xmlns:bpm "http://www.mulesoft.org/schema/mule/bpm"
JBoss jBPM Module Reference
Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version. |
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, read that first and then come back to this page. |
Namespace and Syntax
XML namespace:
XML Schema location:
http://www.mulesoft.org/schema/mule/bpm/3.7/mule-bpm.xsd
Syntax:
<bpm:jbpm />
<bpm:process processName="myProcess" processDefinition="my-process.jpdl.xml" />
Features
-
Simple declaration of jBPM as the BPMS in your Mule configuration using sensible defaults.
-
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.
The jBPM libraries are bundled with the Mule distribution. jBPM 4.4 is the latest supported version. |
Usage
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 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" /> (1)
</process-engine-context>
</jbpm-configuration>
1 | Note that you need to define the MuleMessageService within <process-engine-context> otherwise jBPM cannot "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 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="hibernate.hbm2ddl.auto">create-drop</property>
While an Oracle database uses 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 hibernate.hbm2ddl.auto
. If this is set to create
, Hibernate automatically creates 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 also deletes 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. 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 | Description |
---|---|
<mule-send> |
Activity which sends a message with the payload Usage: <mule-send expr="" endpoint="" exchange-pattern="" var="" type=""> |
<mule-receive> |
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 is thrown. Usage: <mule-receive var="" endpoint="" type=""> |
Configuration Examples
Example Mule Configuration
<mule ...cut...
xmlns:bpm="http://www.mulesoft.org/schema/mule/bpm"
xsi:schemaLocation="...cut...
http://www.mulesoft.org/schema/mule/bpm http://www.mulesoft.org/schema/mule/bpm/3.2/mule-bpm.xsd"> (1)
<bpm:jbpm name="jbpm" /> (2)
<flow name="ToBPMS">
<composite-source>
<inbound-endpoint ref="CustomerRequests" /> (3)
<inbound-endpoint ref="CreditProfiles" />
</composite-source>
<bpm:process processName="LoanBroker" processDefinition="loan-broker-process.jpdl.xml" /> (4)
</flow>
...cut...
</mule>
1 | Import the BPM schema. |
2 | Declare jBPM as the BPMS implementation to use. |
3 | Incoming messages on these endpoints start/advance the process and are stored as process variables. |
4 | The process defined in loan-broker-process.jpdl.xml gets deployed to jBPM at startup. |
Example jPDL Process Definition
<process name="LoanBroker" xmlns="http://www.jbpm.org/4.3/jpdl">
<mule-receive name="incomingCustomerRequest" endpoint="CustomerRequests" type="foo.messages.CustomerQuoteRequest" var="customerRequest">
<transition to="sendToCreditAgency" />
</mule-receive> (1)
<mule-send name="sendToCreditAgency"
expr="#{customerRequest.customer}" endpoint="CreditAgency" exchange-pattern="one-way">
<transition to="sendToBanks" />
</mule-send> (2)
<decision name="sendToBanks"> (3)
<transition to="sendToBigBank">
<condition expr="#{customerRequest.loanAmount >= 20000}" /> (4)
</transition>
<transition to="sendToMediumBank">
<condition expr="#{customerRequest.loanAmount >= 10000}" />
</transition>
...cut...
</decision>
...cut...
<end name="loanApproved" />
</process>
1 | An incoming message is expected on the endpoint CustomerRequests of type foo.messages.CustomerQuoteRequest and is stored into the process variable customerRequest . |
2 | A new message is sent to the endpoint CreditAgency whose payload is an expression using the process variable customerRequest . |
3 | <decision> is a standard jPDL element. |
4 | The decision logic uses the process variable customerRequest . |
<mule ...cut...
<bpm:jbpm name="jbpm" />
<model>
<service name="ToBPMS"> (1)
<inbound>
<inbound-endpoint ref="CustomerRequests" />
<inbound-endpoint ref="CreditProfiles" />
</invound>
<bpm:process processName="LoanBroker" processDefinition="loan-broker-process.jpdl.xml" />
</service>
...cut...
</model>
</mule>
1 | New implementations are recommended to use flows, but Mule 2.x users will be more familiar with services. |
Jbpm
Attributes of <jbpm…>
Name | Description |
---|---|
name |
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. Type: name (no spaces) |
configurationResource |
The configuration file for jBPM, default is "jbpm.cfg.xml" if not specified. Type: string |
processEngine-ref |
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 is ignored in this case. Type: string |
No Child Elements of <jbpm…>
XML Schema
This module uses the schema from the BPM Module; it does not have its own schema.
Import the BPM schema as follows:
xmlns:bpm="http://www.mulesoft.org/schema/mule/bpm"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/bpm http://www.mulesoft.org/schema/mule/bpm/3.6/mule-bpm.xsd"
Refer to BPM Module Reference for detailed information on the elements of the BPM schema.