This project focuses on bringing two great Open Source frameworks closer together, the camunda BPM platform and Apache Camel.
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.
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>')}
Additionally you can specify a correlationKey to send to Camel. It can be used to correlate a response message. The route for the response must contain a parameter correlationKeyName with the name of the process variable which is used for correlation:
${camel.sendTo('<camel endpoint>', '<list of process variables>', 'correlationKey')}
The properties CamundaBpmProcessInstanceId, CamundaBpmBusinessKey (if available) and CamundaBpmCorrelationKey (if set) will be available to any downstream processesors in the Camel route.
The following use cases are supported by the camunda BPM Camel component (see Camel Components).
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©BodyAsVariable=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.
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:
| Parameter | Description |
|---|---|
messageName |
the name of the message in the BPMN 2.0 XML (mandatory if you correlate to a Intermediate Message Event or a ReceiveTask with a message reference) |
activityId |
the id of the ReceiveTask in the BPMN 2.0 XML (mandatory if the process instance waits in a ReceiveTask without a message reference - considered as deprecated) |
correlationKeyName |
the name of a process variable to which the property CamundaBpmCorrelationKey will be correlated |
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. In case of working without a message this can help to make correlation unique, it is always an optional parameter. |
Note that either one of the properties CamundaBpmProcessInstanceId, CamundaBpmBusinessKey or CamundaBpmCorrelationKey need to be present in the message if it is correlated to a waiting process instance. Usage of CamundaBpmCorrelationKey and / or CamundaBpmBusinessKey is preferred.
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):
This project is at the moment in incubation phase. This means that changes are bound to happen that will break backwards compatibility. Be warned!
From version 0.3 on JDK 1.7 or better is required (by Camel, see http://camel.apache.org/what-are-the-dependencies.html - Camel 2.14 onwards requires JDK 1.7 or better).
You might have to add v the camunda BPM repository in your project's pom.xml:
<repositories>
<repository>
<id>camunda-bpm-nexus</id>
<name>camunda-bpm-nexus</name>
<url>https://app.camunda.com/nexus/content/groups/public</url>
</repository>
</repositories>
Choose a dependency depending on your target environment:
<dependency>
<groupId>org.camunda.bpm.extension.camel</groupId>
<artifactId>camunda-bpm-camel-spring</artifactId>
<version>0.4</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.
<dependency>
<groupId>org.camunda.bpm.extension.camel</groupId>
<artifactId>camunda-bpm-camel-cdi</artifactId>
<version>0.4</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.
<dependency>
<groupId>org.camunda.bpm.extension.camel</groupId>
<artifactId>camunda-bpm-camel-blueprint</artifactId>
<version>0.4</version>
</dependency>
The OSGi Framework is used to retrieve the ProcessEngine and a DefaultCamelContext therefore the bean definition of the CamelServiceImpl is obsolete.
The camunda-bpm-osgi project is used with the blueprint-wrapper context.xml. The BlueprintELResolver was extended by the CamelBlueprintELResolver. You need to replace the class of the ‘blueprintELResolver’ bean in the context.xml:
...
<bean id="blueprintELResolver" class=" org.camunda.bpm.camel.blueprint.CamelBlueprintELResolver" />
...
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
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.
This software is licensed under the terms you find in the file named LICENSE.txt in the root directory.