jBPM User Guide

The script task defines a script that needs to be executed when the task is reached. In this case, the script invokes an existing class org.jbpm.examples.quickstarts.HelloService:

HelloService.getInstance().sayHello(person.getName());

where the HelloService class looks like this:

package org.jbpm.examples.quickstarts;

public class HelloService {

  private static final HelloService INSTANCE = new HelloService();

  public static HelloService getInstance() {

    return INSTANCE;

  }

  public void sayHello(String name) {

    System.out.println("Hello " + name);

  }

}

The script retrieves an instance of the HelloService and passes it the name of the person that started this process. This is possible because person is defined as a variable of the process, of type org.jbpm.examples.quickstarts.Person, and script tasks can directly reference process variables as if they were local variables (at least for reading, for setting the value of a variable, you should use kcontext.setVariable(name, value)). This process also references HelloService without fully qualifying the package as HelloService is defined using an import statement.

The underlying XML might look something like this:

<?xml version="1.0" encoding="UTF-8"?> 

<definitions id="Definition"

             targetNamespace="http://www.jboss.org/drools"

             typeLanguage="http://www.java.com/javaTypes"

             expressionLanguage="http://www.mvel.org/2.0"

             xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"

             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

             xsi:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL BPMN20.xsd"

             xmlns:g="http://www.jboss.org/drools/flow/gpd"

             xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"

             xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"

             xmlns:di="http://www.omg.org/spec/DD/20100524/DI"

             xmlns:tns="http://www.jboss.org/drools">

  <itemDefinition id="_personItem" structureRef="org.jbpm.examples.quickstarts.Person" />

  <process processType="Private" isExecutable="true" id="org.jbpm.examples.quickstarts.script" 

           name="Sample Process" tns:packageName="defaultPackage" >

    <extensionElements>

      <tns:import name="org.jbpm.examples.quickstarts.HelloService" />

    </extensionElements>

    <!-- process variables -->

    <property id="person" itemSubjectRef="_personItem"/>

    <!-- nodes -->

    <startEvent id="_1" name="StartProcess" />

    <scriptTask id="_2" name="Script" >

      <script>HelloService.getInstance().sayHello(person.getName());</script>

    </scriptTask>

    <endEvent id="_3" name="End" >

      <terminateEventDefinition/>

    </endEvent>

    <!-- connections -->

    <sequenceFlow id="_1-_2" sourceRef="_1" targetRef="_2" />

    <sequenceFlow id="_2-_3" sourceRef="_2" targetRef="_3" />

  </process>

  <bpmndi:BPMNDiagram>

    <bpmndi:BPMNPlane bpmnElement="org.jbpm.examples.quickstarts.script" >

      <bpmndi:BPMNShape bpmnElement="_1" >

        <dc:Bounds x="45" y="45" width="48" height="48" />

      </bpmndi:BPMNShape>

      <bpmndi:BPMNShape bpmnElement="_2" >

        <dc:Bounds x="131" y="46" width="80" height="48" />

      </bpmndi:BPMNShape>

      <bpmndi:BPMNShape bpmnElement="_3" >

        <dc:Bounds x="252" y="47" width="48" height="48" />

      </bpmndi:BPMNShape>

      <bpmndi:BPMNEdge bpmnElement="_1-_2" >

        <di:waypoint x="69" y="69" />

        <di:waypoint x="171" y="70" />

      </bpmndi:BPMNEdge>

      <bpmndi:BPMNEdge bpmnElement="_2-_3" >

        <di:waypoint x="171" y="70" />

        <di:waypoint x="276" y="71" />

      </bpmndi:BPMNEdge>

    </bpmndi:BPMNPlane>

  </bpmndi:BPMNDiagram>

</definitions>

A simple test that executes this process could look something like this: simply create a ksession and start the process by id, passing in a Person object that will then be set as the person process variable:

public class JavaServiceQuickstartTest extends JbpmJUnitTestCase {

  @Test

  public void testProcess() {

    StatefulKnowledgeSession ksession = createKnowledgeSession("test.bpmn");

    Map<String, Object> params = new HashMap<String, Object>();

    params.put("person", new Person("krisv"));

    ksession.startProcess("org.jbpm.examples.quickstarts.script", params);

  }

}

This example shows how easy it is to include custom Java code in your process using Script Tasks, to invoke existing code and to pass it process variable values. Note that some node types allow you to specify on-entry and on-exit actions (which will be executed when the node is triggered or left respectively). This allows you to include scripts, just like you would do when using a Script Task, but hiding these more or less from the diagram (as for example business users might not be interested in these details).

The process editor consists of a palette, a canvas and an outline view. To add new elements to the canvas, select the element you would like to create in the palette and then add them to the canvas by clicking on the preferred location. For example, click on the "End Event" icon in the "Components" palette of the GUI. Clicking on an element in your process allows you to set the properties of that element. You can connect the nodes (as long as it is permitted by the different types of nodes) by using "Sequence Flow" from the "Components" palette.

You can keep adding nodes and connections to your process until it represents the business logic that you want to specify.

The start of the process. A process should have exactly one start node, which cannot have incoming connections and should have one outgoing connection. Whenever a process is started, execution will start at this node and automatically continue to the first node linked to this start event, and so on. It contains the following properties:

Represents a script that should be executed in this process. A Script Task should have one incoming connection and one outgoing connection. The associated action specifies what should be executed, the dialect used for coding the action (i.e., Java or MVEL), and the actual action code. This code can access any variables and globals. There is also a predefined variable kcontext that references the ProcessContext object (which can, for example, be used to access the current ProcessInstance or NodeInstance, and to get and set variables, or get access to the ksession using kcontext.getKnowledgeRuntime()). When a Script Task is reached in the process, it will execute the action and then continue with the next node. It contains the following properties:

Note that you can write any valid Java code inside a script node. This basically allows you to do anything inside such a script node. There are some caveats however:

Represents an (abstract) unit of work that should be executed in this process. All work that is executed outside the process engine should be represented (in a declarative way) using a Service Task. Different types of services are predefined, e.g., sending an email, logging a message, etc. Users can define domain-specific services or work items, using a unique name and by defining the parameters (input) and results (output) that are associated with this type of work. Check the chapter on domain-specific processes for a detailed explanation and illustrative examples of how to define and use work items in your processes. When a Service Task is reached in the process, the associated work is executed. A Service Task should have one incoming connection and one outgoing connection.

Processes can also involve tasks that need to be executed by human actors. A User Task represents an atomic task to be executed by a human actor. It should have one incoming connection and one outgoing connection. User Tasks can be used in combination with Swimlanes to assign multiple human tasks to similar actors. Refer to the chapter on human tasks for more details. A User Task is actually nothing more than a specific type of service node (of type "Human Task"). A User Task contains the following properties:

A user task should define the type of task that needs to be executed (using properties like TaskName, Comment, etc.) and who needs to perform it (using either actorId or groupId). Note that if there is data related to this specific process instance that the end user needs when performing the task, this data should be passed as the content of the task. The task for example does not have access to process variables. Check out the chapter on human tasks to get more detail on how to pass data between human tasks and the process instance.

Represents the invocation of another process from within this process. A sub-process node should have one incoming connection and one outgoing connection. When a Reusable Sub-Process node is reached in the process, the engine will start the process with the given id. It contains the following properties:

A Business Rule Task Represents a set of rules that need to be evaluated. The rules are evaluated when the node is reached. A Rule Task should have one incoming connection and one outgoing connection. Rules are defined in separate files using the Drools rule format. Rules can become part of a specific ruleflow group using the ruleflow-group attribute in the header of the rule.

When a Rule Task is reached in the process, the engine will start executing rules that are part of the corresponding ruleflow-group (if any). Execution will automatically continue to the next node if there are no more active rules in this ruleflow group. As a result, during the execution of a ruleflow group, new activations belonging to the currently active ruleflow group can be added to the Agenda due to changes made to the facts by the other rules. Note that the process will immediately continue with the next node if it encounters a ruleflow group where there are no active rules at that time.

If the ruleflow group was already active, the ruleflow group will remain active and execution will only continue if all active rules of the ruleflow group has been completed. It contains the following properties:

A Sub-Process is a node that can contain other nodes so that it acts as a node container. This allows not only the embedding of a part of the process within such a sub-process node, but also the definition of additional variables that are accessible for all nodes inside this container. A sub-process should have one incoming connection and one outgoing connection. It should also contain one start node that defines where to start (inside the Sub-Process) when you reach the sub-process. It should also contain one or more end events. Note that, if you use a terminating event node inside a sub-process, you are terminating the top-level process instance, not just that sub-process, so in general you should use non-terminating end nodes inside a sub-process. A sub-process ends when there are no more active nodes inside the sub-process. It contains the following properties:

A Multiple Instance sub-process is a special kind of sub-process that allows you to execute the contained process segment multiple times, once for each element in a collection. A multiple instance sub-process should have one incoming connection and one outgoing connection. It waits until the embedded process fragment is completed for each of the elements in the given collection before continuing. It contains the following properties:

Allows you to create branches in your process. A Diverging Gateway should have one incoming connection and two or more outgoing connections. There are three types of gateway nodes currently supported:

It contains the following properties:

Allows you to synchronize multiple branches. A Converging Gateway should have two or more incoming connections and one outgoing connection. There are two types of splits currently supported:

It contains the following properties:

During the execution of a process, the process engine makes sure that all the relevant tasks are executed according to the process plan, by requesting the execution of work items and waiting for the results. However, it is also possible that the process should respond to events that were not directly requested by the process engine. Explicitly representing these events in a process allows the process author to specify how the process should react to such events.

Events have a type and possibly data associated with them. Users are free to define their own event types and their associated data.

A process can specify how to respond to events by using a Message Event. An Event node needs to specify the type of event the node is interested in. It can also define the name of a variable, which will receive the data that is associated with the event. This allows subsequent nodes in the process to access the event data and take appropriate action based on this data.

An event can be signaled to a running instance of a process in a number of ways:

Events could also be used to start a process. Whenever a Message Start Event defines an event trigger of a specific type, a new process instance will be started every time that type of event is signalled to the process engine.