# 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](https://bpmn-editor.linx.software/).
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 the 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](#example) section for a detailed explanation of how to use the **Process Automation** plugin.
***
## Properties
## Type
The database type for the process.
Options:
* SQL Server
* SQLite
* MySQL
* PostgreSQL
* MongoDB
### Connection
The database connection string for the process.
**Example Connection Strings**
#### SQL Server
> `Data Source=;Initial Catalog=;Integrated Security=;User ID=;Password=;TrustServerCertificate=True;`
#### SQLite Example
> `Data Source=C:\MySQLiteDB.db;`
#### MySQL
> `Server=myServerAddress;Database=myDataBase;Uid=myUsername;Pwd=myPassword;`
#### PostgreSQL
> `Server=serverName\instanceName;Database=MyPostgresDB;User Id=MyUser;Password=myPassword;`
#### MongoDB
*Note: You need to specify the database to create the objects to.*
When connecting to Local MongoDB:
> `mongodb+srv://MyUser:MyPassword@cluster0.example.mongodb.net/MyDatabase`
When connecting to a MongoDB on a server:
> `mongodb+srv://MyUser:MyPassword@cluster0.example.mongodb.net/MyDatabase`
[Read more on MongoDB Connection Strings](https://www.mongodb.com/docs/manual/reference/connection-string/?msockid=392e36fcd07967b83bb6253fd15a662e)
### 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.
{% file src="/files/Blplccb09Gr7gVGPGcdk" %}
Download File
{% endfile %}
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 the implementation of the task. The task event handler is named based on the optional *Operation* property of the task; 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 Linx Designer. 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 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 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 its 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, its 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](#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](#blockingtasks) 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 its 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. Its 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 the following properties:
* ID (String)
* DefinitionID (String)
* Status (String)
* CreatedAt (DateTime)
* LastExecutedAt (DateTime)
* FinishedAt (DateTime)
* CancelledAt (DateTime)
* FaultedAt (DateTime)
* Variables (List)
* Faults (List)
* 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)
* Statusses (List)
* HasFaults (Boolean)
* FaultMessages (List)
* CreatedAt (List)
* FinishedAt (List)
* LastExecutedAt (List)
* CancelledAt (List)
* FaultedAt (List)
* 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](#retrieveprocessinstance) for the properties of a process instance object.
***
### 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 the following properties:
* **ID** (String)
* **DefinitionID** (String)
* **Status** (String)
* **CreatedAt** (DateTime)
* **LastExecutedAt** (DateTime)
* **FinishedAt** (DateTime)
* **CancelledAt** (DateTime)
* **FaultedAt** (DateTime)
* **Variables** (List)
* **Faults** (List)
* **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)
* **Statusses** (List)
* **HasFaults** (Boolean)
* **FaultMessages** (List)
* **CreatedAt** (List)
* **FinishedAt** (List)
* **LastExecutedAt** (List)
* **CancelledAt** (List)
* **FaultedAt** (List)
* **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](#retrieve-a-process-instance-from-the-data-store) for the properties of a process instance object.
***
### Database Support
The **Process** service has data providers for the following database types:
* MongoDB
* SQL Server
* MySQL
* PostgreSQL
***
### ProcessInstance Statuses
* Idle: New. Waiting to be picked up by a worker.
* Running: Executing.
* Finished: Completed.
* Suspended: Async tasks are in this state when the task waits to resume. Calling StopProcessInstance also puts Running instances in this state.
* Faulted: A task failed; it can be resumed or cancelled.
* Cancelled: Was cancelled before it could finish.
When a Task is running, its LastExecutedActivity is the preceding Task, which can also be a Start or Gateway Task.
When a Task marked as async completes the Task event, it goes into Suspended mode until the Complete\_Task function is called.
***
### Failure Recovery
If a **Process** service fails for any reason and is then restarted, it will attempt to resume any of its process instances that 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.
***
## Links
[BPMN 2 specification](https://www.omg.org/spec/BPMN/2.0)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.linx.software/reference/plugins/processautomation/content/process.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.