Message events are events which reference a message. They are used to wait until a proper message is received.
At the moment, messages can be published only externally by using one of the Zeebe clients.
A process can have one or more message start events (besides other types of start events). Each of the message events must have a unique message name.
When a process is deployed then it creates a message subscription for each message start event. Message subscriptions of the previous version of the process (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 process instance is created and the corresponding message start event is activated.
Messages are not correlated if they were published before the process was deployed. Or, if a new version of the process is deployed which doesn't have a proper start event.
correlationKey of a published message can be used to control the process instance creation. If an instance of this process is active (independently from its version) and it was triggered by a message with the same
correlationKey then the message is not correlated and no new instance is created. When the active process instance is ended (completed or terminated) and a message with the same
correlationKey and a matching message name is buffered (i.e. TTL > 0) then this message is correlated and a new instance of the latest version of the process is created.
correlationKey of a message is empty then it will always create a new process instance and does not check if an instance is already active.
When an intermediate message catch event is entered then a corresponding message subscription is created. The process instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event gets completed and the process instance continues.
An alternative to intermediate message catch events are receive tasks which behaves the same but can be used together with 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.
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 expression (e.g.
= orderId). If the message is only referenced by message start events then the
correlationKey is not required.
Usually, the name of the message is defined as a static value (e.g.
order canceled), but it can also be defined as expression (e.g.
= "order " + awaitingAction). If the expression belongs to a message start event of the process, then it is evaluated on deploying the process. Otherwise, it is evaluated on activating the message event. The evaluation must result in a
correlationKey is an expression that usually accesses a variable of the process instance that holds the correlation key of the message. The expression is evaluated on activating the message event and must result either in a
string or in a
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 expression. For example, if the process instance has a variable
orderId with value
"order-123" then the message must be published with the correlation key
By default, all message variables are merged into the process instance. This behavior can be customized by defining an output mapping at the message catch event.
A message start event with message definition:
An intermediate message catch event with message definition:
A boundary message event: