BPMN Message Events
In short: A message event is a circle with an envelope. A white envelope waits for a message, a black one sends one. A message comes from someone outside the process: the customer has paid, the supplier has confirmed, another system reports that it is done. In Flower the process instance waits until the message of its name arrives, and a person, a Jira Automation rule, or another system sends it.
Quick start: model an intermediate message catch event, select a message named Payment received, and publish. When the process waits there, write the comment @FlowerBPM Payment received on the process instance. The process goes on.
Symbols
| Symbol | Element | Meaning |
|---|---|---|
| Message start event | The process starts when the message arrives | |
| Intermediate message event (catch) | The process waits here until the message arrives | |
| Receive task | A task that waits for a message. In Flower it works like the catch event | |
| Message boundary event, interrupting | While the activity runs, the message arrives: the activity ends and the path of the event is taken | |
| Message boundary event, non-interrupting | The activity stays open and the path of the event starts in addition. Dashed border | |
| Message event sub-process, interrupting | While the process runs, the message arrives: the process stops and the event sub-process takes over | |
| Message event sub-process, non-interrupting | The event sub-process runs beside the process. Dashed border | |
| Intermediate message event (throw) | The process sends a message and goes on | |
| Message end event | The path ends and sends a message |
A message has a sender and a receiver. That is the difference to a signal, which reaches every process instance that waits for it, and to a conditional event, which watches data.
What Waits for a Message
These elements wait for a message in Flower:
| Element | What happens when the message arrives |
|---|---|
| Receive task, intermediate message catch event | The process goes on after it |
| Message boundary event, interrupting | Flower closes the work item of the activity, see Which Status Flower Sets, and takes the path of the event |
| Message boundary event, non-interrupting | The work item stays open, the path of the event starts in addition |
| Message start event | The process instance is created and waits at the start. The first task starts when the message arrives |
| Message event sub-process, interrupting or non-interrupting | It starts, like the other event sub-processes. It needs a process whose start events have no event definition, or a single start event with one (a timer, conditional, message, or signal start event), see Event Sub-Processes in Flower |
| Message catch event behind an event-based gateway | It takes the path when its message arrives first. A timer, a conditional event, or a signal behind the same gateway can win as well; the events that do not win are discarded, see Event-Based Gateways |
Each of them waits for a message of one name: the name of the BPMN message that the element references. Select or create the message in the properties panel of the element and give it a name, for example Payment received. Upper and lower case do not matter: payment received reaches it too.
While an element waits, the process instance gets the comment Waiting for the message Payment received at …. It is a note, not a warning.
Between the pools of one model, message flows deliver messages as well: a throw or end event in one pool sends its message to the other pool, inside the engine. See Message Flows Between Pools.
Send a Message
There are three ways to send a message to a process instance. All of them need the key of the process instance or of one of its work items, and the name of the message.
| Way | Who uses it | Hosts |
|---|---|---|
A comment that starts with @FlowerBPM | A person, a Jira Automation rule that acts as a person, any system with the Jira REST API | Cloud and Data Center |
| The Jira Automation action Flower: Send message to process | A Jira Automation rule | Cloud |
POST /rest/flower/latest/service/processMessage | Another system, a Send web request of Jira Automation, a script | Data Center |
With a Comment
Write a comment on the process instance or on any of its work items. A line that starts with @FlowerBPM sends a message. The rest of that line is the name of the message:
@FlowerBPM Payment received
amount: 1200
reference: INV-4711
Paid by bank transfer.This comment sends the message Payment received with the data:
{ "amount": "1200", "reference": "INV-4711", "text": "Paid by bank transfer." }The rules:
- The line with
@FlowerBPMnames the message (text before it, such as a greeting, is fine). Upper and lower case do not matter,@Flower BPMworks too, also when the editor turns it into a mention. - The word after
@FlowerBPMis the command.messageis optional:@FlowerBPM Payment receivedand@FlowerBPM message Payment receivedsend the same message.signalsends a signal to every process instance that waits for it instead. A message whose name starts with signal or message needs the command word:@FlowerBPM message Signal received. - The lines directly after it in the form
key: valuebecome the data. - All other text of the comment (before the
@FlowerBPMline and after thekey: valuelines) becomestextin the data. - The values are text. A condition such as
> 1000still compares them as numbers. @FlowerBPMmust start a line. In the middle of a sentence it is no message.
A person writes this comment by hand. Any system writes it with the Jira REST API (POST a comment to the work item). A comment that a Jira Automation rule writes (action Add comment) counts when the rule acts as a person who can edit (its actor). On Cloud the default actor Automation for Jira is an app account, and Flower ignores comments of apps: there the rule uses the action Flower: Send message to process below, or acts as a person. This way works on Cloud and Data Center.
With Jira Automation
How rules and processes work together in both directions, on Forge and Data Center: Flower BPM and Jira Automation.
On Cloud, Flower adds the action Flower: Send message to process to Jira Automation. Its inputs:
| Input | Value |
|---|---|
| Work item | The process instance or one of its work items, for example {{issue.key}} |
| Name of the message | The name of the message, for example Payment received |
| Data | Optional: the data of the message |
The first time someone adds an action of Flower to a rule, the rule author connects the app once for the site. The action Flower: Complete automated task of automated tasks works the same way.
With the REST API (Data Center)
On Data Center, another system sends a message with a POST request:
POST /rest/flower/latest/service/processMessage
Content-Type: application/json
{
"issueKey": "FLOW-12",
"name": "Payment received",
"data": { "amount": 1200, "reference": "INV-4711" }
}issueKeyis the process instance or one of its work items.nameis the name of the message.datais optional and can be any JSON.
The answers:
| Status | Meaning |
|---|---|
202 {"queued": true} | The message is accepted and will be delivered |
400 | name or issueKey is missing |
403 | The caller is not logged in, or cannot edit the work item or its process instance |
A comment with @FlowerBPM works on Data Center too.
One Inbox for Messages and Signals
Every way in, the comment, the Jira Automation action, and the REST API, ends in the same entry point of Flower, which hands the message to its process instance: one delivery per process instance, one after the other. Each way checks first that the sender may edit the work item and its process instance; a comment is handled once, also when it is edited later. Signals take the same way.
Use the Data in Conditions
Flower keeps the data of the last delivered message of each name at the process instance, in flower.messageData, up to 2000 characters (longer data is cut, with a warning comment). JSON text from the Jira Automation action becomes an object. A gateway after the catch event decides with it:
| Gateway flow | Condition |
|---|---|
| Large payment | ${pi.properties.flower.messageData['Payment received'].amount > 1000} |
| Known invoice | ${pi.properties.flower.messageData['Payment received'].reference == 'INV-4711'} |
The data is there already in the run that delivers the message, so a gateway directly after the catch event sees it. See Expressions.
What Flower Writes
| When | Comment on the process instance |
|---|---|
| An element starts to wait | Waiting for the message … at … (a note) |
| The message is delivered | Message … received, with the elements that got it |
| Nothing of the process waits for the message | The message … arrived, but nothing of the process waits for it: it is dropped. (a warning) |
| The writer of the comment cannot edit the work item | A warning comment: only a person who can edit the work item sends messages |
Every handled message is kept in the property flower of the process instance, delivered or not:
| Property | Contains |
|---|---|
flower.messages | The handled messages in the order they arrived (the last 50), together with the delivered signals (kind: 'signal'). Each one has name, withData (true when data came; the data itself is in flower.messageData), at, by, via (comment, automation or rest), comment (the id of the comment), delivered (true or false), and nodes (the elements that got it) |
flower.messageData['<name>'] | The data of the last delivered message of that name |
Read it with the Jira REST API, GET /rest/api/3/issue/{key}/properties/flower, or in expressions as pi.properties.flower.
Permissions and Edge Cases
- Only a person who can edit the work item sends messages. A Jira Service Management customer who can only comment cannot. Flower then writes a warning comment and does not deliver the message.
- Comments of the app itself are ignored.
- A comment is handled once. Changing it later does not send the message again. Write a new comment instead.
- Restricted comments (Cloud): a comment that is visible only to a group or a role is not seen by the app.
- Nothing waits for the message: it is dropped, with a warning comment, and listed in
flower.messageswithdelivered: false. A message does not wait for an element that the process reaches later. - A message without a name: the validator warns about a receive task or message event whose message has no name. The name is what a comment or Jira Automation sends.
Send a Message from the Process
The intermediate message throw event and the message end event send. Without a message flow, the throw event triggers a Jira Automation rule, or calls its webhook URL (Connect, Data Center); the end event does that only when it has a webhook URL or the request type Jira Automation, otherwise it just ends its flow. See Trigger Jira Automation. With a message flow to another pool of the same model, the message goes to that pool instead, see Message Flows Between Pools.
A rule that a throw event triggers can send a message back to a waiting process with one of the ways above. This is how a process asks another system and waits for its answer.
Common Mistakes
- A message without a name. Nothing can reach the element. The validator warns.
@FlowerBPMin the middle of a sentence. It must start a line.- The message is sent before the process waits. It is dropped. Let the process wait first, or use a conditional event on a field that stays set.
- A message where a signal is meant. A message goes to one process instance. To reach every process instance that waits, send a signal.
Read More
- BPMN Events: all event types and positions
- BPMN Signal Events: one signal for every waiting process instance
- Message Flows Between Pools: messages between the pools of one model
- Trigger Jira Automation: send from the process
- BPMN Conditional Events: wait for data instead of a message
Frequently Asked Questions
What is a message event in BPMN?
An event that sends or receives a message between two participants. It is drawn as a circle with an envelope: white when it waits, black when it sends.
What is the difference between a receive task and a message catch event?
In BPMN, a receive task is a task and can have boundary events, a catch event is only a point in the flow. In Flower both wait for the message of their name in the same way.
How do I let a Jira process wait for an answer from another system?
Model an intermediate message catch event with a named message. The other system writes a comment @FlowerBPM <name> on the process instance with the Jira REST API, or calls Jira Automation, which sends the message with Add comment or the action Flower: Send message to process.
Can I pass data with the message?
Yes. In a comment, the lines key: value after the first line become the data. A gateway reads it as pi.properties.flower.messageData['<name>'].