Messages have a name and contain a payload. They are sent by message throwing events and received by message catching events in a 1:1 relationship between throw events and catch events. Messages contain a payload known as a message payload and can be passed between scopes, for example between two different process definitions within the same diagram that are separated by different pools.
The message id property of a message is matched against the messageRef property in the corresponding throw and catch message elements when viewing the XML Editor.
To create a new message use the + symbol against a message event such as a message boundary event, or make sure no BPMN element is selected by clicking on a blank section of the process canvas and the Edit Messages button will be visible in the right-hand properties panel.
Message events are displayed as an envelope icon inside different shapes that differentiate between the event types. A solid envelope represents a throwing event, and a hollow envelope represents a catching event.
Message payloads
Message payloads contain a set of values that are sent from a throwing event and received by a catching event.
Message payloads can only be created on a message throw event and contain one or more properties that have a name, type and value. The property types for payloads are:
| Type | Description |
|---|---|
| String | A sequence of characters, for example: #Mint-Ice-Cream-4! |
| Integer | A positive whole number, for example: 642 |
| Boolean | A value of either true or false |
| Date | A specific date in the format YYYY-MM-DD, for example: 2020-04-22 |
| Variable | A value passed from a process variable. |
The receiving message catch event is then used to map the received values in the payload to process variables in its own scope.
Message payload mappings can be viewed in the Extensions Editor of a process diagram. Throwing events are mapped as inputs and catching events are mapped as outputs from an event.
Correlation keys
Message events can optionally contain a correlation key. If a correlation key is present then when a message is thrown it uses the activiti:correlationKey value and the messageRef of the throwing event to match against the same two properties in a catching event. If only one property is matched then the message will not be caught.
Using a process variable for the correlation key in a throwing event and a static value for its corresponding catching event allows for the message to only be caught in specific circumstances.
Message start events cannot contain a correlation key unless they are used in a sub process.
Message flows
When messages are used between two different pools the sequence flow that connects them is a dotted line called a message flow. The message flow is part of the collaboration element in the XML created by introducing a pool. Message flows reference the throwing message event as the sourceRef and the catching message event as the targetRef.