Process variables

Process variables are used to store values and pass them between BPMN elements throughout a process instance. The scope of process variables is restricted to a process and not a process definition which is important to consider when modeling with pools in a process definition.

Creating process variables

A process definition without any BPMN element selected will display an Edit Process Variables button in the properties panel. If using pools then the Edit Process Variables button will only appear when a single process is selected. Process variables can be configured using the inbuilt GUI or the JSON editor provided with it.

Each process variable has four properties:

Note: There are four process variable names that are created automatically and should not be used as custom process variable names. nrOfInstances, nrOfActiveInstances, nrOfCompletedInstances and loopCounter are used by multi-instance elements.

The following are the data types that process variables can be set as:

Process variables are stored in the properties of the <process--definition-name>-extensions.json file with unique IDs and can also be viewed through the UI in the Extensions Editor:

The following is an example of an <process-definition-name>-extensions.json file or extensions editor:

{
    "properties": {
        "17aa41f7-9a0c-49c0-805b-045243f8a7e5": {
            "id": "17aa41f7-9a0c-49c0-805b-045243f8a7e5",
            "name": "firstName",
            "type": "string",
            "required": false,
        },
        "2147a4c2-aaf7-44df-a886-d85a7f186445": {
            "id": "2147a4c2-aaf7-44df-a886-d85a7f186445",
            "name": "age",
            "type": "integer",
            "required": true,
            "value": 25
        },
        "887fc645-66ec-4561-8490-e7cc3c8bf0ae": {
            "id": "887fc645-66ec-4561-8490-e7cc3c8bf0ae",
            "name": "accepted",
            "type": "boolean",
            "required": false
        }
    },
}

Process variables can also be declared when starting a process instance.

The following is an example payload for POST rb/v1/process-instances in the runtime bundle:

{
  "payloadType": "StartProcessPayload",
  "processDefinitionId": "Process_MAigMN6p:1:bbfdea14-4907-11ea-9908-deb52b497d16",
        "variables": {
            "area_code": {
                "type": "integer",
                "value": "472"
    },
            "district": {
                "type": "string",
                "value": "North"
    },
            "age" : 50
  }
}

Note: Variables can be declared with or without a type and value. If a type is declared then the value should always be the string representation of the value, for example "472" for an integer in the example rather than 472. If a type is not declared then the engine will attempt to guess it, as in the age example.

Mapping variables

Process variables in a process can be mapped to and from parameters in BPMN elements such as task variables, script variables and decision table values. Input mapping is used to set the process variable sent from the process to the BPMN element and output mapping is used to set the target process variable to receive the results from the BPMN element after it has been executed.

The mapping of variables is stored in the <process-definition-name>-extensions.json file and can also be viewed in the Extensions Editor in the mappings section.

Mapping requires two sets of configuration:

• Variable mapping
• Mapping type

Variable mapping

The variable mapping is used to configure the type of mapping used between a process and its BPMN elements. There are three types of mapping that can be used:

• Process Variables are just regular process variables that must match the type of the source or target parameter. For example an input parameter of type string cannot map to a process variable of type file.

• Expressions: Expressions can be entered using a JSON editor to create more complex mappings such as mapping JSON process variables to input and output parameters. For example, using ${temperature.celsius} will use the value for the object celsius.

      In the following example this would result in the value *16*:
  
      ```json
      {
  "day": "Monday",
  "temperature": {
  

  "celsius": 16, "fahrenheit": 66 } }

      ```
  

• Static Values can be entered rather than using process variables.

Static values and expressions are stored as values in the mappings section of the <process-definition-name>-extensions.json and process variables are stored as variables. For example:

"Task_1f1wpht": {
    "inputs": {
        "flavor": {
            "type": "variable",
            "value": "choice"
            },
        "price": {
            "type": "value",
            "value": "${lookUp.price}"
            },
        "Limit": {
            "type": "value",
            "value": 200
            }
        }
    }
},

Mapping type

There are three options for passing and updating values to and from process variables throughout a process instance:

• Send all variables
• Map variables
• Send no variables

Note: The default behaviour is to send all variables.

Send all variables

Sending all variables passes all variables to and from the BPMN element without explicitly mapping between the process variables and element variables. To send all variables, select the option Send all variables and do not set and input and output mappings.

When sending all variables mapping will be attempted using the name of process variables and the variable names in the BPMN element. If the names are identical then the values will be updated between the variables.

For example, sending the process variables flavor and cost to a user task will create task variables called flavor and cost. If a form field called flavor exists in the user task then it will be updated with the value of flavor from the process variable.

If all variables are sent for a BPMN element then the id of that element will not appear in the mappings section of the <process-definition-name>-extensions.json or Extensions Editor.

Map variables

Mapping variables is to explicitly map individual process variables to variables in the BPMN element. To map variables, select the option Send all variables and set the input and output mappings.

If mapping variables the id of the BPMN element will appear in the mappings section of the <process-definition-name>-extensions.json or Extensions Editor with the inputs and outputs populated with the name or id of the BPMN element variable.

The following is an example of mapping variables for a service task:

{
    "mappings": {
        "ServiceTask_0dfu5w2": {
            "inputs": {
                "nodeId": {
                    "type": "value",
                    "value": "${content.nodeId}"
                }
            },
            "outputs": {
                "num1": {
                    "type": "variable",
                    "value": "alfrescoRequestResponseCode"
                }
            }
        }
    }
}

Send no variables

Sending no variables will not pass any variables between a process instance and its BPMN elements.

If no variables are sent for a BPMN element then the id of that element will be present in the mappings section of the <process-definition-name>-extensions.json or Extensions Editor with empty inputs and outputs.

The following is an example of sending no variables for a user task:

{
    "mappings": {
        "UserTask_0xyu1k8": {
            "inputs": {},
            "outputs": {}
        }
    }
}