Chapter 6.

jPDL
6.1. process 6.2. Control flow activities 6.2.1. start 6.2.2. state 6.2.3. decision 6.2.4. concurrency 6.2.5. end 6.2.6. task 6.2.7. sub-process 6.2.8. custom 6.3. Automatic activities 6.3.1. java 6.3.2. script 6.3.3. hql 6.3.4. sql 6.3.5. mail 6.4. Common activity contents 6.5. Events 6.5.1. Event listener example 6.5.2. Event propagation 6.6. Asynchronous continuations 6.6.1. Async activity 6.6.2. Async fork 6.7. User code 6.7.1. User code configuration 6.7.2. User code classloading This chapter will explain the jPDL file format for describing process definitions. jPDL is the prominent process language of jBPM. The goal of jPDL is to be as concise and developerfriendly as possible, while offering every feature you'd expect from a BPM process language. The jPDL schema file contains more attributes and elements then this documentation. This part of the documentation explains the stable and supported part of jPDL. Experimental/not supported jPDL features can be found in the developers guide. An example jPDL process file looks like this:
<?xml version="1.0" encoding="UTF-8"?> <process name="Purchase order" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="Verify supplier" /> </start> <state name="Verify supplier"> <transition name="Supplier ok" to="Check supplier data" /> <transition name="Supplier not ok" to="Error" /> </state>

<decision name="Check supplier data"> <transition name="nok" to="Error" /> <transition name="ok" to="Completed" /> </decision> <end name="Completed" /> <end name="Error" /> </process>

6.1. process
The top level element representing one process definition. Table 6.1. process attributes: Attribute
name

Type any text

Default

Required? required

Description name or label of the process used to display to the process name in user interactions. identification to distinct different process definitions. Multiple versions of a process with the same key can be deployed. The key:name combination must remain exactly the same for all deployed versions.

key

if omitted, the key will be generated alpha numeric based on the name by characters and replacing all nonoptional underscores alpha-numeric characters with underscores one higher then highest version number starting with 1 if no other process is deployed with the same name/key.

version

integer

optional

version number of this process

Table 6.2. process elements: Multiplicity description 0..1 description text activities 1..* Element Description

a list of any activity type can be placed here. At least one start activity must be present.

6.2. Control flow activities

6.2.1. start

Indicates where an execution for this process starts. Typically there is exactly one start activity in a process. A process has to have at least one start activity. A start activity must have exactly one outgoing transition and that transition is taken when a process execution starts. Known limitation: for now, a process can not have more then one start. Table 6.3. start attributes: Attribute Type Default Required?
name

Description name of the activity. Since a start activity cannot have incoming transitions, the name is optional.

any text

optional

Table 6.4. start elements: Element

transition

Multiplicity 1

Description the outgoing transition

6.2.2. state
A wait state. Process execution will wait until an external trigger is provided through the API. Apart from the common activity content, state doesn't have any extra attributes or elements. 6.2.2.1. state sequence Let's look at an example which shows states connected with transitions as a sequence

Figure 6.1. A sequence of states

<process name="StateSequence" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="a" /> </start> <state name="a"> <transition to="b" /> </state> <state name="b"> <transition to="c" /> </state>

<state name="c" /> </process>

After you start an execution like this:

ProcessInstance processInstance = executionService.startProcessInstanceByKey("StateSequence");

the created process instance will be positioned in state a. Providing an external trigger can be done with the signalExecution methods.
Execution executionInA = processInstance.findActiveExecutionIn("a"); assertNotNull(executionInA); processInstance = executionService.signalExecutionById(executionInA.getId()); Execution executionInB = processInstance.findActiveExecutionIn("b"); assertNotNull(executionInB); processInstance = executionService.signalExecutionById(executionInB.getId()); Execution executionInC = processInstance.findActiveExecutionIn("c"); assertNotNull(executionInC);

6.2.2.2. state choice In this second example with states, we'll show how you can use a state can be used to feed in an external choice of the path to take.

Figure 6.2. A choice between state

<process name="StateChoice" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="wait for response" /> </start> <state name="wait for response"> <transition name="accept" to="submit document" /> <transition name="reject" to="try again" /> </state> <state name="submit document" />

<state name="try again" /> </process>

Let's start a new process instance for this process definition:

ProcessInstance processInstance = executionService .startProcessInstanceByKey("StateChoice");

Now, the execution has arrived in the wait for response. The execution will wait there until an external trigger is given. In case a state has multiple outgoing transitions, the signalName given in the external trigger will be matched against the name of the outgoing transition to take. So when we provide signalName accept like this:
String executionId = processInstance .findActiveExecutionIn("wait for response") .getId(); processInstance = executionService.signalExecutionById(executionId, "accept"); assertTrue(processInstance.isActive("submit document"));

Then the execution will continue over the outgoing transition named accept. Analogue, when signalName reject is given in the signalExecutionXxx methods, the execution will continue over the outgoing transition named reject.

6.2.3. decision
Takes one path of many alternatives. Also known as a decision. A decision activity has multiple outgoing transitions and when an execution arrives in a decision activity, an automatic evaluation will decide which outgoing transition is taken. A decision activity should be configured in one of the three following ways: 6.2.3.1. Decision conditions A decision with conditions on the transitions evaluates the condition in each transition. The first transition for which the nested condition expression resolves to true or which does not have a condition is taken. Table 6.5. decision.transition.condition attributes: Attribute
expr

Type expression expression language

Default

Required? required

Description script that will be evaluated in the specified expression language. the language in which expr is to be evaluated.

lang

the default-expressionlanguage taken from the

optional

Attribute

Type

Default
script-manager

Required?

Description

configuration

Example:

Figure 6.3. The decision conditions example process

<process name="DecisionConditions" > <start> <transition to="evaluate document" /> </start> <decision name="evaluate document"> <transition to="submit document"> <condition expr="#{content=="good"}" /> </transition> <transition to="try again"> <condition expr="#{content=="not so good"}" /> </transition> <transition to="give up" /> </decision> <state name="submit document" /> <state name="try again" /> <state name="give up" /> </process>

After starting a process instance with good content

Map<String, Object> variables = new HashMap<String, Object>(); variables.put("content", "good"); ProcessInstance processInstance = executionService.startProcessInstanceByKey("DecisionConditions", variables);

The activity submit document will be active

assertTrue(processInstance.isActive("submit document"));

See the example unit test for more scenarios. 6.2.3.2. Decision expression A decision expression evaluates to a String representing the name of an outgoing transition. Table 6.6. decision attributes: Attribute
expr

Type expression

Default

Required? required

Description script that will be evaluated in the specified expression language. the language in which expr is to be evaluated.

lang

expression language

the default-expressionlanguage taken from the

script-manager

optional

configuration

Example:

Figure 6.4. The decision expression example process

<process name="DecisionExpression" xmlns="http://jbpm.org/4.4/jpdl"> <start > <transition to="evaluate document"/> </start> <decision name="evaluate document" expr="#{content}" > <transition name="good" to="submit document" /> <transition name="bad" to="try again" /> <transition name="ugly" to="give up" /> </decision> <state name="submit document" <state name="try again" /> <state name="give up" /> </process> />

When you start an new process instance with good content like this
Map<String, Object> variables = new HashMap<String, Object>(); variables.put("content", "good");

ProcessInstance processInstance = executionService.startProcessInstanceByKey("DecisionExpression", variables);

then the new execution will go to activity submit document. See the example unit test for the other scenarios. 6.2.3.3. Decision handler A decision handler is a java class that implements the DecisionHandler interface. The decision handler will be responsible for selecting the name of the outgoing transition.
public interface DecisionHandler { String decide(OpenExecution execution); }

The handler is specified as a sub element of the decision. The configuration attributes and content of a decision handler element can be found in Section 6.7, User code. Here's an example process of a decision using a DecisionHandler:

Figure 6.5. The decision handler example process

<process name="DecisionHandler"> <start> <transition to="evaluate document" /> </start> <decision name="evaluate document"> <handler class="org.jbpm.examples.decision.handler.ContentEvaluation" /> <transition name="good" to="submit document" /> <transition name="bad" to="try again" /> <transition name="ugly" to="give up" /> </decision> <state name="submit document" /> <state name="try again" /> <state name="give up" /> </process>

The ContentEvaluation class looks like this

public class ContentEvaluation implements DecisionHandler { public String decide(OpenExecution execution) { String content = (String) execution.getVariable("content");

if (content.equals("you're great")) { return "good"; } if (content.equals("you gotta improve")) { return "bad"; } return "ugly"; } }

Now, when we start a process instance and supply value you're great for variable content, then the ContentEvaluation will return String good and the process instance will arrive in activity Submit document.

6.2.4. concurrency
Concurrent paths of executions can be modeled with the fork and join activities. The next table describes the join attributes; fork has no specific attributes. Table 6.7. join attributes: Attribute Type integer or expression Default nbr of incoming transitions Required? Description The number of executions that should arrive in this join before the join activates and push an execution out the single outgoing transition of the join. the hibernate lock mode applied on the parent execution to prevent that 2 concurrent transactions see each other as not yet arrived at the join, causing a process deadlock.

multiplicity

optional

lockmode

{none, read, upgrade, upgrade_nowait, write}

upgrade

optional

6.2.4.1. Parallel split with fork The fork activity allows a single path of execution to be split into two or more branches which can execute activities concurrently.

Figure 6.6. Parallel split example process

<process name="ConcurrencyGraphBased" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="fork"/> </start> <fork name="fork"> <transition to="send invoice" /> <transition to="load truck"/> <transition to="print shipping documents" /> </fork> <state name="send invoice" > <transition to="final join" /> </state> <state name="load truck" > <transition to="shipping join" /> </state> <state name="print shipping documents"> <transition to="shipping join" /> </state> <join name="shipping join" > <transition to="drive truck to destination" /> </join> <state name="drive truck to destination" > <transition to="final join" /> </state> <join name="final join" > <transition to="end"/> </join> <end name="end" /> </process>

6.2.5. end
Ends the execution. 6.2.5.1. end process instance By default, an end activity will end the complete process instance. In case multiple concurrent executions are still active within the same process instance, all of them will be ended.

Figure 6.7. The end event

<process name="EndProcessInstance" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="end" /> </start> <end name="end" /> </process>

When a new process instance is created, it immediately ends. 6.2.5.2. end execution Only the execution that arrives in the end activity will be ended and other concurrent executions should be left active. To get this behaviour, set attribute ends="execution" Table 6.8. end execution attributes: Attribute Type Default Required? Description specifies if the whole process instance should be ended or just the path of execution that arrives in the end activity.

ends

{processinstance|execution} processinstance optional

6.2.5.3. end multiple A process can have multiple end events. This can be handy to indicate different outcomes of a process instance. For example

Figure 6.8. Multiple end events

<process name="EndMultiple" xmlns="http://;jbpm.org/4/jpdl"> <start> <transition to="get return code" /> </start> <state name="get return code"> <transition name="200" to="ok"/> <transition name="400" to="bad request"/> <transition name="500" to="internal server error"/> </state> <end name="ok"/> <end name="bad request"/> <end name="internal server error"/> </process>

Now if we would start an execution and signal it to move out of the get return code wait state with the following code, the execution would end with the bad request end event.
ProcessInstance processInstance = executionService.startProcessInstanceByKey("EndMultiple"); String pid = processInstance.getId(); processInstance = executionService.signalExecutionById(pid, "400");

Likewise, using the value 200 or 500 would cause the execution to end with the ok or with the internal server error end events respectively. 6.2.5.4. end state An execution can also end with different states. It is another way to specify the outcome of a process. It is indicated by the state attribute of the end event or by the end-cancel and enderror shortcut notations. Table 6.9. end execution attributes:

Attribute Type Default Required?

state

Description the state assigned to the execution.

String

optional

Take for example the following process.

Figure 6.9. Different end states

<process name="EndState" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="get return code"/> </start> <state name="get return code"> <transition name="200" to="ok"/> <transition name="400" to="bad request" /> <transition name="500" to="internal server error"/> </state> <end name="ok" state="completed"/> <end-cancel name="bad request"/> <end-error name="internal server error"/> </process>

This time, if we would start an execution and signal it to move out of the get return code wait state with the following code, the execution would end with the cancel state. Similarly, using the value 200 or 500 would cause the execution to end with the completed or with the error states respectively.

6.2.6. task
Creates a task for a person in the task component. 6.2.6.1. task assignee

A simple task that will be assigned to a specific user Table 6.10. task attributes: Attribute
assignee

Type expression

Default Required? optional

Description userId referring to the person that is responsible for completing this task.

Figure 6.10. The task assignee example process

<process name="TaskAssignee"> <start> <transition to="review" /> </start> <task name="review" assignee="#{order.owner}"> <transition to="wait" /> </task> <state name="wait" /> </process>

This process shows 2 aspects of task assignment. First, that the attribute assignee is used to indicate the user that is responsible for completing the task. The assignee is a String property of a task and refers to a user. Secondly, this attribute is by default evaluated as an expression. In this case the task is assigned to #{order.owner}. Which means that first an object is searched for with name order. One of the places where this object is looked up is the process variables associated to the task. Then the getOwner() getter will be used to get the userId that references the user that is responsible for completing this task. Here's the Order class used in our example:
public class Order implements Serializable { String owner; public Order(String owner) { this.owner = owner; } public String getOwner() {

return owner; } public void setOwner(String owner) { this.owner = owner; } }

Next a new process instance is created with an order as a process variable.

Map<String, Object> variables = new HashMap<String, Object>(); variables.put("order", new Order("johndoe")); ProcessInstance processInstance = executionService .startProcessInstanceByKey("TaskAssignee", variables);

Then the task list for johndoe can be obtained like this.
List<Task> taskList = taskService.findPersonalTasks("johndoe");

Note that it is also possible to put plain text like assignee="johndoe". In that case the task will be assigned to johndoe. 6.2.6.2. task candidates A task that will be offered to a group of users. One of the users should then take the task in order to complete it. Table 6.11. task attributes: Attribute
candidategroups candidateusers

Type expression expression

Default Required? optional optional

Description resolves to a comma separated list of groupIds. All the people in the groups will be candidates for this task. resolves to a comma separated list of userIds. All the users will be candidates for this task.

Figure 6.11. The task candidates example process

Here's an example process using task candidates:

<process name="TaskCandidates"> <start> <transition to="review" /> </start>

<task name="review" candidate-groups="sales-dept"> <transition to="wait" /> </task> <state name="wait"/> </process>

After starting, a task will be created. The task will not show up in anyone's personal task list. Following task lists will be empty.
taskService.getPersonalTasks("johndoe"); taskService.getPersonalTasks("joesmoe");

But the task will show up in the group task list of all members of the sales-dept group. The in our example, the sales-dept has two members: johndoe and joesmoe
identityService.createGroup("sales-dept"); identityService.createUser("johndoe", "johndoe", "John", "Doe"); identityService.createMembership("johndoe", "sales-dept"); identityService.createUser("joesmoe", "joesmoe", "Joe", "Smoe"); identityService.createMembership("joesmoe", "sales-dept");

So after the process is created, the task will appear in both the group tasks for users johndoe and joesmoe
taskService.findGroupTasks("johndoe"); taskService.findGroupTasks("joesmoe");

Candidates must take a task before they can work on it. This will prevent that two candides start working on the same task. The user interface must only offer the action 'Take' for the tasks in the group task list.
taskService.takeTask(task.getDbid(), "johndoe");

When a user takes a task, the assignee of that task will be set to the given user. The task will disappear from all the candidate's group task list and it will appear in the user's assigned tasks. Users are only allowed to work on tasks in their personal task list. This should be enforced by the user interface. Similarly, the attribute candidate-users can be used that resolves to a comma separated list of userIds. The candidate-users attribute can be used in combination with other assignment options. 6.2.6.3. task assignment handler

An AssignmentHandler can be used to calculate the assignee and the candidates for a task programmatically.
public interface AssignmentHandler extends Serializable { /** sets the actorId and candidates for the given assignable. */ void assign(Assignable assignable, OpenExecution execution) throws Exception; } Assignable

is a common interface for Tasks and Swimlanes. So AssignmentHandlers can be used for tasks as well as swimlanes (see later).
assignment-handler

is a sub element of the task element. It specifies a user code object. So the attributes and elements of assignment-handler are documented in Section 6.7, User code Let's look at the task assignment example process.

Figure 6.12. The task assignment handler example process

<process name="TaskAssignmentHandler" xmlns="http://jbpm.org/4.4/jpdl"> <start g="20,20,48,48"> <transition to="review" /> </start> <task name="review" g="96,16,127,52"> <assignment-handler class="org.jbpm.examples.task.assignmenthandler.AssignTask"> <field name="assignee"> <string value="johndoe" /> </field> </assignment-handler> <transition to="wait" /> </task> <state name="wait" g="255,16,88,52" /> </process>

The referenced class AssignTask looks like this:

public class AssignTask implements AssignmentHandler { String assignee; public void assign(Assignable assignable, OpenExecution execution) { assignable.setAssignee(assignee);

} }

Please note that potentially, AssignmentHandler implementations can use the process variables and any other Java API to access resources like your application database to calculate the assignee and candidate users and groups. Starting a new process instance of the TaskAssignmentHandler process will immediately bring the new execution to the task activity. A new review task is created and at that point, the AssignTask assignment handler is called. That will set johndoe as the assignee. So John Doe will find the task in his personal task list. 6.2.6.4. task swimlanes Multiple tasks in a process should be assigned to the same user or candidates. Multiple tasks in a process can be associated to a single swimlane. The process instance will remember the candidates and user that performed the first task in the swimlane. And subsequent tasks in the same swimlane will be assigned to those user and candidates. A swimlane can also be considered as a process role. In some cases, this might boil down to authorization roles in the identity component. But bare in mind that it is not always the same thing. Table 6.12. task attributes: Attribute Type swimlane swimlane (string) Default Required? optional Description refers to a swimlane that is declared in the process

Swimlanes can be declared inside a process element: Table 6.13. swimlane attributes: Attribute
name

Type swimlane (string) expression

Default Required? required optional

Description Name for this swimlane. This is the name that will be referenced by task swimlane attributes. userId referring to the person that is responsible for completing this task. resolves to a comma separated list of groupIds. All the people in the groups will be candidates for this the tasks in this swimlane. resolves to a comma separated list of userIds. All the users will be candidates for the tasks in this swimlane.

assignee

candidategroups

expression

optional

candidateusers

expression

optional

Figure 6.13. The task swimlane example process

The task swimlane example has the following process file :

<process name="TaskSwimlane" xmlns="http://jbpm.org/4.4/jpdl"> <swimlane name="sales representative" candidate-groups="sales-dept" /> <start> <transition to="enter order data" /> </start> <task name="enter order data" swimlane="sales representative"> <transition to="calculate quote"/> </task> <task name="calculate quote" swimlane="sales representative"> </task> </process>

In this example we create the following information in the identity component:

identityService.createGroup("sales-dept"); identityService.createUser("johndoe", "johndoe", "John", "Doe"); identityService.createMembership("johndoe", "sales-dept");

After starting a new process instance, user johndoe will be a candidate for task enter order data. Again like in the previous task candidates example, John Doe can now take this task like this:
taskService.takeTask(taskDbid, "johndoe");

Taking the task will make Litjohndoe the assignee for the task. And since this task is coupled to the swimlane sales representative, assignee johndoe will also be propagated as the assignee in the swimlane. Next, John Doe can complete the task like this:
taskService.completeTask(taskDbid);

Completing the task will bring the process execution to the next task, which is calculate quote. Also this task is linked to the swimlane. Therefore, the task will be assigned to johndoe. Also the candidate users and candidate groups of the initial assignment will be copied from the swimlane to the task. This is relevant in case user johndoe would release the task and offer it back to the other candidates. 6.2.6.5. task variables Tasks can read and update process variables. Later tasks will have the option to declare tasklocal process variables. Task variables are an important part of the task forms. Task forms typically show data that comes from the task and the process instance. Then input from the user is translated in setting task variables. Getting task variables can be done like this:
List<Task> taskList = taskService.findPersonalTasks("johndoe"); Task task = taskList.get(0); long taskDbid = task.getDbid(); Set<String> variableNames = taskService.getVariableNames(taskDbid); Map<String, Object> variables = taskService.getVariables(taskDbid, variableNames);

And setting task variables can be done like this:

variables = new HashMap<String, Object>(); variables.put("category", "small"); variables.put("lires", 923874893); taskService.setVariables(taskDbid, variables);

6.2.6.6. e-mail support in tasks It is possible to provide assignees with notifications when a task is added to their list, as well as reminders at specific intervals. Every email message is produced from a template. Templates may be specified inline or in the process-engine-context section of the configuration file. Table 6.14. task elements Element Multiplicity notification 0..1 Description Sends a notification message when a task is assigned. If no template is referenced or supplied inline, mail support falls back on the template named task-notification. Sends a reminder message at specific intervals. If no template is referenced or supplied inline, mail support falls back on the template named task-reminder.

reminder

0..1

Table 6.15. notification attributes: Attribute

continue

Type

Default Required? optional

{sync | async | sync exclusive}

Description Specifies if an asynchronous continuation should be introduced right before sending this notification email.

Table 6.16. reminder attributes: Attribute

duedate

Type duration (plain string or containing expression) duration (plain string or containing expression) {sync | async | exclusive}

Default Required? required

Description Delay before a reminder email should be send. Delay after a subsequent reminder email should be send Specifies if an asynchronous continuation should be introduced right before sending this notification email.

repeat

optional

continue

sync

optional

Here is a basic example that accepts the default templates.

<task name="review" assignee="#{order.owner}" <notification/> <reminder duedate="2 days" repeat="1 day"/> </task>

6.2.7. sub-process
Creates a sub process instance and waits till it is completed. When the sub process instance completes, then the execution in the sub-process will continue. Table 6.17. sub-process attributes: Attribute
subprocessid

Type string or expression

Default

Description Identifies the sub process by the id. This either this or means that a specific version of a process sub-process-key definition is referenced. Sub process id can is required be specified as simple text or EL expression. Identifies the sub process by the key. This either this or means that the latest version of the process sub-process-key definition with the given key is referenced. is required The latest version of the process is looked

Required?

subprocesskey

string or expression

Attribute

Type

Default

Required?

Description up each time the activity executes. Sub process key can be specified as simple text or EL expression.

outcome

expression

required when Expression that is evaluated when the sub transitions have process instance ends. The value is then outcomeused for outcome transition mapping. Add value's outcome-value elements to the outgoing specified transitions of this sub-process activity.

Table 6.18. sub-process elements: Element

parameterin parameterout

Multiplicity 0..* 0..*

Description Declares a variable that is passed to the sub process instance when it is created. Declares a variable that will be set in the super process execution when the sub process ends.

Table 6.19. parameter-in attributes: Attribute Type Default

subvar

Required? required exactly one of {'var', 'expr'} is required to specify the value exactly one of {'var', 'expr'} is required to specify the value optional

string string

Description The name of the sub process variable in which the value is set. The name of the variable in the super process execution context. An expression that will be resolved in the super process execution context. The resulting value will be set in the sub process variable. The scripting language in which the expression should be resolved.

var

expr

string

lang

string juel

Table 6.20. parameter-out attributes: Attribute Type Default

var

Required? required

string

Description The name of the variable in the super process execution context in which the value will be set.

subvar

string

exactly one of {'subvar', The name of the sub process variable from 'expr'} is required to which the value will be taken. specify the value

Attribute Type Default

expr

Required?

Description

string

An expression that will be resolved in the exactly one of {'subvar', sub process execution context. The 'expr'} is required to resulting value will be set in the super specify the value process variable. optional The scripting language in which the expression should be resolved.

lang

string juel

Table 6.21. Extra transition elements in case of outcome variable mappings: Element
outcomevalue

Multiplicity 0..1

Description If the outcome matches the value, this transition is taken after the sub-process ended. The value is specified with one child element.

6.2.7.1. sub-process variables The SubProcessVariables example scenario will show the basic workings of the sub-process activity, how to feed information in the sub process when it starts and how to extract information out of the subprocess when it ends. The parent process involves a document that needs to be reviewed.

Figure 6.14. The subprocess document example process

<process name="SubProcessDocument" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="review" /> </start> <sub-process name="review" sub-process-key="SubProcessReview"> <parameter-in var="document" subvar="document" /> <parameter-out var="reviewResult" subvar="result" /> <transition to="wait" /> </sub-process> <state name="wait"/> </process>

The review process is a reusable process for all kinds of reviews.

Figure 6.15. The subprocess review example process

<process name="SubProcessReview" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="get approval"/> </start> <task name="get approval" assignee="johndoe"> <transition to="end"/> </task> <end name="end" /> </process>

The document process is started with a document variable:

Map<String, Object> variables = new HashMap<String, Object>(); variables.put("document", "This document describes how we can make more money..."); ProcessInstance processInstance = executionService .startProcessInstanceByKey("SubProcessDocument", variables);

Then the parent process execution will arrive in the sub process activity. A sub process instance is created and linked with the super process execution. When the SubProcessReview process instance starts, it arrives in the task. A task will be created for johndoe.
List<Task> taskList = taskService.findPersonalTasks("johndoe"); Task task = taskList.get(0);

We can see that the document has been passed from the super process instance to the sub process instance:
String document = (String) taskService.getVariable(task.getDbid(), "document"); assertEquals("This document describes how we can make more money...", document);

Then we set a variable on the task. This is typically done through a form. But here we'll show how it is done programmatically.
Map<String, Object> variables = new HashMap<String, Object>(); variables.put("result", "accept"); taskService.setVariables(task.getDbid(), variables);

Completing this task, will cause the sub process instance to end.
taskService.completeTask(task.getDbid());

When the sub process ends, the super process execution will get signalled(=notified). First the result variable from the sub process instance will be copied into the reviewResult variable in the super process execution. Then the super process execution will continue and leave the review activity. 6.2.7.2. sub-process outcome value In the SubProcessOutcomeValueTest example, the value of a sub process variable is used to select the outgoing transition of the sub-process activity.

Figure 6.16. The subprocess document example process

<process name="SubProcessDocument"> <start> <transition to="review" /> </start> <sub-process name="review" sub-process-key="SubProcessReview" outcome="#{result}"> <transition name="ok" to="next step" /> <transition name="nok" to="update" /> <transition name="reject" to="close" /> </sub-process> <state name="next step" /> <state name="update" /> <state name="close" /> </process>

The SubProcessReview is the same as above in the subprocess variables example:

Figure 6.17. The subprocess review example process for outcome value
<process name="SubProcessReview" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="get approval"/> </start> <task name="get approval" assignee="johndoe"> <transition to="end"/> </task> <end name="end" /> </process>

A new document process instance is started like usual:

ProcessInstance processInstance = executionService .startProcessInstanceByKey("SubProcessDocument");

Then task is fetched from johndoe's task list

List<Task> taskList = taskService.findPersonalTasks("johndoe"); Task task = taskList.get(0);

Then the result variable is set and the task is completed.

Map<String, Object> variables = new HashMap<String, Object>(); variables.put("result", "ok"); taskService.setVariables(task.getId(), variables); taskService.completeTask(task.getDbid());

In this scenario, the ok transition is taken in the parent process out of the sub-process review activity. The example test case also shows other scenarios. 6.2.7.3. sub-process outcome activity A process can have many end activities. In the SubProcessOutcomeActivityTest example, the resulting end activity is used to select the outgoing transition of the sub-process activity.

Figure 6.18. The subprocess document example process for outcome activity
<process name="SubProcessDocument"> <start> <transition to="review" /> </start> <sub-process name="review" sub-process-key="SubProcessReview"> <transition name="ok" to="next step" /> <transition name="nok" to="update" /> <transition name="reject" to="close" /> </sub-process> <state name="next step" /> <state name="update" /> <state name="close" /> </process>

The SubProcessReview now has multiple end activities:

Figure 6.19. The subprocess review example process for outcome activity
<process name="SubProcessReview" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="get approval"/> </start>

<task name="get approval" assignee="johndoe"> <transition name="ok" to="ok"/> <transition name="nok" to="nok"/> <transition name="reject" to="reject"/> </task> <end name="ok" /> <end name="nok" /> <end name="reject" /> </process>

A new document process instance is started like usual:

ProcessInstance processInstance = executionService .startProcessInstanceByKey("SubProcessDocument");

Then task is fetched from johndoe's task list

List<Task> taskList = taskService.findPersonalTasks("johndoe"); Task task = taskList.get(0);

Then the task is completed with outcome ok.

taskService.completeTask(task.getDbid(), "ok");

This will cause the sub process to end in end activity ok. The super process execution will then take outgoing transition ok to next step. The example test case also shows the other scenarios.

6.2.8. custom
Invokes user code that implements custom behaviour of an activity. A custom activity refers to user code. See Section 6.7, User code for more details on the specific attributes and elements. Let's look at the example:
<process name="Custom" xmlns="http://jbpm.org/4.4/jpdl"> <start > <transition to="print dots" /> </start> <custom name="print dots" class="org.jbpm.examples.custom.PrintDots"> <transition to="end" /> </custom> <end name="end" />

</process>

The custom activity behaviour class PrintDots shows that it's possible to control the flow when implementing custom activity behaviours. In this case the PrintDots acitivity implementation will after printing dots wait in the activity until a signal is given.
public class PrintDots implements ExternalActivityBehaviour { private static final long serialVersionUID = 1L; public void execute(ActivityExecution execution) { String executionId = execution.getId(); String dots = ...; System.out.println(dots); execution.waitForSignal(); } public void signal(ActivityExecution execution, String signalName, Map<String, ?> parameters) { execution.take(signalName); } }

6.3. Automatic activities

6.3.1. java
The Java task. A process execution will execute the method of the class that is configured in this activity. Table 6.22. java attributes: Attribute Type Default Required? Description

class

classname

The fully qualified classname. See either 'class' or Section 6.7.2, User code classloading for 'expr' has to be classloading information. The user code specified object will be lazy initialized and cached as part of the process definition. either 'expr' or An expression that returns the target object 'class' has to be on which the method should be invoked. specified required optional The name of the method to invoke The name of the variable in which the return value should be stored.

expr method var

expression methodname variablename

Table 6.23. java elements:

Element Multiplicity
field arg

Description describes a configuration value to inject in a memberfield before the method is invoked. method parameters

0..* 0..*

Consider the following example.

Figure 6.20. A java task

<process name="Java" xmlns="http://jbpm.org/4.4/jpdl"> <start > <transition to="greet" /> </start> <java name="greet" class="org.jbpm.examples.java.JohnDoe" method="hello" var="answer" > <field name="state"><string value="fine"/></field> <arg><string value="Hi, how are you?"/></arg> <transition to="shake hand" /> </java> <java name="shake hand" expr="#{hand}" method="shake" var="hand" > <arg><object expr="#{joesmoe.handshakes.force}"/></arg> <arg><object expr="#{joesmoe.handshakes.duration}"/></arg> <transition to="wait" /> </java> <state name="wait" /> </process>

Classes involved:
public class JohnDoe {

String state; Session session; public String hello(String msg) { if ( (msg.indexOf("how are you?")!=-1) && (session.isOpen()) ) { return "I'm "+state+", thank you."; } return null; } } public class JoeSmoe implements Serializable { static Map<String, Integer> handshakes = new HashMap<String, Integer>(); { handshakes.put("force", 5); handshakes.put("duration", 12); } public Map<String, Integer> getHandshakes() { return handshakes; } } public class Hand implements Serializable { private boolean isShaken; public Hand shake(Integer force, Integer duration) { if (force>3 && duration>7) { isShaken = true; } return this; } public boolean isShaken() { return isShaken; } }

The first java activity greet specifies that during its execution an instance of the class org.jbpm.examples.java.JohnDoe will be instantiated and the method hello of this class will be invoked on the resulting object. The variable named answer will contain the result of the invocation. The class above reveals that it contains two fields named state and session and that the method hello accepts one argument. During the execution the values specified in the field and arg configuration elements will be used. The expected result of creating a process instance is that the process variable answer contains the string I'm fine, thank you.. The second java activity is named shake hand. It will resolve expression #{hand} and capture the resulting object as the target object. On that object, the method shake will be invoked. The two arguments will be calculated by resolving the respective expressions #{joesmoe.handshakes.force} and #{joesmoe.handshakes.duration}. The resulting object is a mofied version of the hand and var="hand" will cause the modified hand to overwrite the old hand variable value.

6.3.2. script
A script activity evaluates a script. Scripts can be specified in any language for which there is a JSR-223 compliant scripting engine. Configuration of scripting engines is explained below. There are 2 ways of specifying a script: 6.3.2.1. script expression The script is provided with the expr attribute. This is for short expressions that are easier expressed in an attribute then in a text element. If no lang is specified, the default-expressionlanguage is used. Table 6.24. script expression attributes: Attribute
expr

Type text scripting language name as defined in Chapter 8, Scripting variablename

Default

Required? required

Description the expression text to evaluate. the language in which the expression is specified. name of the variable in which the return value should be stored.

lang

the default expression language as defined in optional Chapter 8, Scripting optional

var

In the next example, we'll see how a script activity with an expression and how the result is stored in a variable.

Figure 6.21. The script.expression example process

<process name="ScriptExpression" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="invoke script" /> </start> <script name="invoke script" expr="Send packet to #{person.address}" var="text"> <transition to="wait" /> </script> <state name="wait"/>

</process>

This example uses a Person class that looks like this.

public class Person implements Serializable { String address; public Person(String address) { this.address = address; } public String getAddress() { return address; } public void setAddress(String address) { this.address = address; } }

When starting a process instance for this process, we supply a person with a given address property as variable person.
Map<String, Object> variables = new HashMap<String, Object>(); variables.put("person", new Person("Honolulu")); executionService.startProcessInstanceByKey("ScriptText", variables);

After the execution of the script activity, variable text will contain 'Send packet to Honolulu'. 6.3.2.2. script text The second way of specifying a script is with a text element. This is convenient when the script text spans multiple lines. Table 6.25. script text attributes: Attribute
lang

Type scripting language name as defined in Chapter 8, Scripting variablename

Default the default scripting language as defined in Chapter 8, Scripting

Required? optional

Description the language in which the script is specified. name of the variable in which the return value should be stored.

var

optional

Table 6.26. script text elements: Element Multiplicity Description

Element Multiplicity
text

Description contains the script text

For example

Figure 6.22. The script.text example process

<process name="ScriptText" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="invoke script" /> </start> <script name="invoke script" var="text"> <text> Send packet to #{person.address} </text> <transition to="wait" /> </script> <state name="wait"/> </process>

Execution of this process is exactly the same as with the script expression above.

6.3.3. hql
With the hql activity, a HQL query can be performed on the database and the result is stored in a process variable. Table 6.27. hql attributes: Attribute
var

Type variablename

Default Required? required

Description the name of the variable in which the result is stored. a value of true means that the result from the hibernate query should be obtained with method uniqueResult(). The default is false and in that case the list() method will be used to get the result.

unique

{true, false} false

optional

Table 6.28. hql elements: Element Multiplicity Description query 1 The HQL query.
parameter

0..*

The query parameters

For example:

Figure 6.23. The hql example process

<process name="Hql" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="get process names" /> </start> <hql name="get process names" var="activities with o"> <query> select activity.name from org.jbpm.pvm.internal.model.ActivityImpl as activity where activity.name like :activityName </query> <parameters> <string name="activityName" value="%o%" /> </parameters> <transition to="count activities" /> </hql> <hql name="count activities" var="activities" unique="true"> <query> select count(*) from org.jbpm.pvm.internal.model.ActivityImpl </query> <transition to="wait" /> </hql> <state name="wait"/> </process>

6.3.4. sql
The sql activity is exactly the same as the hql activity, with the only difference that session.createSQLQuery(...) is used.

6.3.5. mail
Through the mail activity, process authors are able to specify the content of an email message to be sent to multiple recipients at once. Every email message is produced from a template. Templates may be specified inline or in the process-engine-context section of the configuration file. Table 6.29. mail attributes Attribute Type Default Required? template string no Description Reference to a mail-template element in the configuration file. If absent, the template must be specified inline using the child elements.

Table 6.30. mail elements Element Multiplicity from 0..1 list of sender(s) to cc bcc subject text html 1 0..1 0..1 1 0..1 0..1 list of primary recipients list of carbon copy recipients list of blind carbon copy recipients text content of this element becomes the message subject text content of this element becomes the message text content text content of this element becomes the message HTML content each attachment is configured in a separate subelement Description

attachments 0..1

Table 6.31. attachment attributes Attribute Type Default name string Required? Description

File name associated with this attachment. no, unless If absent, data sources that encapsulate expression is present files such as resource, file and url provide a reasonable fallback value. no Descriptive information associated with this attachment. Expression that evaluates to a representation of the attachment data in the form of a Java object. Useful to extract content from process variables. Path to the attachment data in the file system. The denoted file must exist. Location of the attachment data in the

description string

expression string

file url

string string

one of expression, file, url or resource must be present

Attribute Type Default

Required?

Description worldwide web. The pointed resource must exist.

resource

string no, unless

expression

Name of the resource containing the attachment data in the class path. The denoted resource must exist. MIME type of the object returned by the is present expression.

mime-type string

Example usage:
<process name="InlineMail" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="send birthday reminder note" /> </start> <mail name="send birthday reminder note"> <to addresses="johnDoe@some-company.com" /> <subject>Reminder: ${person} celebrates his birthday!</subject> <text>Do not forget: ${date} is the birthday of ${person} </text> <attachments> <attachment resource="org/example/birthday_card.png"/> <attachment name="picture.jpg" expression="${picture}" mimetype="image/jpeg"/> </attachments> <transition to="end" /> </mail> <state name="end"/> </process>

6.4. Common activity contents

Unless specified otherwise above, all activities also include this content model: Table 6.32. Common activity attributes: Attribute Type Default Required?
name

Description name of the activity

any text

required

Table 6.33. Common activity elements: Multiplicity Description transition 0..* the outgoing transitions Element

6.5. Events

Events specify points in a process on which a list of event listeners can be registered. When an execution passes that point in the process, the event listeners are notified. The events and listeners are not shown in the graphical view of the process, which makes them very interesting for implementing technical details. An event is fired by an element in the process definition like e.g. the process definition, an activity or a transition. The EventListener interface looks like this:
public interface EventListener extends Serializable { void notify(EventListenerExecution execution) throws Exception; }

All automatic activities can be used as event listeners as well. To associate a list of event listeners with a process or an activity, use the on element to group the event listeners and specifiy the event. on can be nested as a subelement of process or any activity. To associate a list of event listeners with a transition take event, just include the event listeners directly in the transition element. Table 6.34. on attributes: Attribute
event

Type {start | end}

Default Required? required

Description name name of the event

Table 6.35. on elements: Element

event-listener

Multiplicity Description 0..* An event listener implementation object.

any automatic activity 0..*

Table 6.36. event listener attributes:

event-listener

is user code so it can be configured like described in Section 6.7, User

code. Any automatic activities (including event-listener) that are placed on events can specify following additional attributes: Attribute
propagation

Type

Default Required?

Description indicates if the event listener should also be invoked for propagating events.

{enabled | disabled | true | disabled optional false | on | off}

Attribute

Type {sync | async | exclusive}

Default Required?

Description indicates if the execution should be continued asynchronously right before the event listener is executed. @see also Section 6.6, Asynchronous continuations

continue

sync

optional

6.5.1. Event listener example

Let's look at an example process with event listeners:

Figure 6.24. The event listener example process

<process name="EventListener" xmlns="http://jbpm.org/4.4/jpdl"> <on event="start"> <event-listener class="org.jbpm.examples.eventlistener.LogListener"> <field name="msg"><string value="start on process definition"/></field> </event-listener> </on> <start> <transition to="wait"/> </start> <state name="wait"> <on event="start"> <event-listener class="org.jbpm.examples.eventlistener.LogListener"> <field name="msg"><string value="start on activity wait"/></field> </event-listener> </on> <on event="end"> <event-listener class="org.jbpm.examples.eventlistener.LogListener"> <field name="msg"><string value="end on activity wait"/></field> </event-listener> </on> <transition to="park"> <event-listener class="org.jbpm.examples.eventlistener.LogListener"> <field name="msg"><string value="take transition"/></field> </event-listener> </transition> </state> <state name="park"/> </process> LogListener

will maintain a list of logs as a process variable:

public class LogListener implements EventListener { // value gets injected from process definition String msg; public void notify(EventListenerExecution execution) { List<String> logs = (List<String>) execution.getVariable("logs"); if (logs==null) { logs = new ArrayList<String>(); execution.setVariable("logs", logs); } logs.add(msg); execution.setVariable("logs", logs); } }

Next, we start a new process instance.

ProcessInstance processInstance = executionService.startProcessInstanceByKey("EventListener");

Then the process instance executes up to the wait activity. So we provide a signal and that will cause it to execute till the end.
Execution execution = processInstance.findActiveExecutionIn("wait"); executionService.signalExecutionById(execution.getId());

The list of log messages will now look like this:

[start on process definition, start on activity wait, end on activity wait, take transition]

6.5.2. Event propagation

Events are propagated from activities and transitions to outer activities and eventually to the process definition. By default, event listeners are only invoked for events that are fired on the elements on which the event listeners are subscribed. But by specifying propagation="enabled", the event listener will also be invoked for all events that are fired on contained elements.

6.6. Asynchronous continuations

Each invocation of ExecutionService.startProcessInstanceById(...) or ExecutionService.signalProcessInstanceById(...) will cause the process to be executed in the thread it was called from (=client). In other words, those methods will only return after the process execution has arrived in a wait state. This default behaviour has a couple of advantages: user application transactions can be easily propagated to jBPM to that jBPM's DB updates are done in the user's transaction context.

Secondly, it's possible for a client to get an exception in case something goes wrong during execution of the process. Usually, the automatic work that has to be done as part of the process inbetween two wait states is relatively small. Even if multiple automatic activities are executed inbetween 2 wait states. So in most situations, it's good to do all that work in a single transaction. This explains that the default behaviour of jPDL is to perform all work of the process synchronously in the thread of client. For those cases where you don't want the call to jBPM to be blocking until all the automatic work is done, jPDL allows for very fine grained control over transaction boundaries. On various places in the process, asynchronous continuations can be introduced. Asynchronous continuations cause the transaction to commit and the jBPM method invocation will return. jBPM will then start a new transaction in a new thread and continue the rest of the automatic process work asynchronously. jBPM uses asynchronous messaging internally to accomplish this. Upon an asynchronous continuation, an asynchronous message will be sent as part of the currently ongoing transaction. And then the originally invoked method like e.g. startProcessInstanceById(...) or signalProcessInstanceById(...) will return. When the asynchronous message is committed and then processed, it will start a new transaction and resume execution where it left off. Table 6.37. Attribute of any activity, transition or on: Attribute
continue

Type {sync | async | exclusive}

Default Required? sync optional

Description indicates if an asynchronous continuation should be performed before the element is executed.

sync (default) keep executing the element as part of the ongoing transaction. async introduces an asynchronous continuation (aka safe point). The ongoing transaction is committed and the element is executed in a new transaction. Transactional asynchronous messaging is used by the jBPM implementation to achieve this. exclusive introduces a asynchronous continuation (aka safe point). The ongoing transaction is committed and the element is executed in a new transaction. Transactional asynchronous messaging is used by the jBPM implementation to achieve this. Exclusive messages will not be processed concurrently. jBPM will make sure that exclusive jobs for the same process instance are not executed concurrently, even if your jBPM configuration has multiple asynchronous message processors (like the JobExecutor) running on different systems. This can be used to prevent optimistic locking failures in case multiple, potentially conflicting jobs are scheduled in the same transaction.

Let's look at a couple of examples.

6.6.1. Async activity

Figure 6.25. The async activity example process

<process name="AsyncActivity" xmlns="http://jbpm.org/4.4/jpdl"> <start> <transition to="generate pdf"/> </start> <java name="generate pdf" continue="async" class="org.jbpm.examples.async.activity.Application" method="generatePdf" > <transition to="calculate primes"/> </java> <java name="calculate primes" continue="async" class="org.jbpm.examples.async.activity.Application" method="calculatePrimes"> <transition to="end"/> </java> <end name="end"/> </process> public class Application { public void generatePdf() { // assume long automatic calculations here } public void calculatePrimes() { // assume long automatic calculations here } } ProcessInstance processInstance = executionService.startProcessInstanceByKey("AsyncActivity"); String processInstanceId = processInstance.getId();

Without the asynchronous continuations, this would be an all automatic process and the process would execute all the way up to the end in method startProcessInstanceByKey But with continue="async" the execution only goes untill it is about to execute activity generate pdf. Then an asynchronous continuation message is send and the startProcessInstanceByKey method returns. In a normal configuration, the job executor will automatically pick up the message and execute it. But for testing scenarios and for these examples we want to control when messages are executed so the job executor is not configured. Therefore we have to execute the jobs manually like this:

Job job = managementService.createJobQuery() .processInstanceId(processInstanceId) .uniqueResult(); managementService.executeJob(job.getDbid());

That will bring the process until it's about to execute activity calculate primes and again an asynchronous message is send. Then the message can be looked up again and when that message is executed, that transaction will run the execution till the end.

6.6.2. Async fork

Figure 6.26. The async fork example process

<process name="AsyncFork" xmlns="http://jbpm.org/4.4/jpdl"> <start > <transition to="fork"/> </start> <fork > <on event="end" continue="exclusive" /> <transition /> <transition /> </fork> <java class="org.jbpm.examples.async.fork.Application" > <transition /> </java> <java class="org.jbpm.examples.async.fork.Application" > <transition /> </java> <join > <transition to="end"/> </join> <end /> </process> public class Application { public void shipGoods() { // assume automatic calculations here

} public void sendBill() { // assume automatic calculations here } }

By placing the asynchronous continuation on the end event of the fork (<on event="end" continue="exclusive" />), each forked execution that takes a transition out of the fork will be continued asynchronously. Value exclusive was selected to serialize the executions of the 2 asynchonous continuation jobs resulting from the fork. The respective transactions that will execute activities ship goods and send bill will both arrive at the join. At the join, both transactions will synchronize on the same execution (read: update the same execution row in the DB), resulting in a potential optimistic locking failure.
ProcessInstance processInstance = executionService.startProcessInstanceByKey("AsyncFork"); String processInstanceId = processInstance.getId(); List<Job> jobs = managementService.createJobQuery() .processInstanceId(processInstanceId) .list(); assertEquals(2, jobs.size()); Job job = jobs.get(0); // here we simulate execution of the job, // which is normally done by the job executor managementService.executeJob(job.getDbid()); job = jobs.get(1); // here we simulate execution of the job, // which is normally done by the job executor managementService.executeJob(job.getDbid()); Date endTime = historyService .createHistoryProcessInstanceQuery() .processInstanceId(processInstance.getId()) .uniqueResult() .getEndTime(); assertNotNull(endTime);

6.7. User code

Various elements in the jPDL process language refer to a an object on which an interface method will be invoked. This section describes the common attributes and elements for the instantiation and configuration of such user code objects.
custom event-listener assignment-handler

in task

handler in decision condition in transition

6.7.1. User code configuration

Table 6.38. attributes: Attribute
class

Type classname

Default

Required? Description one of The fully qualified classname. Instantiation is {class|expr} is done only once and the user object is cached required as part of the process definition. Expression for which the resulting value will one of be taken as the target object. Expressions will {class|expr} is be evaluated for every usage. In other words, required the resulting value of the evaluation will not be cached.

expr

expression

Table 6.39. user code configuration elements: Element Multiplicity

field property

0..* 0..*

Description describes a configuration value to be injected directly in a memberfield before this user class is used. describes a configuration value to injected through a setter method before this user object is used.

Table 6.40. field and property attributes: Attribute Type Default Required? Description name string required the name of the field or property.

Table 6.41. field and property contained element:

field

and property elements have exactly one child element that represents the value that will be injected. Element Multiplicity Description string 0..1 a java.lang.String
int long float double

0..1 0..1 0..1 0..1

a java.lang.Integer a java.lang.Long a java.lang.Float a java.lang.Double

Element Multiplicity
true false object

Description Boolean.TRUE Boolean.FALSE a object that will be instantiated with reflection

0..1 0..1 0..1

Table 6.42. Attribute for basic type string, int, long, floatand double: Attribute Type Default Required?
value

Description text value that will be parsed to the respective type

text

required

6.7.2. User code classloading

Process definitions are cached. By default, all user code objects are cached as part of those process definitions. For all objects that are referenced by a class name, will be instantiated during parsing time. Which implies that the objects aren't allowed to store non-stateless data (ie which can change). This is typically OK since those objects are in practice almost always immutable. If you do need to use 'dynamic' data in your user code, you can always fall back to process variables (or Environment.get(xxx) calls). Objects that are referenced by an expression are calculated dynamically. The devguide also explains an unsupported attribute to prevent that user objects are cached.