jBPM User Guide

<process name="StateSequence" xmlns="http://jbpm.org/4.0/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:

Execution execution = executionService.startProcessInstanceByKey("StateSequence");

the created process instance will be positioned in state a. Providing an external trigger can be done with the signalExecution methods.

String executionId = execution.getId();
execution = executionService.signalExecutionById(executionId);

<process name="StateChoice" xmlns="http://jbpm.org/4.0/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:

Execution execution = executionService.startProcessInstanceByKey("StateSequence");

Now, the execution is 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:

executionService.signalExecutionById(executionId, "accept");

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.

Example:

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

Example:

<process name="Poolcar">
  <start>
    <transition to="How far?" />
  </start>
  <decision name="How far?" expr="#{distance}">
    <transition name="far"    to="Big car" />
    <transition name="nearby" to="Small car" />
  </decision>
  <state name="Big car" />
  <state name="Small car" />
</process>

When you start an new process instance like this

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("distance", "far");
Execution execution = executionService.startProcessInstanceByKey("Poolcar", variables);

then the new execution will go to activity Big car.

Here's an example process of a decision using a DecisionHandler:

<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 select(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.

<process name="EndProcessInstance" xmlns="http://jbpm.org/4.0/jpdl">

  <start>
    <transition to="end" />
  </start>

  <end name="end" />

</process>

When a new process instance is created, it immediately ends.

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

Execution execution = executionService.startProcessInstanceByKey("EndMultiple");
String executionId = execution.getId();
execution = executionService.signalExecutionById(executionId, "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.

Take for example the following process.

<process name="EndState" xmlns="http://jbpm.org/4.0/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.

Execution execution = executionService.startProcessInstanceByKey("EndState");
String executionId = execution.getId();
execution = executionService.signalExecutionById(executionId, "400");
        

Similarly as above, using the value 200 or 500 would cause the execution to end with the completed or with the error states respectively.

<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"));
Execution execution = executionService
    .startProcessInstanceByKey("TaskAssignee", variables);

Then the task list for johndoe can be obtained like this.

List<Task> taskList = taskService.findAssignedTasks("johndoe");

Note that it is also possible to put plain text like assignee="johndoe". In that case the task will be assigned to johndoe.

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.getAssignedTasks("johndoe");
taskService.getAssignedTasks("joesmoe");

But the task will show up in the takable 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 takable tasks for users johndoe and joesmoe

taskService.findTakableTasks("johndoe");
taskService.findTakableTasks("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 takable 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 takable 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.

<process name="TaskAssignmentHandler" xmlns="http://jbpm.org/4.0/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.

Swimlanes can be declared inside a process element:

The task swimlane example has the following process file :

<process name="TaskSwimlane" xmlns="http://jbpm.org/4.0/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.

<process name="SubProcessDocument" xmlns="http://jbpm.org/4.0/jpdl">

  <start>
    <transition to="review" />
  </start>

  <sub-process name="review"
               sub-process-key="SubProcessReview">
               
    <variable name="document" init="#{document}" />
    <out-variable name="reviewResult" init="#{result}" />
    
    <transition to="wait" />
  </sub-process>
  
  <state name="wait"/>

</process>

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

<process name="SubProcessReview" xmlns="http://jbpm.org/4.0/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.findAssignedTasks("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.

taskService.setVariable(task.getDbid(), "result", "accept");

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.

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

<process name="SubProcessReview" xmlns="http://jbpm.org/4.0/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.findAssignedTasks("johndoe");
Task task = taskList.get(0);
        

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

taskService.setVariable(task.getDbid(), "result", "ok");
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.

<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:

<process name="SubProcessReview" xmlns="http://jbpm.org/4.0/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.findAssignedTasks("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.

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

<process name="ScriptExpression" xmlns="http://jbpm.org/4.0/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'.

For example

<process name="ScriptText" xmlns="http://jbpm.org/4.0/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>