Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.5)
  3. Reference
  4. Modules Reference
  5. BPM Module Reference

  6. JBoss jBPM Module Reference

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], please read that first and then come back to this page.

Namespace and Syntax

XML Namespace:

xmlns:bpm "http://www.mulesoft.org/schema/mule/bpm"

XML Schema Location:

http://www.mulesoft.org/schema/mule/bpm/3.5/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. As of Mule 3.0.1, jBPM 4.4 is the latest supported version.

Usage

Using jBPM with Mule consists of 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 okay 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 Mule Message Service 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 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>, <decision>.

Element Description

<mule-send>

Activity which sends a message with the payload expr to the Mule endpoint. If exchange-pattern = request-response (the default value), the send blocks and the response message is stored into var. If the message is not of type, an exception is 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.

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

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.5/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://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.

jBPM

Table 1. 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)
Required: No
Default: None

configurationResource

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

Type: string
Required: No
Default: None

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
Required: No
Default: None

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.5/mule-bpm.xsd"

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

Maven

If you are using Maven to build your application, use the following groupID and artifactID to include this module as a dependency:

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