Message Events

Message events are events which reference a message. They are used to wait until a proper message is received.

workflow

At the moment, messages can be published only externally by using one of the Zeebe clients.

Message Start Events

A workflow can have one or more message start events. Each of the message events must have a unique message name. If the workflow has at least one message start event then it must not have a none start event. Other types of start events are allowed.

When a workflow is deployed then it creates a message subscription for each message start event. Message subscriptions of the previous version of the workflow (based on the BPMN process id) are closed.

When the message subscription is created then a message can be correlated to the start event if the message name matches. On correlating the message, a new workflow instance is created and the corresponding message start event is activated.

Messages are not correlated if they were published before the workflow was deployed. Or, if a new version of the workflow is deployed which doesn't have a proper start event.

The correlationKey of a published message has no effect on the correlation to a message start event. It only affects at which partition the workflow instance is created.

Intermediate Message Catch Events

When an intermediate message catch event is entered then a corresponding message subscription is created. The workflow instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event gets completed and the workflow instance continues.

An alternative to intermediate message catch events are receive tasks which behaves the same but can be used together with boundary events.

Message Boundary Events

An activity can have one or more message boundary events. Each of the message events must have a unique message name.

When the activity is entered then it creates a corresponding message subscription for each boundary message event. If a non-interrupting boundary event is triggered then the activity is not terminated and multiple messages can be correlated.

Messages

A message can be referenced by one or more message events. It must define the name of the message (e.g. Money collected) and the correlationKey variable (e.g. orderId), except it is only referenced by message start events.

The correlationKey variable must reference a variable of the workflow instance that holds the correlation key of the message. It is read from the workflow instance on activating the message event and must be either a string or a number.

In order to correlate a message to the message event, the message is published with the defined name (e.g. Money collected) and the value of the correlationKey variable. For example, if the workflow instance has a variable orderId with value "order-123" then the message must be published with the correlation key "order-123".

Variable Mappings

By default, all message variables are merged into the workflow instance. This behavior can be customized by defining an output mapping at the message catch event.

Additional Resources

XML representation

A message start event with message definition:

<bpmn:message id="Message_0z0aft4" name="order-placed" />

<bpmn:startEvent id="order-placed" name="Order placed">
  <bpmn:messageEventDefinition messageRef="Message_0z0aft4" />
</bpmn:startEvent>

An intermediate message catch event with message definition:

<bpmn:message id="Message_1iz5qtq" name="money-collected">
  <bpmn:extensionElements>
    <zeebe:subscription correlationKey="orderId" />
  </bpmn:extensionElements>
</bpmn:message>

<bpmn:intermediateCatchEvent id="money-collected" name="Money collected" >
  <bpmn:messageEventDefinition messageRef="Message_1iz5qtq" />
</bpmn:intermediateCatchEvent>

A boundary message event:

<bpmn:boundaryEvent id="order-canceled" name="Order Canceled" 
  attachedToRef="collect-money">
  <bpmn:messageEventDefinition messageRef="Message_1iz5qtq" />
</bpmn:boundaryEvent>

Using the BPMN modeler

Adding an intermediate message catch event:

message-event

Workflow Lifecycle

Workflow instance records of a message start event:

Intent Element Id Element Type
EVENT_OCCURRED order-placed START_EVENT
ELEMENT_ACTIVATING order-placed START_EVENT
ELEMENT_ACTIVATED order-placed START_EVENT
ELEMENT_COMPLETING order-placed START_EVENT
ELEMENT_COMPLETED order-placed START_EVENT

Workflow instance records of an intermediate message catch event:

Intent Element Id Element Type
ELEMENT_ACTIVATING order-delivered INTERMEDIATE_CATCH_EVENT
ELEMENT_ACTIVATED order-delivered INTERMEDIATE_CATCH_EVENT
... ... ...
EVENT_OCCURRED money-collected INTERMEDIATE_CATCH_EVENT
ELEMENT_COMPLETING money-collected INTERMEDIATE_CATCH_EVENT
ELEMENT_COMPLETED money-collected INTERMEDIATE_CATCH_EVENT

References: