You are viewing an older version of this section. Click here to navigate to the latest version.

JBoss jBPM Module Reference


JBoss jBPM is a best-of-breed open source BPMS and is well-integrated with Mule. One advantage of jBPM is that it is embedded directly in the Mule runtime, allowing for faster performance. For general information on jBPM and how to configure it, refer to the jBPM User Guide

This module provides a "Plug-in" for JBoss jBPM to be used with Mule’s BPM support. If you have not yet read the general documentation for Mule’s BPM Support, please read that first and then come back to this page.

Namespace and Syntax

XML namespace:

xmlns:bpm ""

XML Schema location:



<bpm:jbpm /><bpm:process processName="myProcess" processDefinition="my-process.jpdl.xml" />


  • MULE3USER:Simple declaration of jBPM as the BPMS in your Mule configuration using sensible defaults.

  • MULE3USER:Custom elements for jBPM’s process definition language (jPDL) which allow you to easily integrate Mule into your business processes.

Refer to BPM Module Reference for a list of general features offered by Mule’s BPM support.

To see jBPM with Mule in action, take a look at the Loan Broker BPM Example (available in the full Mule distribution).

The jBPM libraries are bundled with the Mule distribution. As of Mule 3.0.1, jBPM 4.4 is the latest supported version.


Using jBPM with Mule consists of a few things:

  • Configuring jBPM

  • Configuring Hibernate and the database used to store process state

  • Declaring jBPM as the BPMS to use in your Mule configuration

  • Interacting with Mule from your process definition

jBPM Configuration

The default configuration file for jBPM is called jbpm.cfg.xml. You will need to include this file as part of your Mule application. If defaults are ok for you, then it could be as simple as the following.

jBPM Configuration (jbpm.cfg.xml)

<jbpm-configuration>    <import resource="jbpm.default.cfg.xml" />    <import resource="jbpm.jpdl.cfg.xml" />    <import resource="jbpm.tx.hibernate.cfg.xml" />    <process-engine-context>        <object class="org.mule.module.jbpm.MuleMessageService" /></process-engine-context></jbpm-configuration>

❶ Note that you need to define the MuleMessageService within <process-engine-context> otherwise jBPM will not be able to "see" Mule.

For more configuration options, refer to the jBPM documentation.

Database Configuration

jBPM uses Hibernate to persist the state of your processes, so you will need to provide a database supported by Hibernate and include any client jars as part of your Mule application. You also need to provide the file jbpm.hibernate.cfg.xml with the appropriate Hibernate settings for your chosen database.

For example, a simple in-memory Derby database might use these settings:

Derby settings

  <property name="hibernate.dialect">org.hibernate.dialect.DerbyDialect</property>  <property name="hibernate.connection.driver_class">org.apache.derby.jdbc.EmbeddedDriver</property>  <property name="hibernate.connection.url">jdbc:derby:memory:muleEmbeddedDB</property>  <property name="">create-drop</property>

while an Oracle database might use these settings:

Oracle settings

  <property name="hibernate.dialect">org.hibernate.dialect.OracleDialect</property>  <property name="hibernate.connection.driver_class">oracle.jdbc.driver.OracleDriver</property>  <property name="hibernate.connection.url">jdbc:oracle:thin:user/pass@server:1521:dbname</property>

One very important Hibernate setting to pay attention to is If this is set to create, Hibernate will automatically create the DB schema for jBPM at startup if it does not yet exist in your database. If it is set to create-drop, the schema will also be deleted at shutdown, which is useful in test environments.

For more configuration options, refer to the jBPM documentation and/or Hibernate documentation.

Mule configuration

Using jBPM in your Mule configuration is then as simple as including the <bpm:jbpm> element. The default configuration file is assumed to be jbpm.cfg.xml, otherwise you can specify it with the configurationResource attribute.

Default config

<bpm:jbpm />

Custom config

<bpm:jbpm name="jBPM" configurationResource="custom-jbpm-config.cfg.xml"/>

Process definition (jPDL)

For lack of a good standard in the BPM community, jBPM has traditionally used its own DSL for process definitions called jPDL. You will find that it is very easy to learn, and there is an Eclipse plug-in called the Graphical Process Designer which allows you to create your process definitions visually as well.

In future versions, the preferred definition language will likely be BPMN 2.0, which is now a widely-accepted standard in the BPM community. Mule currently support BPMN-defined processes through the Activiti BPM Module.

Mule provides two custom elements for jBPM’s process definition language (jPDL). You can use these in your process definition along with other standard jPDL elements such as <state>, <java>, <script>, <decision>.

Element Usage Description Required Attributes


<mule-send expr="" endpoint="" exchange-pattern="" var="" type="">

Activity which sends a message with the payload expr to the Mule endpoint. If exchange-pattern = request-response (the default value), the send will block and the response message will be stored into var. If the message is not of type, an exception will be thrown. expr can be a literal value or an expression which references process variables.

The only mandatory attributes are expr and endpoint, the rest are optional.


<mule-receive var="" endpoint="" type="">

Wait state which expects a message to arrive from the Mule endpoint and stores it into var. If the message is not of type, an exception will be thrown. <mule-receive> can replace <start> as the first state of a process and this way you can store the message which initiated the process into a variable.

The attributes are all optional.

Configuration Examples

Example Mule Configuration

<mule ...cut...    xmlns:bpm=""    xsi:schemaLocation="...cut..."><bpm:jbpm name="jbpm" /><flow name="ToBPMS">        <composite-source>            <inbound-endpoint ref="CustomerRequests" /><inbound-endpoint ref="CreditProfiles" />        </composite-source>        <bpm:process processName="LoanBroker" processDefinition="loan-broker-process.jpdl.xml" /></flow>    ...cut...</mule>

❶ Import the BPM schema.
❷ Declare jBPM as the BPMS implementation to use.
❸ Incoming messages on these endpoints start/advance the process and are stored as process variables.
❹ The process defined in loan-broker-process.jpdl.xml will get deployed to jBPM at startup.

Example jPDL Process Definition

<process name="LoanBroker" xmlns="">    <mule-receive name="incomingCustomerRequest" endpoint="CustomerRequests" type="foo.messages.CustomerQuoteRequest" var="customerRequest">        <transition to="sendToCreditAgency" />    </mule-receive><mule-send name="sendToCreditAgency"          expr="#{customerRequest.customer}" endpoint="CreditAgency" exchange-pattern="one-way">        <transition to="sendToBanks" />    </mule-send><decision name="sendToBanks"><transition to="sendToBigBank">            <condition expr="#{customerRequest.loanAmount >= 20000}" /></transition>        <transition to="sendToMediumBank">            <condition expr="#{customerRequest.loanAmount >= 10000}" />        </transition>        ...cut...    </decision>    ...cut...    <end name="loanApproved" /></process>

❶ An incoming message is expected on the endpoint CustomerRequests of type foo.messages.CustomerQuoteRequest and is stored into the process variable customerRequest.
❷ A new message is sent to the endpoint CreditAgency whose payload is an expression using the process variable customerRequest.
<decision> is a standard jPDL element.
❹ The decision logic uses the process variable customerRequest.

Example Mule Configuration with <service>

<mule ...cut...  <bpm:jbpm name="jbpm" />   <model>    <service name="ToBPMS"><inbound>            <inbound-endpoint ref="CustomerRequests" />             <inbound-endpoint ref="CreditProfiles" />        </invound>        <bpm:process processName="LoanBroker" processDefinition="loan-broker-process.jpdl.xml" />     </service>    ...cut...  </model></mule>

❶ New implementations are recommended to use flows, but Mule 2.x users will be more familiar with services.


Configuration Reference


Attributes of <jbpm…​>

Name Type Required Default Description


name (no spaces)


An optional name for this BPMS. Refer to this from the "bpms-ref" field of your process in case you have more than one BPMS available.




The configuration file for jBPM, default is "jbpm.cfg.xml" if not specified.




A reference to the already-initialized jBPM ProcessEngine. This is useful if you use Spring to configure your jBPM instance. Note that the "configurationResource" attribute will be ignored in this case.

Child Elements of <jbpm…​>

Name Cardinality Description

XML Schema

This module uses the schema from the BPM Module, it does not have its own schema.

Import the BPM schema as follows:


Refer to BPM Module Reference for detailed information on the elements of the BPM schema.


If you are using Maven to build your application, use the following groupId/artifactId to include this module as a dependency:

<dependency>  <groupId>org.mule.modules</groupId>  <artifactId>mule-module-jbpm</artifactId></dependency>