How to Create and Configure a Microservice

Objects definition Management

Locating the Object Definitions

In the repository

The objects definitions are stored in the repository under the CommandDefinition folder.

OBMF_object_definition_1 OBMF_object_definition_2.png

Editing the object definition is done using the contextual menu (right click on the file name)

OBMF_object_definition_6.png

From the files associated to a device

OBMF_object_definition_4a.png OBMF_object_definition_4.png

In read/write mode

Like in the repository, the modification of the object definition is done with contextual menu (right click on the file name).

OBMF_object_definition_5.png

To create a new Object Definition

See TODO OBMF_Principles#Configuration_Objects_management for more information on the object definition structure.

Objects definitions are created using the specific icon in the repository tree.

OBMF_object_definition_3.png

When creating an object definition, an example of configuration can be provided to ease the design of the object. Note that the file is required to have the .xml extension.

OBMF_object_definition_7.png

You will be automatically redirected to the Object Definition editor.

OBMF_object_definition_8.png

Now you can start configuring your object definition.

Icon

The icon is used in the navigation tree

OBMF_information_icon.png

Display Name

The display name is displayed in the console

OBMF_information_display_name.png

Description

The description is displayed as a tool tip in the console

OBMF_information_description.png

Object Category

In order to store the objects in hierarchical categories, the category definition has to be a '|' (pipe) separated list of names.

OBMF_object_definition_8-1.png

The result in the object management console is:

OBMF_object_definition_8-2.png

Object Name Variable

This is the name of the variable to represent the object in lists. By default this is object_id, but some time another more user-friendly name has to be displayed.

OBMF_information_obj_name_var_1.png OBMF_information_obj_name_var_2.png OBMF_information_obj_name_var_3.png OBMF_information_obj_name_var_4.png

Rank in category

The rank in category is use to sort the navigation tree: The rank is used to sort the groups and after that, within a group, the objects are sorted using the rank too.

OBMF_information_rank_in_cat.png

Import Rank

If a object is referenced in the post-import section of an other object then it's import rank should be lower in order to save it into the database. The post-import sections can only refer to database values when referring another object.

If a object is referenced in the post-import section of an other object then it's import rank should be lower in order to save it into the database. The post-import sections can only refer to database values when referring another object.

Object Variables

Definition

The variables are used by the commands to import or generate configuration for the equipment.
All the variables of the object start with the prefix "params." A special variable called the object. The object ID can be represented by various values of the configuration, and generally it is the name of the object. For example, for the object interface the ID can be the name of the interface.

The variables can be organized in arrays. The name of the variables uses then the following convention: "params.array_name.0.subvar1", "params.array_name.0.subvar2"... for variables in the array array_name.

The variables can be created from this tab, but are also extracted from the different commands (IMPORT, CREATE, UPDATE, DELETE). If a variable is not necessary in the Object Management Console then it can be hidden using the visibility flag.

WARNING The name of a variable that's use in IMPORT part must not exceed 32 characters because of restrictions due to PHP.

The variables are presented in a tab like this:

OBMF_object_definition_10.png

The advanced parameters are:

OBMF_object_definition_10-1.png

when grouping variables:

OBMF_object_definition_10-2.png

And the second variable:

OBMF_object_definition_10-3.png

and the result is:

OBMF_object_definition_10-4.png

and when editing the object the variables are kept separated:

OBMF_object_definition_10-5.png

There are some actions available for the variables:

Micro Service Reference

The type of the variable can be selected to ensure controls in the Micro Service Management Console. A specific type is Micro Service Reference, it is used to reference another Micro Service ID. For example, a firewall policy Micro Service can reference interface Micro Service. For variables of the type Micro Service Reference a list of existing Micro Services is proposed in the Micro Service Management Console for that variable.

OBMF_object_definition_12.png OBMF_object_definition_13.png

The object in the Object Management Console:

OBMF_object_definition_14.png

Composite

The type Composite is used to allow different behaviors for a given variable depending on the values of another value.

For example when an ACL rule action is Permit then the user must specify an IP address and a mask. If the ACL rule action is Deny then the IP address and mask fields should not be displayed to the user.

OBMF_object_definition_Composite_1.png OBMF_object_definition_Composite_2.png OBMF_object_definition_Composite_3.png OBMF_object_definition_Composite_4.png OBMF_object_definition_Composite_5.png OBMF_object_definition_Composite_6.png OBMF_object_definition_Composite_7.png OBMF_object_definition_Composite_8.png

Link

The Link type is used to add a static URL to be clicked by the user within an object.

ImOBMF_object_definition_Link_1 OBMF_object_definition_Link_2.png OBMF_object_definition_Link_3.png OBMF_object_definition_Link_4.png

Device

The Device type is used to allow the user to select a device existing in the MSA database according to her rights and the manufacturer and models selected.

OBMF_object_definition_Device_1.png OBMF_object_definition_Device_2.png OBMF_object_definition_Device_3.png

Unique Value

The Unique Value type is used to allow the user to select a predefined value only once within an array or between multiple variables or between multiple Micro Services instances.

OBMF_object_definition_Unique_Value_1.png OBMF_object_definition_Unique_Value_2.png OBMF_object_definition_Unique_Value_3.png

CRUD Methods

Please refer to the following example for details on the Create Read Update Delete and Import methods.

IMPORTANT NOTE for the Delete method.

Most of the time you just have to use the object_id param to delete an object instance. How ever in some case you may need to use additional parameters in the Delete method. In that case you MUST use the following naming convention for the variables in that Delete method: {$objectname.$object_id.variablename}

This naming convention is mandatory. If you simply use {$params.variablename} then the variable value will be empty as the delete removes thevalues prior to the stack execution. The {$objectname.$object_id.variablename} allows you to get the values stored in the history.

For example:

no ip route {$route.$object_id.subnet} {$route.$object_id.mask} {$route.$object_id.interface} {$route.$object_id.gateway} {$route.$object_id.metric}

While using microservices, you can do different actions:

  • Import: It converts device configuration into a micro service.
  • Create: It creates a micro service for a device.
  • Update: It allows to modify, from the user's MSA, the device configuration and database.
  • Delete: It erases a device configuration of a micro service.

Import

Variables and arrays of variables are found thanks to regex (Example: @ regex @).
@ symbol is written at the beginning and the end of regex. @ symbol has been chosen because it is a ASCII symbol and it is one of the rarest symbol in configurations.
Import screen is splitted in 3 parts.

Command to run on the device

In order to run more than one command, you can use ##.

Double_command2.png

Configuration parser

  • 1. Micro service identifier extractor

The regex are written in order to find the object_id, which is the micro service unique identifier.

Routing_import_objectID.png
  • 2. Micro service variables extractor

Regex find usefull variables or arrays according to the configuration. An example of configuration is available on 'Example'.

Routing_import_variables.png
  • 3. Ignore lines parsers

Information which are not used are ignored.

Routing_import_ignore.png

Be careful: You have to write a regex that matches each line of the micro service (by extracting or ignoring) except for the last line which is often next or end.
If you forget a line with regex, the micro service will be created without all information.
If you write a regex that matches the last line of your micro service, it will not be well defined.
Be careful: While writing a regex, blank spaces are very important. For instance, @end@ is different from @ end@.

Post import operations

This field is often blank. It is a script launch after the import in order to modify variables for the micro service in function of itself or other micro services.