Chapter 6. Variables

Variables store data that is used during runtime. Process designer uses three types of variables:

Global variables

Global variables are visible to all process instances and assets in a particular session. They are intended to be used primarily by business rules and by constraints and are created dynamically by rules or constraints.

Process variables

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 completion.

Local variables

Local variables are associated with and available within specific process elements, such as activities. They are initialized when the element context is initialized, that is, when the execution workflow enters the node and execution of the onEntry action has finished, if applicable. They are destroyed when the element context is destroyed, that is, when the execution workflow leaves the element.

An element, such as a process, sub-process, or task can only access variables in its own and parent contexts. An element cannot access a variable defined in the element’s child element. Therefore, when an elements requires access to a variable during 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 until the process context is reached. In case of global variables, 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.

6.1. Variable tags

For greater control over variable behavior, you can tag process variables and local variables in the BPMN process file. Tags are simple string values that you add as metadata to a specific variable.

Red Hat Process Automation Manager supports the following tags for process variables and local variables:

  • required: Sets the variable as a requirement in order to start a process instance. If a process instance starts without the required variable, Red Hat Process Automation Manager generates a VariableViolationException error.
  • readonly: Indicates that the variable is for informational purposes only and can be set only once during process instance execution. If the value of a read-only variable is modified at any time, Red Hat Process Automation Manager generates a VariableViolationException error.

  • restricted: A special tag that is used with the VariableGuardProcessEventListener to indicate that permission is granted to modify the variable based on the required and the existing role.

    VariableGuardProcessEventListener is extended from DefaultProcessEventListener and supports two different constructors:

    • VariableGuardProcessEventListener 

      public VariableGuardProcessEventListener(String requiredRole, IdentityProvider identityProvider) {
    this("restricted", requiredRole, identityProvider);
}

    • VariableGuardProcessEventListener 

      public VariableGuardProcessEventListener(String tag, String requiredRole, IdentityProvider identityProvider) {
    this.tag = tag;
    this.requiredRole = requiredRole;
    this.identityProvider = identityProvider;
}

      Therefore, you must add an event listener to the session with the allowed role name and identity provider that returns the user role as shown in the following example: 

      ksession.addEventListener(new VariableGuardProcessEventListener("AdminRole", myIdentityProvider));

    In the previous example, the VariableGuardProcessEventListener method verifies if a variable is tagged with a security constraint tag (restricted). If the user does not have the required role, then Red Hat Process Automation Manager generates a VariableViolationException error.

Note

The variable tags that appear in the Business Central UI, for example internal, input, output, business-relevant, and tracked are not supported in Red Hat Process Automation Manager.

You can add the tag directly to the BPMN process source file as a customTags metadata property with the tag value defined in the format ![CDATA[TAG_NAME]].

For example, the following BPMN process applies the required tag to an approver process variable:

Figure 6.1. Example variable tagged in the BPMN modeler

Image of variable tags in BPMN modeler

Example variable tagged in a BPMN file

<bpmn2:property id="approver" itemSubjectRef="ItemDefinition_9" name="approver">
  <bpmn2:extensionElements>
    <tns:metaData name="customTags">
      <tns:metaValue><![CDATA[required]]></tns:metaValue>
    </tns:metaData>
  </bpmn2:extensionElements>
</bpmn2:property>

You can use more than one tag for a variable where applicable. You can also define custom variable tags in your BPMN files to make variable data available to Red Hat Process Automation Manager process event listeners. Custom tags do not influence the Red Hat Process Automation Manager runtime as the standard variable tags do and are for informational purposes only. You define custom variable tags in the same customTags metadata property format that you use for standard Red Hat Process Automation Manager variable tags.

6.2. Defining global variables

Global variables exist in a knowledge session and can be accessed and are shared by all assets in that session. They belong to the particular session of the Knowledge Base and they are used to pass information to the engine. Every global 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.

Important

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

Global variables are initialized either when the process with the variable definition is added to the session or when the session is initialized with globals as its parameters.

Values of global variables can typically be changed during the assignment, which is a mapping between a process variable and an activity variable. The global variable is then associated with the local activity context, local activity variable, or by a direct call to the variable from a child context.

Prerequisites

  • You have created a project in Business Central and it contains at least one business process asset.

Procedure

  1. Open a business process asset.
  2. Click a blank area of the process designer canvas.
  3. Click the Properties icon on the upper-right side of the screen to open the Properties panel.
  4. If necessary, expand the Process section.
  5. In the Global Variables sub-section, click the plus icon.
  6. Enter a name for the variable in the Name box.
  7. Select a data type from the Data Type menu.

6.3. Defining process variables

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 completion.

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 a 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.

Note that process variables should be mapped to local variables.

Prerequisites

  • You have created a project in Business Central and it contains at least one business process asset.

Procedure

  1. Open a business process asset.
  2. Click a blank area of the process designer canvas.
  3. Click the Properties icon on the upper-right side of the screen to open the Properties panel.
  4. If necessary, expand the Process Data section.
  5. In the Process Variables sub-section, click the plus icon.
  6. Enter a name for the variable in the Name box.
  7. Select a data type from the Data Type menu.

6.4. Defining local variables

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 has 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. This enables you to maintain relative independence of the parent element that accommodates the local variable. Such isolation might help prevent technical exceptions.

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, you can define Data Input Assignments and Data Output Assignments in the Assignments property. Data Input Assignment defines variables that enter the Task and therefore provide the entry data needed for the task execution. The Data Output Assignments can refer to the context of the Task after execution to acquire output data.

User Tasks present data related to the actor that is executing the User Task. Additionally, User Tasks also request the actor to provide result data related to the execution.

To request and provide the data, use task forms and map the data in the Data Input Assignment parameter to a variable. Map the data provided by the user in the Data Output Assignment parameter if you want to preserve the data as output.

Prerequisites

  • You have created a project in Business Central and it contains at least one business process asset that has at least one task that is not a script task.

Procedure

  1. Open a business process asset.
  2. Select a task that is not a script task.
  3. Click the Properties icon on the upper-right side of the screen to open the Properties panel.
  4. Click the box under the Assignments sub-section. The Task Data I/O dialog box opens.
  5. Click Add next to Data Inputs and Assignments or Data Outputs and Assignments.
  6. Enter a name for the local variable in the Name box.
  7. Select a data type from the Data Type menu.
  8. Select a source or target then click Save.