Camunda Camel

This community extension focuses on bringing two great Open Source frameworks closer together, the Camunda Platform and Apache Camel. Note, that a community extension is not part of the supported product of Camunda.

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

Table of Contents

• How-to use
• Use Cases
  • camunda Platform --> Apache Camel
    • Calling a Camel Endpoint (Service)
  • Apache Camel --> Camunda Platform
    • camunda-bpm://start Start a process instance
    • camunda-bpm://message Send a message to the process engine
    • camunda-bpm://poll-externalTasks Consuming external tasks
    • camunda-bpm://async-externalTask Processing outstanding external tasks
• Examples
• Target environments
  • Spring
  • CDI
  • Blueprint
• Credits
• License

How-to use

Environment requirements:

Please also check Camel requirements: http://camel.apache.org/what-are-the-dependencies.html (e.g. Camel 2.14 onwards requires JDK 1.7 or better).

Now follow the docs on the environment you want to run in. In Spring it will look like:

<dependency>
    <groupId>org.camunda.bpm.extension.camel</groupId>
    <artifactId>camunda-bpm-camel-spring</artifactId>
    <version>0.8.0</version>
</dependency>

The Spring bean id camel can be made available easily then:

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

Use Cases

camunda Platform --> 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>')}

Hint: You will also get variables which were set but contain a null value.

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

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

Hint: missing or null value variables will cause to throw an IllegalArgumentException. You can append a question mark to each name of a variable which is allowed to be missing or null (e.g. 'mayBeNullVar?,mustNotBeNullVar').

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>', '<comma-separated list of process variables>', 'correlationKey')}

The properties CamundaBpmProcessInstanceId, CamundaBpmBusinessKey (if available) and CamundaBpmCorrelationKey (if set) will be available to any downstream processors in the Camel route.

Error Handling:

• Throwing a org.camunda.bpm.engine.delegate.BpmnError will lead to an error being propagated to Camunda (starting from version >= 0.8.1). Note that this can terminate a process instance if not handled, see https://docs.camunda.org/manual/latest/user-guide/process-engine/delegation-code/#throw-bpmn-errors-from-listeners)
• Throwing any other exception will lead to a retry/incident created in Camunda

Apache Camel --> Camunda Platform

The following use cases are supported by the Camunda Platform 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:

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:

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.

camunda-bpm://poll-externalTasks Consuming external tasks

With version 7.4.0 Camunda introduced external tasks. With version 7.5.0 further improvements were added.

Since version 0.5 of camunda-bpm-camel it is possible to consume external tasks by Camel endpoints. There are advantages by doing so:

• You don't have to place Camel instructions into your BPMN which is another level of technical decoupling.
• External tasks are not processed by the thread processing the workflow and therefore they do not block the origin thread which may be part of Camunda's worker thread-pool.
• If you have asynchronous communication external tasks in combination with Camel are a great deal to split the service task into three transactions: The first is about the workflow currently processing (context: Camunda); the second is for sending the request (context: Camel) and the third for processing the response (context: Camel).
• External tasks may be used as some sort of queue - especially if the service does some outbound network communication. In some installations it might be sufficient to use this aspect instead of using an ESB.

Example: camunda-bpm:poll-externalTasks?topic=topic1

The following URI parameters are supported:

*) The endpoint URI is not the URI remarked in your configuration file. It is a URI generated by Camel but it is very similar to your URI. An example: camunda-bpm:poll-externalTasks?topic=topic1&maxTasksPerPoll=5 -> camunda-bpm://poll-externalTasks?maxTasksPerPoll=5&topic=topic1 (parameters are sorted).

The exchange produced by the endpoint got several properties:

• CamundaBpmProcessInstanceId
• CamundaBpmProcessDefinitionId
• CamundaBpmProcessDefinitionKey
• CamundaBpmProcessInstancePrio

Additionally these in-headers are set:

• CamundaBpmExternalTask contains the entire LockedExternalTask object
• CamundaBpmExternalAttemptsStarted contains how many times the task was processed but failed
• CamundaBpmExternalRetriesLeft contains how many times the task will be processed any more if this execution fails
• the in-body is a map containing the process instance variables requested (Map< String, Object >)

If the reply-body contains a map (Map< String, Object >) this map is treated as a list of process instance variables and therefore used to update the process. If the reply-body is a string it is used as a BPMN error code to signal an error to the process. If processing the exchange fails (e.g. an exception is caught) then the exception's message is used to mark the task as failed (which might cause further retries or an incident if the number of retries elapsed). Additionally exceptions can be annotated by @org.camunda.bpm.camel.component.externaltasks.SetExternalTaskRetries to control how the current exception effects the retry counter.

Hint: Processing of the route is not done in parallel even if the route uses a AsyncProcessor. This is Camel's default behavior of a polling Consumer! If you want to process the external tasks in parallel you have to define your own scheduler:

Example: camunda-bpm:poll-externalTasks?topic=topic1&scheduler=#topic1Scheduler

A scheduler is found by lookup in Camel's registry (what kind of registry is used depends on your environment, typical registries are CDI BeanManager and JNDI). This is an example of CDI producer building a scheduler which processes two external tasks in parallel:

@Named("topic1Scheduler")
public ScheduledPollConsumerScheduler produceTopic1Scheduler() {
    final DefaultScheduledPollConsumerScheduler scheduledPollConsumerScheduler = new DefaultScheduledPollConsumerScheduler();
    scheduledPollConsumerScheduler.setConcurrentTasks(2);
    return scheduledPollConsumerScheduler;
}

camunda-bpm://async-externalTask Processing outstanding external tasks

By using camunda-bpm://poll-externalTasks' parameter async at value true it is up to your responsibility to complete the task once your processing is done. A typical situation is when you want to process the response of asynchronous communication. In this situation you may use this processor endpoint (see Camel docs) to complete the external task. The endpoint also supports throwing an incident or raising an BPM error as described for camunda-bpm://poll-externalTasks.

For using it the incoming message of the Camel route must include a parameter CamundaBpmExternalTaskId which contains the id of the external task.

Example: camunda-bpm:async-externalTask?topic=topic1

Typical usage:

• <from uri="direct:bar" /><to uri="camunda-bpm:async-externalTask" />
• <from uri="direct:bar" /><to uri="camunda-bpm:async-externalTask?onCompletion=true" /><to uri="some-other-endpoint" />

These in-headers are set to be used subsequent endpoints:

• CamundaBpmExternalAttemptsStarted contains how many times the task was processed but failed
• CamundaBpmExternalRetriesLeft contains how many times the task will be processed any more if this execution fails

The Exception org.camunda.bpm.camel.component.externaltasks.NoSuchExternalTaskException (derived from RuntimeCamelException) might be thrown on processing an external task. The reason for this circumstance might be a situation in a BPM process in which the task implemented by the external task (e.g. ServiceTask) was cancelled. Tasks are cancelled due to interrupting events (e.g. timer event).

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 exists the example project 'camel use cases'

Target environments

Spring

<dependency>
    <groupId>org.camunda.bpm.extension.camel</groupId>
    <artifactId>camunda-bpm-camel-spring</artifactId>
    <version>0.8</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.extension.camel</groupId>
    <artifactId>camunda-bpm-camel-cdi</artifactId>
    <version>0.8</version>
</dependency>

The CDI configuration needs a bit more work - especially for bootstrapping Camel. The easiest is to do this in a Singleton 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.

Blueprint

<dependency>
    <groupId>org.camunda.bpm.extension.camel</groupId>
    <artifactId>camunda-bpm-camel-blueprint</artifactId>
    <version>0.8</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" />
...

Credits

This library started as a fork of Activiti's Apache Camel module and the following people have contributed to its further development 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.