Process variables are data containing information on a process instance. The following process variables are included in every process instance:

Using other process variables

You can use these variables for special purposes:

In the process definition, you can define variables that are used within a process. Defined variables can be automatically validated and, if necessary, converted at the appropriate interfaces of the application.

You can define the following variables within a process:

A variable definition contains the following information:

For data type Number the following restrictions apply:

The non-primitive data types use the following notation:

Variables are defined as a BPMN extension in the form of Camunda properties. In the BPMN model, you define general process and service variables directly in the process node. You define local process variables in the node of the activity in which they are to apply.

General process and service variables

 <process id="myProcess" name="Process with variable declaration" isExecutable="true">
    <extensionElements>
        <camunda:properties>
            <camunda:property name="variable:myVariable" value="[String]!" /> <!-- Name: "myVariable", Type: "String", Multiple: true, Mandatory: true, Startvariable: false -->
            <camunda:property name="variable:myStartVariable*" value="String" /> <!-- Name: "myStartVariable", Type: "String", Multiple: false, Mandatory: false, Startvariable: true-->
            <camunda:property name="variable:someUserTaskOutput" value="String" /> <!-- Name: "someUserTaskOutput", Type: "String", Multiple: false, Mandatory: false, Startvariable: false -->
            <camunda:property name="service:/myservice:in:input" value="String!" /> <!-- Name: "input", Type: "String", Multiple: false, Mandatory: true -->
            <camunda:property name="service:/myservice:out:output" value="Number!" /> <!-- Name: "output", Type: "Number", Multiple: false, Mandatory: true -->
        </camunda:properties>
    </extensionElements>
</userTask>

Local process variable

<userTask id="userTask" name="User Task">
    <extensionElements>
        <camunda:inputOutput>
            <camunda:inputParameter name="someInput">user task input which is only available within this user task scope</camunda:inputParameter>
            <camunda:outputParameter name="someUserTaskOutput">user task output which will be written to process scope</camunda:outputParameter>
        </camunda:inputOutput>
        <camunda:properties>
            <camunda:property name="variable:someInput" value="String" />
        </camunda:properties>
    </extensionElements>
</userTask>

When modeling your own processes, you can use process variables to create dynamic processes. When getting started with process variables, it is useful to create a simple process with one user activity first. This process will e.g. look like this:

The BPMN of this sample process is structures as follows. To simplify the example, the graphic information on the BPMN diagram is not included in this BPMN sample file.

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:camunda="http://camunda.org/schema/1.0/bpmn" targetNamespace="" exporter="d.velop process modeler">
  <process id="GettingStarted" name="Beispiel: Einstieg" isExecutable="true">
    <startEvent id="start"/>
    <userTask id='task_hello_world' name='Hello World' camunda:candidateUsers="${variables.get('dv_initiator')}" />
    <sequenceFlow id="s1" sourceRef="start" targetRef="task_hello_world" />
        <sequenceFlow id="s2" sourceRef="task_hello_world" targetRef="end" />
    <endEvent id="end"/>        
  </process>  
</definitions>

Now add a new variable definition to this process definition.

Adding a variable definition

To be able to use a process variable, you need to add it to the process definition. In the process definition, you add the BPMN items extensionElements and camunda:properties to the BPMN item process. To define the process variable, then add the item camunda:property to the BPMN item camunda:properties.

This example shows how to add the variable message of data type String:

<process id="GettingStarted" name="Beispiel: Einstieg" isExecutable="true">
        <extensionElements>
      <camunda:properties>
        <camunda:property name="variable:message" value="String" />
      </camunda:properties>
    </extensionElements>
        ...
</process>

Explanation of the properties

Using the process variable

You can now use the variable message for the name of the user activity, so that this name is displayed to the user in the task list. To do so, replace the existing test in the property name of the user activity with the method for access to the variable message:

<process id="GettingStarted" name="Beispiel: Einstieg" isExecutable="true">
        ...
        <userTask id="task_hello_world" name="${variables.get('message')}" camunda:candidateUsers="${variables.get('dv_initiator')}" />
        ...

You can now define the value of the variable e.g. for the start of the process.

Process variables always have a specific scope within a process instance. Depending on the scope, read and write access will be possible.

In every process instance, there is a universal scope which comprises the entire process. All other scopes, such as user or service activities, have read access to the variables in the universal scope.

Additional scopes are generated at the following points:

Read access

Read access to process variables (e.g. the use in an expression) is possible independently of the scope. If no value is found in the current scope, the section above it is searched until a value has been found.

Write access

If you want to change values (e.g. in a user activity with output mapping), the value is always applied to the current scope. Other scopes, e.g. along other branches in the process, are not impacted by this until the end of this scope. The changes are transferred to all other scopes only at the end of the current scope.

End of scopes

At the end of a scope (e.g. when joining parallel branches or at the end of a subprocess), the variables of this scope are discarded. You must configure an output mapping before you can apply variables to a scope located higher in the hierarchy. In the process, the call hierarchy is run through until a scope that already contains this variable is found. This run starts from the current item and works its way towards the top. The new value is then applied to this scope. If the variable is completely new, it is then written to the scope of the entire process.

Impact on process monitoring

The view of a token always shows the variables of the current scope. Changes to the variables are only applied in this scope.

Most tokens have their own scope. The only exception are user activities for which no input/output mapping was configured and which are not executed in parallel to other activities. Theses tokens have the same scope as the token directly above them.

In the view of the token without its own scope, you can find a link to a token from the section above it. When you select this link, you can view the variables of the linked scope.