Contact Free trial Login

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

BPM stands for Business Process Management and simplistically can be thought of as a system which automates business processes. Typically a BPM system has a graphical interface which allows you to model your business processes visually so that a business analyst or other non-programmer can easily understand them and verify that they indeed reflect the reality of your business.

Mule’s support for BPM allows you to send/receive messages to/from a running process. A message from Mule can start or advance a process, the message can be stored as a process variable, and a running process can send messages to any endpoint in your Mule application.

Mule can interact with many kinds of BPM systems. Integrations are readily available for several popular implementations and integrating with a new system is Writing a BPMS Plug-in.


If the business logic for your Mule application is relatively simple, does not change very often, and is mostly stateless, you are probably best off implementing it using Mule’s orchestration functionality such as flows, routers, and custom components.

However, you might consider using BPM to model your business logic in the following cases:

  • If the execution in your flow has many discrete steps and/or multiple paths based on decision criteria, modeling it as a process may help better visualize it.

  • If your business logic is in constant flux, BPM might be a good way to decouple the logic from your integration.

  • If your business logic or processes need to be reviewed or updated by non-programmers, BPM makes that possible.

  • If a flow does not go from start to finish within a few minutes, it’s probably a good candidate for BPM because intermediate process state is persisted so it does not need to be held in memory.

  • If your integration requires human input, BPM lets you add a human step to your process via task management and a web app.

  • If your application needs a step-by-step audit trail, BPM might be a good option because process history is kept in a database.

It is likely that a BPM engine would add some performance overhead. If high-performance is critical to your application, you should consider using Mule’s orchestration instead to model your process.

Namespace and Syntax

XML namespace:

xmlns:bpm ""

XML Schema location:


<bpm:process processName="myProcess" processDefinition="myProcess.xml" />


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

  • Mule can interact with different running processes in parallel.


Import the XML schema for this module as follows:


Then you can use the <bpm:process> element as follows, generally preceded by an inbound endpoint. See the example configuration, below.

<bpm:process processName="myProcess" processDefinition="myProcess.xml" />
  • At a minimum, when triggering a BPM process, you must specify the processName and processDefinition attributes in the <bpm:process> element. The syntax of these elements are specific to the BPMS implementation you are using.

  • 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 specific BPMS and its process definition language. For supported implementations, like jBPM, please see the relevant module documentation.

  • 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, then the message advances the existing process one step. Otherwise, a new process will be created and started. 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. If you wish to use a different message property for tracking the process ID, you can specify it using the processIdField attribute.

  • The BPMS being used (any system which implements the Javadoc interface described below) must be declared at the top of your Mule configuration. This may be a dedicated XML element if one is provided for your BPMS (such as <bpm:jbpm>) or a Spring bean in the case of a custom implementation or integration. If more than one BPMS is being used in your application, you must specify the bpms-ref attribute on the <bpm:process> element to disambiguate, otherwise the BPMS will be found automatically from Mule’s object registry (akin to the connector-ref attribute on an <endpoint>).

Configuration Examples

Example configuration

<mule ... xmlns:bpm=""
    xsi:schemaLocation="" ...>

  <spring:bean id="testBpms" class="" /> ❸

  <flow name="MessagesToProcess">
      <jms:inbound-endpoint queue="queueA" /> ❶
      <bpm:process processName="myProcess" processDefinition="myProcess.xml" /> ❷

  <flow name="SomeSynchronousService">
      <inbound-endpoint ref="callService" exchange-pattern="REQUEST-RESPONSE" /> ❹
      <component class="" /> ❺

In this configuration, an inbound message on the JMS queue ❶ triggers the process defined by the file "myProcess.xml" ❷, whose format depends on the underlying BPMS. The inbound message is stored as a process variable. The BPMS which deploys and runs the process is that defined by the class ❸. Since there is only one implementation in the application, no explicit reference is required. A step in the process definition might send a message to the endpoint callService ❹, in which case the synchronous response from ❺ could be also be stored as a process variable. Note that since this logic occurs in the process definition, it is not visible in the Mule configuration.

Multiple BPMS’s

<spring:bean id="bpms1" class="" />

<spring:bean id="bpms2" class="" />

<flow name="ProcessFlow1">
    <bpm:process processName="process1" processDefinition="process1.def" bpms-ref="bpms1" ❶ />

<flow name="ProcessFlow2">
    <bpm:process processName="process2" processDefinition="process2.cfg" bpms-ref="bpms2" ❷ />

This configuration snippet illustrates how to use the bpms-ref attribute ❶ ❷ to disambiguate between more than one BPMS’s. If there is only one BPMS available, this attribute is unnecessary.

BPMS Support

The Mule distribution includes native support for JBoss jBPM, a popular embeddable BPMS. For information see JBoss jBPM Module Reference.

Other BPMS solutions are:

Support for JBoss jBPM is included in the Mule distribution, for information see JBoss jBPM Module Reference.

Writing a BPMS Plug-in

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 system or even their own custom BPMS implementation to use with Mule. Unfortunately, there is no standard JEE specification to enable this. Therefore, Mule 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 system that implements the interface (org.mule.module.bpm.BPMS) can "plug in" to Mule via the BPM module. Creating a connector for an existing BPM system can be as simple as creating a wrapper class that maps this interface to the native APIs of that system.

Configuration Reference



A process backed by a BPMS such as jBPM.

Attributes of <process…​>

Name Description


An optional reference to the underlying BPMS. This is used to disambiguate in the case where more than one BPMS is available.

Type: string
Required: no
Default: none


The logical name of the process. This is used to look up the running process instance from the BPMS.

Type: string
Required: yes
Default: none


The resource containing the process definition, this will be used to deploy the process to the BPMS. The resource type depends on the BPMS being used.

Type: string
Required: yes
Default: none


This field is used to correlate Mule messages with processes. If not specified, it will default to MULE_BPM_PROCESS_ID.

Type: string
Required: no
Default: none

No Child Elements of <process…​>

XML Schema


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



  • This module is designed for BPM engines that provide a Java API. If you need to integrate with a BPEL engine, you can do so using standard web services.

  • The recommended way to interact with a BPM system is via the <bpm:process> component and message processor.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub