CamundaCon 2023 ― The Process Orchestration Conference of the Year on Sep 27-28

Save your Seat

Fluent API for Message Correlation

  • Blog
  • >
  • Fluent API for Message Correlation
TOPICS

30 Day Free Trial

Bring together legacy systems, RPA bots, microservices and more with Camunda Platform 8

Join the Camunda Developer Newsletter

Get the latest events, release notes, and product updates straight to your mailbox.

TRENDING CONTENT
Camunda BPM 7.1.0-alpha4 features a new fluent API for message correlation.

BPMN 2.0 defines events and tasks catching messages. The following is a fragment of a process waiting for an order to be cancelled:

Intermediate Message Catch Event
Intermediate Message Catch Event

In BPMN 2.0 XML you have to provide a name for the message you want to catch:

<bpmn2:definitions ...>
  ...
  <bpmn2:message id="<b>Message_1</b>" name="<b>orderCancelled</b>"/>
  ...
  <bpmn2:process id="Process_1" isExecutable="false">
    ...
    <bpmn2:intermediateCatchEvent id="IntermediateCatchEvent_2" name="Order 
Cancelled">       
      <bpmn2:messageEventDefinition messageRef="<b>Message_1</b>"/>
    </bpmn2:intermediateCatchEvent>
    
  </bpmn2:process>

New Fluent API

Camunda Engine now features a fluent DSL for correlating this message to the process engine:

  runtimeService.createMessageCorrelation("<b>orderCancelled</b>")
      .processInstanceBusinessKey("someOrderId")
      .setVariable("CANCEL_REASON", "someReason")
      .setVariable("CANCEL_TIMESTAMP", new Date())
      .correlate();

The fluent DSL makes it easy to define a complex correlation set based on different restrictions. The above example correlates the message on the business key. On top of that, correlation based on process variables and process instance id is supported:

runtimeService.createMessageCorrelation("<b>orderCancelled</b>")
      .processInstanceVariableEquals("orderId", "someOrderId")
      .processInstanceVariableEquals("customerId", "someCustomerId")
     .correlate();


  runtimeService.createMessageCorrelation("<b>orderCancelled</b>")
      .processInstanceId("someProcessInstanceId")
      .correlate();

The API also makes it easy to provide the message payload as a single or multiple variables through setVariable(varName, value).

More Efficient than Query + Trigger

We recommend using the fluent DSL or the RuntimeService.correlateMessage(…) methods introduced in 7.0 over the Query + Trigger pattern. Using the Query + Trigger pattern you first query for an execution having a message event subscription and then trigger that execution:

Not as efficient:

  // Query
  Execution e = runtimeService.createExecutionQuery()
    .processInstanceBusinessKey("someOrderId")
    .messageEventSubscriptionName("<b>orderCancelled</b>")
    .singleResult();
  Map<String, Object> variables = new HashMap<String, Object>();
  variables.put("CANCEL_REASON", "someReason");
  variables.put("CANCEL_TIMESTAMP", new Date());


  // Trigger
  runtimeService.messageEventReceived("<b>orderCancelled"</b>, e.getId(), variables);

The Query + Trigger pattern has two disadvantages:

  1. More lines of code 🙂
  2. Two process engine commands instead of a single one. This makes it less efficient in terms of performance.

Try All Features of Camunda Platform

Related Content

Why Camunda Platform 8? Learn how real estate invester Heimstaden utilizes Camunda 8 to orchestrate their tenant support ticketing system.
We've relaunched our Professional plan as the Starter plan with an updated offering and a new monthly price to help you get started faster.
Did you know that you can keep your process instances moving with Operate? Learn how in this tutorial.