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

  6. JBoss jBPM Module Reference

JBoss jBPM Module Reference

JBoss jBPM is an 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.4/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 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. 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" /> ❶
    </process-engine-context>
</jbpm-configuration>

❶ 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 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 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 is 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. jBPM 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>

<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 blocks and the response message is stored in 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.

<mule-receive>

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

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

    <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 deploys 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> ❶

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

Configuration Reference

Jbpm

Attributes of <jbpm…​>

Name Type Required Default Description

name

name (no spaces)

no

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.

configurationResource

string

no

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

processEngine-ref

string

no

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:

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.4/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/artifactId to include this module as a dependency:

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