4.8. Variables

Variables are elements that serve for storing a particular type of data during runtime. The type of data a variable contains is defined by its data type.
Just like any context data, every variable has its scope that defines its "visibility". An element, such as a Process, Sub-Process, or Task can only access variables in its own and parent contexts: variables defined in the element's child elements cannot be accessed. Therefore, when an elements requires access to a variable on runtime, its own context is searched first. If the variable cannot be found directly in the element's context, the immediate parent context is searched. The search continues to "level up" until the Process context is reached; in case of Globals, the search is performed directly on the Session container. If the variable cannot be found, a read access request returns null and a write access produces an error message, and the Process continues its execution. Variables are searched for based on their ID.
In Red Hat JBoss BPM Suite, variables can live in the following contexts:
  • Session context: Globals are visible to all Process instances and assets in the given Session and are intended to be used primarily by business rules and by constrains. The are created dynamically by the rules or constrains.
  • Process context: Process variables are defined as properties in the BPMN2 definition file and are visible within the Process instance. They are initialized at Process creation and destroyed on Process finish.
  • Element context: Local variables are available within their Process element, such as an Activity. They are initialized when the element context is initialized, that is, when the execution workflow enters the node and execution of the OnEntry action finished if applicable. They are destroyed when the element context is destroyed, that is, when the execution workflow leaves the element.
    Values of local variables can be mapped to Global or Process variables using the Assignment mechanism (refer to Section 4.11, “Assignment”). This allows you to maintain relative independence of the parent Element that accommodates the local variable. Such isolation may help prevent technical exceptions.

4.8.1. Globals

A global is a variable that exists in a Knowledge Session and can be accessed and is shared by all assets in that Session. Globals belong to the particular Session of the Knowledge Base: they are used to pass information to the engine.
Every global defines its ID and item subject reference: the ID serves as the variable name and must be unique within the Process definition. The item subject reference defines the data type the variable stores.

Important

The rules are evaluated at the moment the fact is inserted. Therefore, if you are using a Global to constraint a fact pattern, and the global is not set, the system returns a NullPointerException.

4.8.1.1. Creating Globals

Globals are initialized when the Process with the variable definition is added to the Session or when the Session is initialized with Globals as its parameters. Their value can be changed by the Process Activities using the Assignment, when the global variable is associated with the local Activity context, local Activity variable, or by a direct call to the variable from a child context.

Procedure 4.4. Defining a Global in the Process Designer

To define a Process variable, do the following:
  1. Open the Process in the Process Designer.
  2. In the Properties panel of the BPMN Diagram expand the Extra item.
  3. Click the empty value cell next to the Globals and click the arrow.
    Globals area for the BPMN-Diagram in BPMS 6.0.2

    Figure 4.22. Global properties cell

  4. In the Editor for Variable Definitions window, click the Add Variable button and define the variable details.
    Editor for Variable Definitions in BPMS 6.0.2

    Figure 4.23. Editor for Variable Definitions

Procedure 4.5. Defining and Initializing a Global using the API

To define and initialize global variables at process instantiation using API, do the following:
  1. Define the variables as a Map of the <String, Object> values.
  2. Provide the map as a parameter to the startProcess() method.

Example 4.2. Code instantiating a Process with a Global

Map<String, Object> params = new HashMap<String, Object>();
params.put("var", "variable value");
ksession.startProcess("Process Definition Name", params);

4.8.1.2. Accessing Globals

processInstance.getContextInstance().getVariable("globalStatus")

4.8.1.3. Process variables

A Process variable is a variable that exists in a Process context and can be accessed by its Process or its child elements: Process variables belong to the particular Process instance and cannot be accessed by other Process instances. Every Process variable defines its ID and item subject reference: the ID serves as the variable name and must be unique within the Process definition. The item subject reference defines the data type the variable stores.
Process variables are initialized when the Process instance is CREATED. Their value can be changed by the Process Activities using the Assignment, when the global variable is associated with the local Activity context, local Activity variable, or by a direct call to the variable from a child context .

4.8.2. Local variables

A local variable is a variable that exists in a child element context of a Process and can be accessed only from within this context: local variables belong to the particular element of a Process.
For Tasks, with the exception of the Script Task, the user can define local variable in the DataInputSet and DataOutputSet parameters: DataInputSet define variables that enter the Task and therefore provide the entry data needed for the Task execution, while the DataOutputSet variables can refer to the context of the Task after execution to acquire output data.
User Tasks typically present data related to the User Task to the actor that is executing the User Task and usually also request the actor to provide result data related to the execution. To request and provide such data, you can use Task forms and map the acquired data into the DataInputSet parameter to serve as input data of the User Task and into the DataOutputSet parameter from the User Task namespace back to the parent namespace to serve as the User Task output data (refer to Section 4.11, “Assignment”).

Note

Local variables are initialized when the Process element instance is CREATED. Their value can be changed by their parent Activity by a direct call to the variable.

4.8.2.1. Accessing local variables

To set a variable value, call the respective setter on the variable field from the Script Activity; for example, person.setAge(10) sets the Age field of the person global variable to 10.