Process

The Process service hosts a single process workflow definition.


Process Definition Format

The process definition format is Business Process Modelling and Notation version 2 (BPMN 2), as defined here: https://www.omg.org/spec/BPMN/2.0 .

This plugin supports the following BPMN features:

  • Task
  • Service Task
  • User Task
  • Manual Task
  • Exclusive Gateway
  • JavaScript expressions


Process Definition Editor

Any BPMN 2 editor may be used to create a process definition, including the Linx BPMN editor.

The Red Hat BPMN Editor extension in Visual Studio Code is another good free editor.


Quick Steps

  1. Add Process Automation plugin to your solution.
  2. Drag the Process service onto the Solution Explorer panel.
  3. Set properties for the service. (See below for details.)
  4. Drag required functions and types onto the design canvas of the events and functions that were created for your service when you added the Definition in the previous step.
  5. Click Debug (on top toolbar) to test and debug your solution, or right-click on the service or service event (in the Solution Explorer), then select Debug to specifically test and debug the service.

See the Example section for a detailed explanation of how to use the Process Automation plugin.

Properties

Type

The database type for the process.

Options:

  • MongoDB

  • MySQL

  • PostgreSQL

  • SQL Server

Connection

The database connection string for the process.

Query timeout

The maximum number of seconds to wait for a database query to complete.

Definition

The process definition in BPMN 2 format.

Number of workers

The maximum number of concurrently executing process instances.

Any additional process execution requests will be queued until currently executing process instances have completed.


Example

In this section we will show you how to use the Process service in Linx.

Let’s assume for example that we define the following File Import process:


The underlying format of this process definition in the File Import.bpmn file is XML, as per the BPMN 2 specification.

Download File Import.bpmn.

Launch Linx Designer, create a new solution, and add the Process Automation plugin. Drag a new Process service from the Process Automation plugin into the solution.

Open File Import.bpmn in text mode, copy the definition XML, and paste it into the Definition property of the newly added process.

Linx will create the following events and functions for your task handlers, based on your File Import process definition:


An event handler will be generated for each task in the process definition, in which the implementation of the task is done.

A Complete_Blocking_Task service function is generated for each blocking task in the definition.

In addition, a selection of service functions is generated to start, stop, restart and cancel a process instance, as well as to retrieve process instances and logs from the data store.


Process Data Inputs

When designing a process, it will typically be necessary to define the input data which should be passed to each new instance of the process. For example, the File Import process might have the following data inputs:


Process data inputs may be of type Boolean, Float, Integer, String or Object. If an Object type is used, the property will be a String, containing the JSON of the object instance passed. Custom types are not yet supported.

The StartProcess function of the Process will have a property for each process data input in the definition:


When a new process instance is started, the process data inputs will be added to the list of variables of the process instance.


Tasks

The Process service supports service, user, manual and plain task types. Script, business rule, global/reusable, send and receive task types are not supported.

An event handler will be generated for each task in the process definition, for implementation of the task. The task event handler is named based on the optional Operation property of the task, or if not provided, then the Name property is used.


Task Data Inputs

Typically a task requires data inputs. For example, the Import File task of the File Import process has the following data input:


Task data inputs may be of type Boolean, Float, Integer, String or Object. If an Object type is used, the property will be a String, containing the JSON of the object instance passed. Custom types are not yet supported.

When the Process service executes the task, a value for each data input will be obtained from the current list of process variables. If no variable by the specified name is found, the task will fail.

If a Source is specified for a data input, the value for the data input will be mapped from a process variable by the name specified in Source.

For each task data input specified in the process definition, an input property will be provided in the task event handler in the Linx Designer, under $.Parameters.DataInputs. In addition, the process instance ID and current activity ID are also provided in the task input parameters. For example the Import File event handler input parameters will appear as follows:


Task Data Outputs

A task also typically requires data outputs. For example, the Import File task has the following data outputs:


Task data outputs may be of type Boolean, Float, Integer, String or Object. If an Object type is used, the property will be a String, containing the JSON of the object instance passed. Custom types are not yet supported.

When the Process service executes the task, the value for each data output will be added to the current list of process variables. If a variable with the specified data output name already exists, it will be overwritten.

If a Target is specified for a data output, the value of the data output will be mapped to a process variable by the name specified in Target.

For each task data output specified in the process definition, an output property will be provided in the Return function of the task event handler in the Linx Designer. For example the Import File event handler return properties will appear as follows:


Blocking Tasks

It may happen that a process requires a task that involves a manual intervention, or which involves waiting for an operation from an external system. Such a task is called a blocking task. A blocking task can be defined in a process as follows:

  • If the abovementioned Red Hat BPMN Editor is being used, then set the Is Async property of the task.

  • Alternatively, a task of type User or Manual will also behave as a blocking task.

For example, the Request Approval task of the File Import process is a blocking task:


If a blocking task is reached during the execution of a process instance, the task event handler, together with its input parameters, is invoked in the same way as any other task. However, the blocking task event handler has no return properties. The execution of the process instance will stop, and it’s status will change from Running to Suspended.

To complete the execution of a blocking task, and thereby continue the execution of the process instance, a call must be made to the blocking task’s corresponding Complete_Blocking_Task service function. The Complete_Blocking_Task service function contains the blocking task’s data output properties.

For example, the Request Approval blocking task of the File Import process has the following data inputs and data outputs:


And the Complete_Request_Approval service function will contain properties for the Request Approval task’s data outputs, as well as the corresponding process instance ID, as follows:


The process instance ID is required by the Complete_Blocking_Task service function, to indicate which process instance should be resumed. It is obtained from the output of the StartProcess service function which was used to start the corresponding process instance. When the Complete_Blocking_Task service function is called, it’s data output values will be added to the process instance’s variables, as with the return properties of any other task. Then the execution of the process instance will be resumed.


Gateways

Currently only exclusive gateways are supported. Inclusive and parallel gateways are not yet supported.

For exclusive gateway output sequence flow condition expressions, only JavaScript expressions are supported. No other expression languages are supported.

For example, the output sequence flows of the Import Succeeded gateway in the File Import process, use the Import_Succeeded boolean variable of the process instance, to determine the process flow:


Hosting Model

The Process service definition may contain only one process. Definitions containing multiple processes are not supported.

A Process service can manage the execution of multiple concurrent instances of a given process definition. This contrasts with a workflow server implementation, which would manage multiple different process definitions. To host an additional process definition in Linx, an additional Process service should be created.


Start a Process Instance

To start a new instance of a process, use the StartProcess service function. The StartProcess service function will have an input property for each process data input defined in the process definition, as described in the Process Data Inputs section above. The output of the StartProcess service function is the process instance ID of the newly started process instance.


Complete a Blocking Task

To complete a blocking task, and resume the process instance, use the blocking task’s corresponding Complete_Blocking_Task service function. The Complete_Blocking_Task service function will have an input property for each blocking task data output defined in the process definition, as described in the Blocking Tasks section above. The Complete_Blocking_Task service function has no result properties.


Stop a Process Instance

To stop a running process instance, use the StopProcessInstance service function. The StopProcessInstance service function requires the process instance ID, and a reason which will be logged in the process execution log. The StopProcessInstance service function has no result properties.

Execution of the process instance will be stopped before the beginning of the next activity in the process, and it’s status will change from Running to Suspended.

If a process instance was suspended by one or more blocking tasks at the time that StopProcessInstance was called, and then the corresponding Complete_Blocking_Task service functions are called, they will be handled in terms of updating the process instance variables with the blocking task data output values, but the process instance will not be resumed, until the RestartProcessInstance service function is called.


Restart a Process Instance

To restart a stopped process instance, use the RestartProcessInstance service function. The RestartProcessInstance service function requires the process instance ID, and has no result properties.

Execution of the process instance will be resumed at the beginning of the next activity in the process. It’s status will change from Suspended to Running, unless the process instance was suspended by a blocking task at the time that it was stopped, and no corresponding Complete_Blocking_Task service function was received whilst it was stopped. In that case the process instance will remain suspended until the necessary Complete_Blocking_Task service function resumes it.

The RestartProcessInstance service function can also be used to make an attempt to revive a process instance which has failed, and is therefore in the Faulted state.


Cancel a Process Instance

To cancel a running process instance, use the CancelProcessInstance service function. The CancelProcessInstance service function requires the process instance ID, and a reason which will be logged in the process execution log. The CancelProcessInstance service function has no result properties.

A cancelled process instance cannot be revived.


Retrieve a Process Instance from the Data Store

To retrieve a process instance from the data store, use the GetProcessInstance service function. The GetProcessInstance service function requires the process instance ID. The result of the GetProcessInstance service function is a process instance object with following properties:

  • ID (String)
  • DefinitionID (String)
  • Status (String)
  • CreatedAt (DateTime)
  • LastExecutedAt (DateTime)
  • FinishedAt (DateTime)
  • CancelledAt (DateTime)
  • FaultedAt (DateTime)
  • Variables (List<DataItem>)
  • Faults (List<ProcessFault>)
  • LastExecutedActivityID (String)


Retrieve Process Instances from the Data Store by Specified Criteria

To retrieve a list of process instances from the data store by specified criteria, use the GetProcessInstances service function. The GetProcessInstances service function provides the following filter criteria:

  • ProcessInstanceIDs (List<String>)
  • Statusses (List<ProcessStatus>)
  • HasFaults (Boolean)
  • FaultMessages (List<String>)
  • CreatedAt (List<DateTime>)
  • FinishedAt (List<DateTime>)
  • LastExecutedAt (List<DateTime>)
  • CancelledAt (List<DateTime>)
  • FaultedAt (List<DateTime>)
  • TimeMatchToleranceSeconds (Int32)

The result of the GetProcessInstances service function is a list of process instance objects. See Retrieve a Process Instance from the Data Store for the properties of a process instance object.


Retrieve Process Instance Logs from the Data Store

To retrieve the execution logs for a process instance from the data store, use the GetProcessInstanceLog service function. The GetProcessInstanceLog service function requires the process instance ID. The result of the GetProcessInstanceLog service function is a list of process execution log entry objects, each of which has the following properties:

  • ID (String)
  • ProcessInstanceID (String)
  • Timestamp (DateTime)
  • Message (String)
  • Source (String)
  • ActivityID (String)
  • EventName (String)


Database Support

The Process service has data providers for the following database types:

  • MongoDB
  • SQL Server
  • MySQL
  • PostgreSQL


Failure Recovery

If a Process service fails for any reason, and is then restarted, it will attempt to resume any of it’s process instances which were in the Running state at the time of the failure.

Note that for failure recovery to work, the hosting model assumes that each process definition is hosted uniquely by only one Process service. If more than one Process service hosts the same process definition (that is, having the same definition ID), then the second such Process service which is started up, will incorrectly attempt to resume any Running process instances which were started by the first Process service.



BPMN 2 specification