Understanding Message Flow in Flows for APEX

Understanding MessageFlow in Flows for APEX

Introduction

BPMN Message Flow allows process instances to send, receive, and wait for formatted messages from other process instances and external sources.

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

For start events only, the message key and key value are not required (and shouldn’t be used) as the process instance to be started will not yet know enough about the process to be expecting a specific message key and value. This is explained later below.

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. Tutorial 7b shows the example of a Customer ordering products from a Supplier, which are then shipped by a Shipper. Here we have 3 different organizations that collaborate to complete a business process. In the tutorial, all of the message flows have been shown in the model using static definitions so that you can see what these messages could look like. Obviously a real process would generate much of the content from the ordering, sales, and supply chain applications used by the three example companies. But the messages are a simplified example of how this could work. If you have the Flows for APEX Enterprise Edition, this tutorial can be executed; if not, you can study the model to see how it works.

Tasks or Event Syntax - It’s Up to You

BPMN allows you to define simple messaging using tasks or events:

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

Flows for APEX supports both messaging tasks and messaging events.

.

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 favor the use of event syntax as a more modern style.

In this documentation, unless there are differences between the task-based object and the event-based behavior, we will refer to both ReceiveTask and Message Catch as message catching, and Send Tasks and Message Throw Events as message throwing.

Supported Objects in Flows for APEX Editions

Flows for APEX Community Edition only supports the basic message flow objects (introduced in Flows for APEX v23.1):

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

Flows for APEX Enterprise Edition, supports a complete set of BPMN Message Flow objects:

• Message Start Event 🆕
• Interrupting Boundary Message Catch Event (on tasks, sub-processes, and call activities) 🆕
• Non-Interrupting Boundary Message Catch Event (on tasks, sub-processes, and call activities) 🆕
• Message Throw End Event (on process end events and subProcess end events) 🆕

Flows for APEX Enterprise Edition v25.1 further develops the underlying architecture of Message Flow by providing an incoming message queue. Processing of incoming messages by the receiving instance uses Oracle Advanced Queuing in the underlying database. This isolates the sending and receiving process instances.

Message Subscriptions

When a message catching event become the current object during process execution, it creates a message subscription. This tells the message listener that the process instance is waiting for a specific message with specific header values, and that it should process the specific message when it is received by calling the instance call back when the message is received.

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 catch event:
  • 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
  • the process variable to store any payload into

These are stored in the Flows for APEX internal table flow_subscriptions.

.

Message Start Events are slightly different as there is not an existing process waiting for a call back when the start message arrives. In this case, there is a message subscription created for a diagram that just requires the message name. A Message Start message would usually also contain a payload, containing all of the information required to set up the process from the start message.

The message start subscription is created when a diagram is promoted to released status, and is reused for each new message start event until the process diagram is moved to deprecated status, when the subscription is cancelled. The calling process would usually use the message Payload to give the called process enough context information about the process to be started that subsequent message flow uses the full protocol.

MessageFlow Operation - “normal” message throw and catch (not Start Events)

Serial	Current Process (Receiver)	Message Subscription	Remote Process (Sender)
1	Catch Event becomes current step	Creates a Message Subscription for the Message	-
2	Step waits to receive incoming message	-	-
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 successful message.	-
6	Calling Step issues acomplete_step and steps forward	Message Subscription is deleted now it has been consumed	Sender carries on…

Note:

• Messages are formatted
• The receiving process must create a Subscription for the message before it is sent by the sender.
• 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