JBoss jBPM 2.0 Tutorial

JBoss jBPM 2.0 Tutorial

jBpm is a workflow management system (WFMS). The next image shows the interfaces between jBpm and all actors involved in the form of a use case diagram.

Figure 1 : Interfaces of a WFMS

Since the term workflow mangament system has a complete different meaning to different people, I will explain the core responsabilities of a workflow management system in four layers. A more detailed description of the 4 layers can be found in the article The State of Workflow

　

jBpm takes process archives as input. A process archive is a formal description of a business process. After a process archive is deployed, jBpm can manage the executions of this process. 'Managing the executions' means keeping track of the state of a process (State layer), storing information associated with a process execution (Context layer), integrating custom programming logic like e.g. sending emails, interacting with an ERP, ... (Programming logic layer) and optionally allow users to complete tasks by submitting forms (User interfaces layer).

Main responsibility

The main responsibility of a WFMS is to maintain the state of process executions. The state model of jBpm is based on a graph with nodes and transitions. Nodes and transitions are the main ingredients of a process definition. A state is an example of a node.

Runtime interaction

The 2 most important interactions with jBpm are : starting one instance (=one execution) of a process definition and signalling the end of a state. As a result of both these interactions jBpm will calculate the next state of the process instance.

Actions

The state graph, provides the structure of the process. Actions are pieces of programming logic that can be executed upon events in the process. There are three types of events : entering a node, leaving a node and taking a transition. While jBpm is calculating the next state, a number of these events will fire.

Process archives

The main file in a process archive is processdefinition.xml. That file contains the formal description of the process. The act of parsing the processdefinition.xml and storing it in the database is called deploying a process. All other files in a process archive are stored as attachments with the process definition (either in the database or as files on the filesystem).

Example

Create a process archive

We have modelled the following process for requesting a pay raise...

The payraise process This process is expressed as xml like this:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE process-definition PUBLIC "-//jBpm/jBpm Mapping DTD 2.0//EN" "http://jbpm.org/dtd/processdefinition-2.0.dtd"> <process-definition name="pay raise process"> ... <!-- START-STATE --> <start-state name="request a payraise" ...> <transition to="evaluating"/> </start-state> <!-- NODES --> <state name="evaluating"> ... <transition name="approve" to="fork"/> <transition name="disapprove" to="done"/> </state> <fork name="fork"> <transition to="updating erp asynchronously" /> <transition to="treating collegues on cake and pie" /> </fork> <state name="updating erp asynchronously"> ... <transition to="join" /> </state> <state name="treating collegues on cake and pie"> ... <transition to="join" /> </state> <join name="join"> <transition to="done" /> </join> <!-- END-STATE --> <end-state name="done" /> </process-definition>

snippet of the processdefinition.xml

Deploy process archive

jBpm store its process definitions in the database. So deploying a process into jbpm actually means parsing the processdefinition.xml and store it in the jbpm database. This can be done in one of 2 ways

1. the jbpm ant-tasks par and deploypar. par lets you create a process archive from a set of files. deploypar deploys a process archive to the database. The deploypar takes a jbpm.properties file as an attribute. That file specifies the jbpm configurations including the database to which the process archive has to be deployed. For more information about the properties, see configuration.
2. programmatically like this:

   // create a process archive input stream String resource = "payraise/processdefinition.xml"; InputStream is = PayRaiseTest .class .getClassLoader() .getResourceAsStream(resource); ArchiveBuilder ab = new ArchiveBuilder(is); JarInputStream jis = ab.getJarInputStream(); // deploy the process DefinitionService ds = JbpmServiceFactory .getInstance() .openDefinitionService(); ds.deployProcessArchive(jis); ds.close();

   code to deploy a process archive
   Note that also this code uses the jbpm.properties for its configuration, including the database to which the process archive is deployed.

Note that the jbpm default configurations points to an hypersonic in-memory database. That is ideal for testing. But this is of little use when using the ant task to deploy your process. In that case, your database will live in the runtime memory of the ant-task so you'll not be able to access it after the ant-task has completed.

　

Start process instance

After packing and deploying this process to the jBpm database, the next code example shows how to start a process instance.

ExecutionService executionService = JbpmServiceFactory.getInstance().openExecutionService("AlbertEinstein"); executionService.startProcessInstance( "payraise" ); executionService.close();

code to start a process instance

Getting a task list

A token is a pointer to a state. In jbpm, every token can point to one actor, thereby creating a relation between a state and an actor. The idea behind this state-actor relation in a token. is the following : when workflow engine enters a state, that means that the workflow engine will be waiting for some external trigger. If the process definition is equipped with a calculation that determines *who* it is waiting for, this calculation is executed when the token enters the state. So the task list will be a collection of tokens that refer to a given actor. Actors in jBpm are always referenced by their id : actorId (java.lang.String).

// get an execution service for user Carl Gauss (cg) ExecutionService executionService = JbpmServiceFactory.getInstance().openExecutionService("cg"); // get the task list for Carl Gauss (cg) Collection tasks = executionService.getTaskList("cg"); executionService.close();

code to get a tasklist

Signal the end of a state

When the process instances was started, jBpm calculated that the next state is 'evaluating' and that user CarlGauss is responsible for this task. This resulted in the token of the process being assigned to 'CarlGauss'. The next snippet asks jBpm all the tokens that are waiting for CarlGauss. In this example we assume that the first task is the one we started above. When CarlGauss has made his decision, he informs jBpm by means of the endOfState method call. Note that in this example we explicitly provide the name of the leaving transition to indicate the choice made by the user.

ExecutionService executionService = JbpmServiceFactory.getInstance().openExecutionService("CarlGauss"); Collection tasks = executionService.getTaskList("CarlGauss"); Token token = (Token) tasks.iterator().next(); executionService.endOfState( token.getId(), "approve" ); executionService.close();

code to signal an end of state

Including an action

Next important aspect of jBpm is including actions in a process definition. An action is a piece of java-code that must be executed upon some event in the process. Suppose for example you want to send a message in a bottle when a the example process is started. Then you'll write first the code that sends the message in a bottle as an ActionHandler...

public class ExampleActionHandler implements ActionHandler { public void execute(ExecutionContext executionContext) { System.out.println( "message in a bottle" ); } }

example action handler code

Then we can create an action on the transition that leaves the start-state like this...

... <start-state name="start"> <transition to="only state"> <action><delegation class="org.jbpm.example.ExampleActionHandler" /></action> </transition> </start-state> ...

jpdl-fragment that puts an action on a transition in processdefinition.xml

Basically, there are 3 event-types on which actions can be placed : taking a transition, entering a node and leaving a node.

Declaring a variable

The variables are persisted in a text field in the database. So when trying to set a variable, jBpm has to know how to convert the object to text. For the following types, jBpm knows how to do this automatic :

• java.lang.String
• java.lang.Long
• java.lang.Date
• java.lang.Double
• java.io.Serializable

Variables of these types don't have to be declared in the processdefinition.xml. jBpm uses lazy creation of those variables, just like a java.util.HashMap.

　

If you want to store other java types as variables, you have to specify a custom serializer in the processdefinition.xml like this :

... <type java-type="org.jbpm.impl.YourCustomJavaType"> <delegation class="org.jbpm.impl.YourCustomSerializer" /> </type> ...

jpdl-fragment that declares a custom serializer The class specified in the delegation (here org.jbpm.impl.YourCustomSerializer) has to implement org.jbpm.delegation.Serializer. Now, jBpm will know how to convert your variables of type org.jbpm.impl.YourCustomJavaType to text for storage in the db.

To avoid that jBpm has to discover automatically the serializer to use, you can specify the variables inside of the type like this :

... <type java-type="org.jbpm.impl.YourCustomJavaType"> <delegation class="org.jbpm.impl.YourCustomSerializer" /> <variable name="your-custom-var-name"> <variable name="your-second-custom-var-name"> </type> ...

jpdl-fragment that declares a custom serializer

The last option is to declare a transient variable. Transient variables can be accessed by ActionHandlers, but they will not be stored into the database. Here's how to declare transient variables :

... <type> <transient /> <variable name="your-transient-var-name"> <variable name="your-second-transient-var-name"> </type> ...

jpdl-fragment that declares transient variables

Accessing a variable as a client

Accessing a variable as an action

Assigning a task