Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Reference Materials for Mule ESB 3
  4. = Reference Materials for Mule ESB 3

  5. BPM Transport Reference

BPM Transport Reference

As of Mule 3.0.1, the recommended way to interact with a BPM system is via the <bpm:process> component and message processor. This approach is documented [here]. Usage of the legacy BPM transport is supported in 3.0.x but was removed in 3.1.

The BPM transport allows Mule events to initiate and/or advance processes in a Business Process Management System (BPMS), also known as a process engine. It also allows executing processes to generate Mule events. For a high-level introduction to Business Process Management with Mule and the concepts involved, read this blog entry.

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

Features

  • Incoming Mule events can launch new processes, advance, or terminate running processes.

  • A running process can send synchronous or asynchronous messages to any Mule endpoint.

  • Synchronous responses from Mule are automatically fed back into the running process and can be stored into process variables.

  • Endpoints of type "bpm://MyProcess" are used to intelligently route process-generated events within Mule.

  • Mule can interact with different running processes in parallel.

BPEL
The connector can only integrate with BPM engines that provide a Java API. If you need to integrate with a BPEL engine that only exposes SOAP endpoints, you will need to use standard web services.

Usage

<model>
    <service name="MessagesToProcess">
        <inbound>
            <jms:inbound-endpoint queue="queueA"/>
        </inbound>
        <outbound>
            <pass-through-router>
                <bpm:outbound-endpoint process="myProcess" />
            </pass-through-router>
        </outbound>
    </service>

    <service name="MessagesFromProcess">
        <inbound>
            <bpm:inbound-endpoint process="myProcess"/>
        </inbound>
        <outbound>
            <bpm:outbound-router>
                <jms:outbound-endpoint queue="queueC"/>
                <jms:outbound-endpoint queue="queueD"/>
            </bpm:outbound-router>
        </outbound>
    </service>
</model>

  • Incoming Mule messages and properties can be stored as process variables, and process variables can be sent as Mule messages. How to configure this depends on the BPMS and its process definition language.

  • Incoming messages from Mule to the BPMS are correlated based on the message property MULE_BPM_PROCESS_ID. If a process already exists with this ID, the message advances the existing process one step. Otherwise, a new process creates and starts. Any outgoing messages generated by the process have MULE_BPM_PROCESS_ID set on them. In the case of an asynchronous response, it is important that your application maintain this property in the response message so that it gets correlated with the correct process instance.

  • The process attribute on the endpoint is used to differentiate among multiple process definitions. For example, a message sent to the endpoint <bpm:outbound-endpoint process="foo" /> starts or advances the process called "foo".

Integration with BPM Engines

One of the basic design principles of Mule is to promote maximum flexibility for the user. Based on this, the user should ideally be able to "plug in" any BPM engine to use with Mule. Unfortunately, there is no standard JEE specification to enable this. Therefore, the Mule BPM Transport simply defines its own simple interface.

public interface BPMS
{
    public Object startProcess(Object processType, Object transition, Map processVariables) throws Exception;

    public Object advanceProcess(Object processId, Object transition, Map processVariables) throws Exception;

    // MessageService contains a callback method used to generate Mule messages from your process.
    public void setMessageService(MessageService msgService);
}

Any BPM engine that implements the interface can "plug in" to Mule via the BPM transport. Currently, the JBoss jBPM engine is the only one included in the Mule distribution. Other implementations may be found on the Anypoint Exchange.

JBoss jBPM

JBoss jBPM is an open source BPMS and is well-integrated with Mule.

jBPM Configuration

To use jBPM with Mule, you need to have two important files on your classpath:

jbpm.cfg.xml

This file contains the jBPM configuration. If defaults are okay, then it could be as simple as the following.

NOTE: Define the MuleMessageService within <process-engine-context> otherwise jBPM cannot "see" Mule.

<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.transport.jbpm.MuleMessageService" />
    </process-engine-context>
</jbpm-configuration>

jbpm.hibernate.cfg.xml

This file contains the Hibernate configuration. jBPM uses Hibernate to persist its objects to an RDBMS, so you need to configure your database settings here. For example, a simple in-memory Derby database might use these 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:muleEmbeddedDB</property>
<property name="hibernate.hbm2ddl.auto">create-drop</property>

While an Oracle database uses these 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>

Mule configuration

Configuring the BPM connector with jBPM is then as simple as using the <bpm:jbpm-connector> element and giving it the location of your process definition(s). These processes load into jBPM when the connector starts up.

<bpm:jbpm-connector name="bpmConnector">
    <bpm:process name="processA" resource="processADef.jpdl.xml" />
    <bpm:process name="processB" resource="processBDef.jpdl.xml" />
</bpm:jbpm-connector>

Process definition (jPDL)

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

<mule-send>

Usage: <mule-send expr="" endpoint="" synchronous="" var="" type="">

Activity which sends a message with the payload expr to the Mule endpoint. If synchronous = true (the default value), the send blocks and the response message stores into var. If the message is not of type, an exception throws. 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-send> example 
<mule-send name="sendToMediumBank" expr="#{loanRequest}" endpoint="MediumBank" var="loanQuote" type="org.mule.example.loanbroker.messages.LoanQuote">

<mule-receive>

Usage: <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 throws.

The attributes are all optional.

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

<mule-receive> example 
<mule-receive name="waitForCreditAgency" endpoint="CreditProfiles" var="creditProfile">