Understanding MessageFlow in Flows for APEX

Introduction

The Flows for APEX Enterprise Edition v24.1 supports a full set of BPMN message flow objects, allowing messages to start another process, simple message send and receive capabilities, message boundary events, and message throw end events. A limited set of these is includd in. the Community Edition, introduced in v23.1.

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 organisations 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 Events - It’s Up to You

BPMN, and Flows for APEX, allows you to define simple messaging using tasks or events:

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

MessageFlow Objects.

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.

For simplicity, in this documentation, unless there are differences between the task-based object and the event-based behaviour, 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

MessageFlow CE Objects

Flows for APEX Community Edition just supports the basic message flow objects that were introduced in Flows for APEX v23.1:

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

MessageFlow EE Objects

Meanwhile, the Enterprise Edition, starting in v24.1, adds the following objects, which create a complete set of BPMN Message Flow objects:

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

Message Subscriptions

When a message catching event become the current object in a process instance, it creates a message subscription, telling the message listener that it is waiting for a message with specific header values, and which process step to call back (and how) 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
    • which process variable to store any payload into

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

Message Subscription Table schematic.

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 messageflow 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 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 acomplete_step and steps forward Message Subscription is deleted now it has been consumed Sender carrys 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.

How do I use the limited MessageFlow in Community Edition?

There are 3 main use cases for the limited capabilities of MessageFlow in Flows for APEX Community Edition. The functionality in Flows for APEX Enterprise Edition makes messageFlow much more powerful, but we believe the functionality in the Community Edition 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.

Example Sales Order Process.

  • 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 - but the Enterprise Edition functionality is highy recommended.

Tightly Coupled Processes.

  • With Community Edition, the two processes 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 without Enterprise Edition
  • 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 catch event 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 to create a delay between Process B’s receive task and its replying send task.
  • Consult the Flows for APEX Team if you really want to do this!
  • Consider upgrading to the Enterprise Edition if you want to make full use of process collaboration. Having Message Start Events, Message Boundary Events, and Message End Events make process collaboration straightforward.