jBPM Process Variables

Chapter 7. Variables

7.1. Variable scoping

7.2. Variable types

7.3. Updating serialized process variables

7.4. Declared variables

7.5. Variables history

Process variables can be accessed from outside the process with methods from the ExecutionService:

• ProcessInstance startProcessInstanceById(String processDefinitionId, Map<String, Object> variables);
• ProcessInstance startProcessInstanceById(String processDefinitionId, Map<String, Object> variables, String processInstanceKey);
• ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map<String, ?> variables);
• ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map<String, ?> variables, String processInstanceKey);
• void setVariable(String executionId, String name, Object value);
• void setVariables(String executionId, Map<String, ?> variables);
• Object getVariable(String executionId, String variableName);
• Set<String> getVariableNames(String executionId);
• Map<String, Object> getVariables(String executionId, Set<String> variableNames);

And from inside the process with methods from Execution interfaces passed to user code like ActivityExecution and EventListenerExecution:

• Object getVariable(String key);
• void setVariables(Map<String, ?> variables);
• boolean hasVariable(String key);
• boolean removeVariable(String key);
• void removeVariables();
• boolean hasVariables();
• Set<String> getVariableKeys();
• Map<String, Object> getVariables();
• void createVariable(String key, Object value);
• void createVariable(String key, Object value, String typeName);

jBPM doesn't have a mechanism for detecting changes automatically to variable values. So if you get e.g. a serializable collection from the process variables and add an element, then you need to set the changed variable value explicitely for the changes to be saved to the DB.

7.1. Variable scoping

By default variables are created in the top level process instance scope. This means they are visible and accessible in all the paths of execution of the whole process instance. Process variables are created dynamically. Meaning that a variable is created the first time it is set through one of these methods.
Each execution is a variable scope. Variables declared in a nested execution level will 'see' their own variables and variables declared in parent executions according to the normal scoping rules. With the createVariable methods in the execution interfaces ActivityExecution and EventListenerExecution, execution-local variables can be created.
In one of the future releases, we might add variable declaration in the jPDL process language.

7.2. Variable types

jBPM supports following Java types as process variables:

• java.lang.String
• java.lang.Long
• java.lang.Double
• java.util.Date
• java.lang.Boolean
• java.lang.Character
• java.lang.Byte
• java.lang.Short
• java.lang.Integer
• java.lang.Float
• byte[] (byte array)
• char[] (char array)
• hibernate entity with a long id
• hibernate entity with a string id
• serializable

For persistence of these variable, the type of the variable is checked in the order of this list. The first match will determine how the variable is stored.

7.3. Updating serialized process variables

(Since jBPM 4.3)
In customs, event-handlers and other user code, you can retrieve process variables. In case a process variable is stored as a serialized object, you can just make updates to your deserialized objects without the need for an explicit save. jBPM will manage deserialized process variables and update them automatically if you change. For example (@see examples package org.jbpm.examples.serializedobject), look at this piece of user code inside a custom's activity behaviour:

public class UpdateSerializedVariables implements ActivityBehaviour {

  public void execute(ActivityExecution execution) {
    Set<String> messages = (Set<String>) execution.getVariable("messages");
    messages.clear();
    messages.add("i");
    messages.add("was");
    messages.add("updated");
  }
}

When the transaction commits in which this usercode was called, the updated messages set will be updated in the database automatically.
When reading process variables that are stored in serialized format from the DB jBPM will monitor that deserialized object. Right before the commit of the transaction, jBPM will serialize and update the variable automatically if that is necessary. jBPM will ignore updates to the deserialized object if another object was set as the value in that scope (which even can be of another type). jBPM will also skip updating of the variable if the deserialized object has not been changed. The check to see if the object has changed is based on comparing the byte arrays from serializing the object again and comparing that with the byte array that was originally loaded from the db.

7.4. Declared variables

(Since jBPM 4.4)
Variables can be declared directly in process definition (JPDL). These variables will be created at process instance startup. There can be more than one variable definition.
There are several possible ways for declaring variable:

• declare String variable initialized with static text

  <variable name="declaredVar" type="string" init-expr="testing declared

   variable"/>
        

• declare custom variable initialized with EL

  <variable name="declaredVar" type="long" init-expr="#{anotherVar}"/>
        

• declare custom variable initialized with serializable class

  <variable name="declaredVar" type="serializable" >
     <object class="org.jbpm.examples.variable.declared.HistoryVariable" />
  </variable>
        

As shown above variable values can be assigned in two ways: using attribute init-expr or by nesting init descriptor (element object) within variable tags.
Note: Only one of value assignment can be used for a variable declaration.

Table 7.1. Attribute for variable element:

Attribute	Type	Default	Required?	Description
name	text		required	name of the variable
type	text		required	type of the variable, must refer to types defined in jbpm.variable.types.xml
init-expr	text (EL expression)		optional	value for the variable, this attribute or nested element must be given
init-expr-type	text	UEL	optional	defines language for expression evaluation
history	boolean	false	optional	indicates wheater variable should be stored in history or not - default false, for more information about history see Section 7.5, “Variables history”

Table 7.2. Nested element for variable:

Element	Multiplicity	Description
object	1	Value for the variable as custom object, either this element or init-expr attribute must be specified

7.5. Variables history

(Since jBPM 4.4)
Variables can be marked to be persisted as history records. This means that once process instance is ended and its runtime information is removed, history details are preserved.
History can be enabled for variable in two ways:

• via public API ExecutionService:
  • void createVariable(String executionId, String name, Object value, boolean historyEnabled);
  • void createVariables(String executionId, Map<String, ?> variables, boolean historyEnabled);
• on variable declaration

  <variable name="declaredVar" type="string" init-expr="testing declared

   variable" history="true"/>
        

Currently all variables are persisted in history as String values. Variable (regardless of its type) will be converted to a string value using toString() method. In case of custom objects they should override toString() method to provide string representation of the variable that will be available as history record. This will provide an easy way for enabling convienient search capabilities based on variable values.
Access to history variables is given via HistoryService methods:

• Object getVariable(String processInstnceId, String name);
• Map<String, Object> getVariables(String processInstnceId, Set<String> variableNames);
• Set<String> getVariableNames(String processInstnceId);

     For more information follow my Tutorial  online @ http://jbpmmaster.blogspot.com/