JBoss jBPM 2.0 Tutorial

原创 2006年06月26日 10:39:00

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.


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


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"

<process-definition name="pay raise process"> 
  <!-- START-STATE -->
  <start-state name="request a payraise" ...>
    <transition to="evaluating"/>

  <!-- NODES -->
  <state name="evaluating">
    <transition name="approve"     to="fork"/>
    <transition name="disapprove"  to="done"/>
  <fork name="fork">
    <transition to="updating erp asynchronously" />
    <transition to="treating collegues on cake and pie" />

  <state name="updating erp asynchronously">
    <transition to="join" />

  <state name="treating collegues on cake and pie">
    <transition to="join" />
  <join name="join">
    <transition to="done" />

  <!-- END-STATE -->
  <end-state name="done" />

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
    ArchiveBuilder ab = new ArchiveBuilder(is);
    JarInputStream jis = ab.getJarInputStream();
    // deploy the process
    DefinitionService ds = JbpmServiceFactory
    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 = 
executionService.startProcessInstance( "payraise" );
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");
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 = 
Collection tasks = executionService.getTaskList("CarlGauss");
Token token = (Token) tasks.iterator().next();
executionService.endOfState( token.getId(), "approve" );
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>
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" />
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">
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 :

  	<transient />
  	<variable name="your-transient-var-name">
  	<variable name="your-second-transient-var-name">
jpdl-fragment that declares transient variables

Accessing a variable as a client

Accessing a variable as an action

Assigning a task

JBOSS jBPM 工作流管理系统简介

jBPM,全称是Java Business Process Management,是一种基于J2EE的轻量级工作流管理系统。jBPM是公开源代码项目,它使用要遵循 Apache License。jBP...
  • kellerdu
  • kellerdu
  • 2004年11月04日 10:54
  • 7924

JBoss 系列七十一:jBPM 6 发布,快速安装,新功能介绍

概述 jBPM 6.0 最终版已与上月底发布,本文主要从两个方面去介绍jBPM 6.0 : 快速安装新功能介绍 快速安装 快速安装包括如下三步: 1. 下载安装包 从http://sou...
  • kylinsoong
  • kylinsoong
  • 2013年12月23日 17:36
  • 19110

JBoss jBPM入门手册(JBoss jBPM getting started guide)

原文出自  http://wiki.jboss.org/wiki/Wiki.jsp?page=JbpmGettingStarted  JBoss jBPM getting started guide ...
  • JefferyLee
  • JefferyLee
  • 2007年05月27日 17:18
  • 1464

JBoss 系列八十二: jBPM 6 快速开始的三段视频

本文包括三段视频说明如何快速开始使用 jBPM 6 创建执行流程。 视频一 如jBPM 6 中使用 jbpm-console 创建执行 BPM 流程 - I中所示,本视频演示如何在 jBPM cons...
  • kylinsoong
  • kylinsoong
  • 2014年01月09日 09:11
  • 6172


工作中要用到JBPM写工作流,自习的时候找到一篇较好的文章,贴过来共享下! 示例:在某一公司中,部门员工要休假的话需要部门主管的批准。如果休假天数大于10天的话,在部门主管的同意后,还必须上级主管批准...
  • princewong
  • princewong
  • 2007年07月05日 09:23
  • 914

JBoss jBPM工作流定义部署

  • dotyboy
  • dotyboy
  • 2006年11月24日 23:23
  • 676


1、下载对应的jbpm版本(是zip的) ,解压缩到任意盘下 2、 在MyEclipse8.5安装目录下(这是我的安装目录D:/soft/Genuitec/MyEclipse 8.5 M1/dr...
  • sun_abc
  • sun_abc
  • 2011年02月15日 09:42
  • 3108


    由于国内对JBPM的研究较少,我们在研究该工作流研究后特把本手册公布出来,希望对大家有所帮助,手册由陆义平整理主要包括如下几点:   1.  如何在一个干净的JBoss服务器上安装Jbpm3....
  • xliujun
  • xliujun
  • 2006年07月14日 11:38
  • 2740

JBoss 系列七十四:使用 BPMN2 Modeler 创建 jBPM 6 流程

概述 流程设计在BPM中占很重要的地位,本文演示如何使用 BPMN2 Modeler 创建一个BPMN流程,并运行该流程,如前面 jBPM 6 开发 eclipse 插件安装中介绍的,插件安装完成B...
  • kylinsoong
  • kylinsoong
  • 2013年12月26日 16:24
  • 12039

JBoss 系列六十二:深入理解 jBPM Human Task - II(使用JMS做传输媒介执行Human Task)

概述 本文是继深入理解 jBPM Human Task - I,对使用JMS做传输类型过程中服务器端和客户端业务逻辑的明细。本文也是基于之前代码分析系列: 服务器端代码 - jBPM Human ...
  • kylinsoong
  • kylinsoong
  • 2013年12月02日 10:50
  • 2514
您举报文章:JBoss jBPM 2.0 Tutorial