Understanding Message Flow

BPMN MessageFlow

Introduction

While most of our process diagrams define how one task follows another inside a single process instance, message flow allows one instance to send, receive, or wait for a message from another process instance. In BPMN, this is called MessageFlow.

BPMN process diagrams use BPMN SequenceFlow, drawn with solid lines, to define flow between tasks, events, and gateways within a process instance. If a BPMN participation is used (a set of lanes), flow within the participation (lane set) must use only sequenceFlow. Communication between different lanesets or different process instances must use MessageFlow, drawn with dashed lines, instead..

.

Within a Participation (a laneset), all communication must use Sequence Flow. Between Participations (lanesets), all communication must use Message Flow.

Simple Message Protocol

Flows for APEX introduces a formatted message protocol that can be used to define these message flows. We call this protocol simple message protocol. The simple message protocol specifies the message header, used to identify the message. This contains three components, which must be known by both the sender and the receiver prior to the message being sent.

1. message name / type,
2. message key,
3. key value.

In addition, the message can optionally contain a payload, or message body, which can send information that is currently unknown to the receiver. The payload could be a text value, or a JSON object containing several values.

BPMN uses this subscription concept so that messages can be identified by their message type and a key/value pair - rather than having to use synthetic identifiers like process id or task guid. The subscription allows Flows for APEX to receive a message with a message name and key/value pair – and then know which step in which process instance it should forward that message onto.

At any time, on a system-wide basis, the message name and key-value pair in the subscription table must be unique.

Choosing your message names and key/value pairs therefore requires some design effort.

Messaging - BPMN Objects

BPMN, and Flows for APEX, allows you to define messaging using

• Tasks : sendTask and receiveTask
• Events : message throwEvent and message catchEvent

.

You can choose to use tasks or events, and individual analysts or companies will often have their own style guides. Both are supported and provide equivalent functionality in Flows for APEX. We tend to favour the use of event syntax as a more modern style.

Supported Objects in Flows for APEX v 23.1

The initial release of message flow supports:

• Send Task
• Receive Task
• Intermediate Message Throw Event
• Intermediate Message Catch Event

The following events are not yet supported in this release:

• Message Start Event
• Boundary Event Message Catch Event
• Message Throw End Event

Subscriptions

When a message receiveTask or a message catch event become the current object in a process instance, they create a message subscription which defines the message that they are waiting for.

The message subscription defines

• the simple message protocol headers required to identify an incoming message, which are:
  • the message name
  • a key name
  • a key value
• information to identify the subscribing receiveTask / messageCatchEvent
  • the process id of the waiting process
  • the subflow id of the waiting object
  • the step key for that object
  • the handler to use for the waiting step type
• information on what to do with any received payload
  • which process variable to store any payload into

These are stored in the Flows for APEX table flow_subscriptions.

.

MessageFlow Operation

Serial	Current Process (Receiver)	Message Subscription	Remote Process (Sender)
1	ReceiveTask or Message Catch Event becomes current step	Creates a Message Subscription for the Message	-
2	Step waits to receive incoming messsage	-	-
3	-	-	Remote Process prepares and sends a message containing the required Message Name, Key Name, and Key Value, along with any payload
4	-	Engine looks for 100% match between received message (message name, key name, key value) and its Message Subscriptions.	-
5a	-	no matching subscription found - returns error to Sender	Sender handles. Failed message logged.
or 5b	-	100% match found - looks up call back information (process id, subflow id, step key, handler) and uses this to store payload into process variable and then call the subscribing step. Logs succesful message.	-
6	Calling Step issues a complete_step and steps forward	Message Subscription is deleted now it has been consumed	Sender carrys on…

Note:

• Messages are formatted
• The Receiver has to create a Subscription for the message before it is sent.
• With good design, the message names, key names and key values should all be real-world business objects (like order no, Customer ID), rather than synthetic process identifiers (like process ID, subflow ID, etc.). Contents that the other party doesn’t know are information that should be passed in the payload.
• A subscription is created for one message, and used / deleted when a matching message arrives.

How do I use MessageFlow in 23.1?

There are 3 main use cases for MessageFlow in v23.1. Further releases will make this much more powerful, but we believe the functionality in this release has several uses.

1. Flows for APEX Process needs to wait for, and receive information from a Non-Flows for APEX program.

Scenario: Your business process needs to wait until something happens outside the control of APEX and Flows for APEX. Asynchronously, when the external process is ready, it sends a message - optionally with a payload - to the process, causing the process to continue.

.

• The external local process could be called using Send Task with a sub-type of PL/SQL Call. This would just call the local task using PL/SQL, rather than sending it a formatted message.
• The process then starts a Message Catch Event and a Timer Catch Event - and waits.
• If the Timer fires first, because no payment was received within the 14 day timer period, the order gets cancelled and the process ends.
• When the payment is ready, the local process uses the Flows for APEX API to call flow_api_pkg.receive_message, passing in the message name, key name, key value, and a payload JSON snippet ccontaining the bank reference number and amount paid.
• The incoming message is caught by the Message Catch Event. This causes the Event Based Gateway to terminate the Time-out Timer. The message payload is inserted into a process variable, and the subscription then cancelled (used).
• The process steps forward.

2. Flows for APEX Process waits for remote message via REST

A remote process could use the REST endpoint to send a message into the local Flows for APEX process instance.

3. Inter-process communication between two processes running in the same Flows for APEX Workspace.

As a beta / lab feature, it is possible for two process instances in the same Flows for APEX System and running inside the same APEX Workspace to send and receive messages to each other. However, in v23.1, you need to design and test this carefully.

.

• The two processes currently need to be in two different diagrams, Each diagram should reference the other diagram as a dark pool / black box. Do not define both processes as part of a single Collaboration on a single BPMN diagram.
• The current architecture has the two instances tightly coupled. A message send task from one process calls the message receive task in the other process – and these process steps in the called process will be executed by the user sending the message.
• If you do have Process A Sending a Message to Process B, the Receive Task in Process B must do something in a non-synchronous process step before it then sends a reply message for process A to catch – otherwise the sending task in process A is still current, and process A is not yet waiting to receive a message from Process B. Add a short timer between Process B’s receive task and its replying send task.
• Consult the Flows for APEX Team if you really want to do this!
• We expect to remove these restrictions in a future release - hopefully, the next release!