Gateways can also be used to model concurrency in a process.

The most straightforward gateway to introduce concurrency in a process model is the Parallel Gateway, which allows forking into multiple paths of execution or joining multiple incoming paths of execution.

The functionality of the parallel gateway is based on the incoming and outgoing sequence flow(s):

Note that a parallel gateway does not need to be ‘balanced’ (i.e., a matching number of incoming/outgoing sequence flows for corresponding parallel gateways). A parallel gateway will simply wait for all incoming sequence flows and create a concurrent path of execution for each outgoing sequence flow, not influenced by other constructs in the process model. So, the following process is legal in MSactivator™:

The XOR gateway will let you model a decision in the process.

When the execution arrives at this decision gateway, all outgoing sequence flows are evaluated in the order in which they have been defined. The sequence flow whose condition evaluates to ‘true’ is selected for continuing the process.

To configure the gateway, you need to select the outbound link from the gateway, choose the inbound task and configure the condition to transition to the next BPM task.

Click on "Create" to create a new BPM editor.

Use your mouse to add tasks and link them together.

You can save your BPM at anytime and edit it later. When you save you BPM, you need to select a sub-tenant.

Select an executable task to see the list of workflows (based on the sub-tenant selected), then select a process and provide its input parameters.

If the process you select in a BPM task is a "UPDATE" process (see Workflow design for more details), you’ll have the possibility to select either an existing Workflow instance or use a new instance created by one of the previous BPM task.

This is extremely useful for BPM designers for chaining tasks together.

By default, the BPM execution will stop whenever the associated workflow process execution fails but you may need to make sure that the BPM continues to execute despite the failure. This is typically the case when there is a decision gateway where execution is routed based on the status of the process execution.

To allow the BPM process to continue executing after a workflow process execution fails, you need to edit the BPM task and check "Continue on Failure."

With the execution breakpoint you can create pauses in the BPM flow execution. The BPM process will run, stop and wait for the user to select the breakpoint symbol and click "Continue BPM" to resume it’s execution.

Breakpoints can be used for debugging a complex BPM process without triggering all the workflow and doing a step by step execution. It can also be used to organise a complex BPM into several part and allow for manual validation of each intermediate steps.

The BPM engine will start executing the BPM tasks one by one and the status of the current workflow process execution will be updated live in the view "LATEST EXECUTION RESULT" while the detail of the process execution will be displayed.

BPM are associated to a subtenant in a way which is very similar to workflows, you can manage the instances of BPM executions.

For instance, if you executed a BPM with a breakpoint, you don’t need to leave the BPM execution screen open. You can trigger the execution, close the screen and later, select the instance and open it.

Business Process modeling is used to communicate a wide variety of information to a wide variety of audiences. BPMN is designed to cover many types of modeling and allows the creation of end-to-end Business Processes.

The structural elements of BPMN allow the viewer to be able to easily differentiate between sections of a BPMN Diagram.

The MSactivator™ provides the support for executable BPM Processes.

With the BPM design console, you can design your BPM and connect the BPM elements to Workflows.

The MSactivator™ provides a partial support of the BPMN 2.0 specification and you will be able to use Event and Activities.

will let you specify the beginning and the end of the process execution.

Integration Task will allow you to specify the flow of execution of your BPM.

Use text annotation to add some description to your BPM elements.

Not supported yes

To create a new BPM you need to select "Automation" on the left menu. This will list any BPM available for the current customer.

You can either edit a BPM or create a new one from this screen. Use you mouse to add elements and link them together.

For each task, you need to select a workflow and one of the process from that workflow. The BPM editor will list all the processes defined in a workflow and when the process is selected it will list the variables that are defined in the tasks by the function list_args.

You can save your BPM design anytime and edit it later. The BPM files are stored in the repository under /opt/fmc_repository/Datafiles/<TENANT ID>/<CUSTOMER ID>/bpmn

This tutorial will show you, in a simple way how to create a new BPM and call a Workflow.

It is using the Helloworld example wich is detailed in this documentation: Getting Started Developing Workflows.

As stated above, the BPM tasks can only call Workflow process with the type CREATE. Before creating the BPM, you need to add a new process to the Helloworld workflow and make sure its type is CREATE. This process can have a single task and you can reuse the PHP code from the Helloworld tutorial.

Once this is done, go to the "BPM" section under "Automation" and click on "+ Create BPM".

Add a Task Activity and an End Event.

Click on the task, select the Helloworld workflow, then from the list of process, select the new CREATE process. Provide a value for the parameter name and save the BPM

To test your BPM, click on it’s name from the list of BPM and click on "Execute BPM".

You can check that the workflow process was executed and the message is visible in the processes execution status.

There are 3 main types of workflow processes:

The variables are used to define the current state of a workflow instance, this state is maintained in a context which is persisted in the database.

For each workflow instance, the variable and their values are stored in the database in a context. This context is accessible in read-write mode anytime in the process tasks, in order to store a value of a variable or read a value from a variable.

in Python: read a value from the context

set a value in the context

in PHP: read a value from the context

set a value in the context

The context is persisted in the database and its value is updated after each task execution.

This is how variable values can be passed, during the execution of a process, from one task to another.

Provide the information related to the workflow:

Use "+ Create Variable" to add a variable to this workflow.

A variable can be used to store data in the context of the workflow instance and it can also be used to generate the user input fields when executing a process from the UI.

It is possible to define a variable for "internal" use and decide to keep is hidden from the end-user.

A variable has a name, a type and a display name

This documentation will give you more details on the variables and the various types available.

A workflow can have as many processes as needed. The processes provide the "public" functions exposed by a workflow either with the UI or the REST API.

To create a process, click on the "+" and provide a name and a type (CREATE, UPDATE or DELETE).

Variables are used to hold the parameters to pass to a workflow process. For instance, the port and IP address to block in a firewall policy.

Variables can also be used to display user information that is not necessarily meant to be used for configuring the managed entity.

Setting variables is done from the section "Variables" on the workflow editor screen.

The type of a variable will affect the way the workflow end user form will be rendered.

For instance, the type boolean will render the variable with true/false radio buttons.

When creating or editing a variable, there are some information that need to be provided in the "Default" section.

Depending on the selected type, some advanced parameters may be differ.

To create a variable array, you need to follow a precise naming convention: $params.<ARRAY NAME>.0.<ELEMENT NAME>. The 0, is the separator that will allow the UI and the configuration engine that this variable is an array.

This tutorial walks you through the design and development of your first workflow.

Workflows can be used to automate a wide variety of tasks and processes, such as:

As an example, we’ll use the "Helloworld" workflow. The "Helloworld" workflow will print a name as IN parameter and will display a message to the user ("Hello NAME").

This workflow is composed of 3 processes: one to create the new instance of the workflow, one to enter the name and print it, and one to delete the instance.

This tutorial walks you through the design and development of your first workflow in Python. This tutorial is similar to the Helloworld example in PHP

Workflows can be used to automate a wide variety of tasks and processes, such as:

As an example, we’ll use the "Helloworld" workflow. The "Helloworld" workflow will print a name as IN parameter and will display a message to the user ("Hello NAME").

This workflow is composed of 3 processes: one to create the new instance of the workflow, one to enter the name and print it, and one to delete the instance.

This SDK provides a set of functions to call the MSactivator™ REST API and automate action on the MSactivator™ such as create and activate managed entities, call microservice functions, call processes from other workflows…​

The SDK API documentation is available online on your MSactivator™ instance at: https://localhost/msa_sdk

When developing a workflow you will probably have de define some functions that will be used in multiple tasks.

In order to avoid code duplication and ease the maintenance of your workflow one option is to create a common folder at the same level as your other task folder and create a python file common.py where the shared functions will be defined.

common.py will contain the python code and can also import the Python SDK as well as other Python modules

In the task implementation you need to add the following lines to import this common library

This SDK provides a set of functions that can be used to call the MSactivator™ REST API and automate actions on the MSactivator™ such as create and activate managed entities, call microservice function, call processes from other workflows…​

The SDK functions are implemented in a set of PHP files stored in the MSactivator™ container msa_dev under /opt/fmc_repository/Process/Reference/Common/Library

The PHP files are organised by API topic and contains the functions that are calling the REST API.

These functions can be called directly when implementing the tasks of the workflow processes.

Here is a list of some of the most commonly used functions.

From the developer portal, click on "Create Microservice" to create the microservice.

The microservice console is composed of a vertical menu on the left and a main screen

Microservices are vendor specific, the implementations of the functions to create, update, delete or import a managed entity configuration will depend on the managed entity, the type of remote management interface, the format of the configuration, how it is structured,…​

Variable are usually defined to hold the parameters to be passed to the microservice. For instance, the port and IP to block for a firewall policy. Variables can also be used to display user information that is not meant to be used for configuring the managed entity.

Setting variables is done from the section "Variables" on the microservice editor screen.

When you create a new microservice, the variable object_id, which is mandatory, will be set and cannot be deleted. It can be edited to set it’s type and other advanced properties.

All variables are referenced with the prefix $param which is automatically set in the variable editor screen and when a variable has to be referenced in one of the microservice function, you need to use the syntax {$param.your_variable} (see below for more examples)

By default the type of a variable is String but other types are supported such as Integer, Boolean, Password, IpAddress, ObjectRef,…​

From the left menu of the microservice editor there is a list of functions to implement. While none of the functions are mandatory, at least one of 'Create', 'Update', 'Delete' or 'Import' has to be implemented in oder to have a microservice that can actually do something.

In order to provide a full lifecycle management of a service on a managed entity, the 4 functions above have to be implemented.

The function 'Read', 'List' are optional and while it’s possible to implement them, you’ll have to rely on the REST API to execute them.

The function 'Constraint' allow the implementation of custom constraints to be verified before the managed entity is actually configured.

In most cases, the constraint definition is straight forward when defining a microservice variable. Based on the type of the variable, the UI will check if the provided value is consistent with the type. For example if the type is "IP Address", the format of the value should be an IP address.

In some cases, though, the constraint is more complex and may depend on a combination of several conditions that can involve multiple variables.

For example, the 5 variables params.av, params.webfilter, params.spamfilter, params.ips, and params.scanport have the following dependencies:

To make things simpler, it is possible to add a custom constraint evaluation to the object definition.

The custom constraint is implemented as a smarty template:

XML microservice are used to manage entities that expose a REST API that return a response formatted in XML or for Adapter that are not supporting JSON microservice and JsonPath.

To create a XML microservice, you need to check XML for the configuration type when creating a new microservice

JSON microservice are used to manage entities that expose a REST API that returns a response formatted in JSON.

To create a JSON microservice, you need to check JSON for the configuration type when creating a new microservice.

The Microservice API is made of several functions that can be implemented. It is not mandatory to implement all the functions, this will depend on your requirements and can be done incrementally.

Below you’ll find some example of CLI based configuration and the regex that can be used to extract the variables.

These are only provided as example and you may have to modify them to match you needs.

To help with testing and validating your regular expression, there are many online tools. We, at UBiqube, usually use this one: https://regexr.com/3bhgg

The variables are usually defined to hold the parameters to be passed to the microservice. For instance, the port and IP address variables to block for a firewall policy. Variables can also be used to display user information that is not meant to be used for configuring the managed entity.

Setting different types for variables will affect the way the microservice end user form, for creating or updating it, will render.

For instance, the type boolean will render the variable with true/false radio buttons.

When creating or editing a variable, there are some information that need to be provided in the "Default" section.

Depending on the selected type, some advanced parameters may be differ.

To create a variable array, you need to follow a precise naming convention: $params.<ARRAY NAME>.0.<ELEMENT NAME>. The 0, is the separator that will allow the UI and the configuration engine that this variable is an array.

This type of variables should be used when extracting configuration with an array variable extractor in the Import function of the microservice.

The Smarty templates are used to generate output using variables and control structures like if/then/else conditional branches or for/each loops.

The output is used to configure the managed entities or retrieve data from the database.

Whether you are developing a CLI or and XML (REST) based microservice, the CoreEngine will rely on parameter substitution to generate the configuration or the call to the REST API.

The parameters, coming from the web UI or the REST API are passed to the template engine as a JSON payload.

For ClI microservices, the parameters, extracted from the JSON payload will be used to generate the piece of configuration to apply to the managed entity (this is the role of the adapter).

For XML/REST, the parameters are used to build the REST API call, either by updating the path and/or by updating the payload

This tutorial explores the design and development of a Microservice.

Microservices can be used to manage a wide variety of services on numerous types of devices, such as:

The first step in Microservice design and development is to have a device to manage.

This tutorial assumes you have a properly configured, running MSactivator™.

If you have followed the quickstart guide you should have a running MSactivator™ with a Linux managed entity, created and activated.

As a first example of Microservices, we will start with managing this Linux Managed Entity.

On Linux, the CLI command to list the users is: cat /etc/passwd.

To create a new user use the command: useradd

and to delete a user use the command: userdel.

The list of users in /etc/passwd contains the system users that we want to exclude from the scope of the Microservice. We will cover this later in this tutorial.

With this simple implementation you can manage users on a Linux system, but there are some additional use cases that you may want to address:

Use the following method to trigger OrderCommand (Microservices) methods present at the following URL:

As shown above, the http body contains what’s called "object parameters" in general.

This documentation describes the order stack management API.

This REST API is also used internally by the MSactivator™ portal.

Each API is described below with the REST call, a textual description, the parameters and a section 'detail'. The 'detail' section provides some insight into the inner workings of the API. For instance, what is the database table impacted or what CoreEngine API command is being used.

The detail on the CoreEngine API command is very important because it is directly related to the adaptor implementation for a specific vendor.

Some adapters were designed to be generic in order to have little dependencies with a specific vendor.

This is the case for the REST and the Linux adapters.

but you may want to also have the vendor name and entity model both appear in the list of supported vendor instead of REST/Generic or Linux/Generic.

Doing so will allow you to filter the microservice and deployment setting based on the vendor name and model name.

This will ease the organization of your integration files.

Let’s assume that you want to add vendorA / modelX to the list of supported vendors.

You will need an access to the MSactivator™ CLI of the msa_dev container.

It is possible to implement new custom commands that will be callable from the MSactivator™ API (verb JSACMD MY_COMMAND).

The MSactivator™ CoreEngine daemon in charge of polling the device for availability is polld.

By default, polling is using ping, and for scalability and performance reasons the polling mechanism is implemented in the C programming language. This allows the MSactivator™ to poll several hundreds of managed entities per minute. For the devices that don’t support ping, or in case the polling has to be customized, it is possible to implement a custom polling in a php script:

On Stormshield the connection to the device is tested as shown below

The MSactivator™ CoreEngine can connect on a managed entity to fetch a set of predefined assets such as:

The specific model script retrieves information (via CLI, snmp, REST calls…​) into an array. The array is then passed to a specific callback in order to store the information in the database.

It is also possible to extract custom assets. They will be stored in the database as a list of key values.

The asset mngt module uses regular expressions to extract the asset from the configuration.

These values are stored in a database that keeps the asset history.

The asset script is device specific and is located in:

Regexp:

The regexp is executed against the result of the CLI : get system status.

Regexp: