This project focuses on bringing two great Open Source frameworks closer together, the camunda BPM platform and Apache Camel.

Having started as a fork of Activiti's Apache Camel module, we have in the meantime refactored the whole codebase and we will steadily adding features. Watch this space!

Supported features

See example project 'camel use cases' for code for all of the use cases shown in the above model.

Discuss this process model on camunda share if you have questions or feedback.

camunda BPM --> Apache Camel

Calling a Camel Endpoint (Service)

Use the following expression in a ServiceTask to send all the process instance variables as a map to Camel endpoint:

${camel.sendTo('<camel endpoint>')}

Alternatively you can specify which process instance variables you want to send to Camel with:

${camel.sendTo('<camel endpoint>', '<list of process variables>')}

The property CamundaBpmProcessInstanceId will be available to any downstream processesors in the Camel route.

Apache Camel --> camunda BPM

The following use cases are supported by the camunda BPM Camel component (see Camel Components).

camunda-bpm://start Start a process instance

A direct consumer to start process instances.

The following URI parameters are supported:

Parameter	Description
processDefinitionKey	the process definition key of the process to start an instance of
copyBodyAsVariable	name of the process variable to which the body of the Camel should be copied. Default is camelBody
copyHeaders	whether the Camel message headers should be copied as process variables
copyProperties	whether the Camel exchange properties should be copied as process variables

If the Camel message body is a map, then all the keys will be copied as process variables of the started instance.

If the property CamundaBpmBusinessKey is available on the incoming message then it will be associated with the started process instance and can be later followed to look it up.

The properties CamundaBpmProcessInstanceId, CamundaBpmProcessDefinitionId and CamundaBpmBusinessKey are available to the downstream processors in the Camel route as Camel exchange properties.

Example: camunda-bpm://start?processDefinitionKey=startProcessFromRoute&copyBodyAsVariable=var1

Starts a process instance of the process definition startProcessFromRoute with the body of the message as a map with process variable var1 as a key.

camunda-bpm://message Send a message to the process engine

A direct consumer to send a message to the process engine. This can either:

• trigger the start of a new process instance, see Start Message Event
• send a message to a waiting process instances. The process instance might either wait in a ReceiveTask or an Intermediate Message Event.

The following URI parameters are supported:

Paremeter	Description
activityId	the id of the ReceiveTask in the BPMN 2.0 XML (mandatory if the process instance waits in a ReceiveTask)
messageName	the name of the message in the BPMN 2.0 XML (mandatory if you do not correlate to a ReceiveTask)
copyBodyAsVariable	name of the process variable to which the body of the Camel should be copied. Default is camelBody.
processDefinitionKey	the process definition key of the process definition this operation is related to. Sometimes this can help to make correlation unique, it is always an optional parameter.

Note that either the property CamundaBpmProcessInstanceId or CamundaBpmBusinessKey need to be present in the message if it is correlated to a waiting process instance.

Examples

Check the existing integration tests for guidance on how to use the current supported features in your projects: Spring or CDI. To run the CDI integration tests do mvn -DskipITs=false.

Further there exist two example projects showing camunda-bpm-camel in Action (on JBoss AS 7 though):

• camel use cases
• Bank Account Opening Process using Camel

Using it in your project

This project is at the moment in incubation phase. This means that changes are bound to happen that will break backwards compatibility. Be warned!

Maven coordinates

Declare the camunda BPM repository in your project's pom.xml and make sure you also add the <updatePolicy> element so Maven always downloads the latest SNAPSHOT:

<repositories>
	<repository>
		<id>camunda-bpm-nexus</id>
		<name>camunda-bpm-nexus</name>
		<url>https://app.camunda.com/nexus/content/groups/public</url>
		<snapshots>
			<updatePolicy>always</updatePolicy>
		</snapshots>
	</repository>
</repositories>

Choose a dependency depending on your target environment:

Spring

<dependency>
    <groupId>org.camunda.bpm.incubation</groupId>
    <artifactId>camunda-bpm-camel-spring</artifactId>
    <version>0.1-SNAPSHOT</version>
</dependency>

In your Spring configuration you need to configure the CamelService like this:

  <bean id="camel" class="org.camunda.bpm.camel.spring.impl.CamelServiceImpl">
    <property name="processEngine" ref="processEngine"/>
    <property name="camelContext" ref="camelContext"/>
  </bean>

The Spring bean id camel will be then available to expressions used in ServiceTasks to send data to Camel.

CDI

<dependency>
    <groupId>org.camunda.bpm.incubation</groupId>
    <artifactId>camunda-bpm-camel-cdi</artifactId>
    <version>0.1-SNAPSHOT</version>
</dependency>

The CDI configuration needs a bit more work - especially for bootstrapping Camel. The easiest is to do this in a Singelton Startup EJB (see Example: CamelBootStrap.java):

@Singleton
@Startup
public class CamelBootStrap {
  
  @Inject
  private CdiCamelContext cdiCamelContext;

  @Inject
  private ProcessEngine processEngine;	

  @Inject
  private MyCamelRouteBuilder routeBuilder; // your own route declaration

  @PostConstruct
  public void init() throws Exception {
    CamundaBpmComponent component = new CamundaBpmComponent(processEngine);
    component.setCamelContext(cdiCamelContext);
    cdiCamelContext.addComponent("camunda-bpm", component);
    cdiCamelContext.addRoutes(routeBuilder);
    cdiCamelContext.start();
  }

  @PreDestroy
  public void shutDown() throws Exception {
    cdiCamelContext.stop();
  }
}

Best read Apache Camel's CDI documentation and have a look at the CDI integration tests here for guidance.

Feedback and further development

This project is part of the camunda BPM incubation space. Feedback, pull requests, ... you name it... are very welcome! Meet us on the camunda BPM dev list list.

Out landry list of development TODOs (in no special order):

• Create JBoss Distribution with Camel (including Bootstrapping) as a JBoss Module and Routes to be defined within Process Applications CIS-19
• Exception handling, i.e. Apache Camel exceptions to BPMNErrors mapping
• Implement asynchronous support
• Refactor Camel to camunda BPM signalling code to use the Activity Instance Model and not process instance IDs or execution IDs

These use cases are considered not interessting - tell us if you think different!

• Deploy process definition from Camel message

Credits

This library started as a fork of Activiti's Apache Camel module and the following people have contributed to its further develoment in the context of camunda BPM: contributors.

License

This software is licensed under the terms you find in the file named LICENSE.txt in the root directory.