Message events

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.

To create a new message in the Modeling Application, use the + symbol against a message event. A name can be defined and an auto-generated id is created. The message id is matched against the messageRef property in the corresponding throw and catch message elements.

Messages contain a payload known as a message payload.

Message events are graphically represented by an envelope icon inside different shapes that differentiate between the event types. A solid envelope represents a throwing event, whilst a hollow envelope represents a catching event.

The XML representation of a message is the following:

<bpmn2:message id="Message_0k9hibo" name="payment-message" />

The following are message events:

Message payloads

Message payloads contain a set of values that are sent from a throwing event and received by a catching event.

Message payloads are created with message throw events and contain one or more properties that have a name, type and value. The following are the property types available to use in the payload:

The receiving message catch event is then used to map the received values in the payload to process variables in its own scope.

The message payload mappings are stored in the <process-name>-extensions.json file in a process. Throwing events are mapped as inputs and catching events are mapped as outputs.

The following is an example of a message payload for a message end event with the payload containing the process variable username and an integer of order-number:

    "mappings": {
        "EndEvent_0ss2fp3": {
            "inputs": {
                "name": {
                    "type": "variable",
                    "value": "username"
                },
                "order-number": {
                    "type": "value",
                    "value": 1459283
                }
            }
        }
    },
    "properties": {
        "426ea9f7-7049-4a4c-b235-960144b483de": {
            "id": "426ea9f7-7049-4a4c-b235-960144b483de",
            "name": "username",
            "type": "string",
            "value": "",
            "required": false
        }
    }

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 for 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.

In the following example, the message will only be caught if a catching event has a messageRef of Message_1hxecs2 and an activiti:correlationKey that matches the value of userId:

<bpmn2:endEvent id="EndEvent_1">
    <bpmn2:incoming>SequenceFlow_8</bpmn2:incoming>
    <bpmn2:messageEventDefinition messageRef="Message_1hxecs2" activiti:correlationKey="${userId}" />

Note: 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 and is called a messageFlow. The message flow is part of the collaboration element created by introducing a pool. Message flows reference the throwing message event as the sourceRef and the catching message event as the targetRef.

The following is an example of a message flow:

<bpmn2:collaboration id="Collaboration_0kgbwi1">
    <bpmn2:participant id="Participant_1i6u1my" processRef="Process_1d9yxsm" />
    <bpmn2:participant id="Participant_10umhbc" processRef="Process_1piiyp4" />
    <bpmn2:messageFlow id="MessageFlow_0vh4zdb" sourceRef="Event_00acemq" targetRef="Event_13u5jtf" />
</bpmn2:collaboration>

Message intermediate catch events

Message intermediate catching events cause the process flow to wait until the message named in the messageRef property is received before it proceeds.

When used in the Modeling Application, a previously created Message can be selected from the dropdown in its properties, or a new one created using the + symbol.

Message intermediate catching events are graphically represented by two thin concentric circles with a hollow envelope icon inside.

The XML representation of message intermediate catching events is:

<bpmn2:intermediateCatchEvent id="IntermediateCatchEvent2">
    <bpmn2:incoming>SequenceFlow_5</bpmn2:incoming>
    <bpmn2:outgoing>SequenceFlow_6</bpmn2:outgoing>
    <bpmn2:messageEventDefinition messageRef="Message_6" />
</bpmn2:intermediateCatchEvent>

Message intermediate throw events

Message intermediate throw events send the message event named in the messageRef property when the process flow reaches them.

When used in the Modeling Application, a previously created Message can be selected from the dropdown in its properties, or a new one created using the + symbol

Message intermediate throwing events are graphically represented by two thin concentric circles with a solid envelope icon inside.

The XML representation of message intermediate throwing events is:

<bpmn2:intermediateThrowEvent id="IntermediateThrowEvent1">
    <bpmn2:incoming>SequenceFlow_5</bpmn2:incoming>
    <bpmn2:outgoing>SequenceFlow_6</bpmn2:outgoing>
    <bpmn2:messageEventDefinition messageRef="Message_6" />
</bpmn2:intermediateThrowEvent>

© 2023 Alfresco Software, Inc. All Rights Reserved.