Message Events
BPMN Message Events
This section introduces BPM Message Events and describes how to configure them.
Message Catch Start Event ( )
A message catch start event starts a new process instance when a message is received.
Message Name: The message name for a message start event must be unique across a Flows for APEX instance.
Subscription: The process diagram must be in released status for a message start event to be successful. Promoting a model to released state creates a message subscription for the start event.
A start event can be in its own diagram, or can be in an additional BPMN Pool to a diagram containing a normal start event.
To configure:
Event Type: Select Simple Message for the Flows for APEX Message Flow protocol.
Simple Message: Set the Message Name for the name of the incoming message that the listener should wait for. This can be set as a static definition, inside a process variable, returned by a SQL query, or returned by a PL/SQL expression or function body.
Return Payload Into: Specify the name of the proces variable that the message payload will be returned into. The payload variable is of type CLOB, so could contain text or a JSON document. If the payload is a JSON document, you could use the on event variable expression to extract components from the JSON into scalar process variables.
Edition: Message Start Event is only available with the Flows for APEX Enterprise Edition.
Message Intermediate Events
Message Intermediate Throw Event ( )
Behaviour: An intermediate message throw event throws a message when it becomes the current object during process execution. If the receiving end point is not expecting the message, i.e., there is no existing message subscription for the incoming message, it will return an error.
Event Type: Select Simple Message for the Flows for APEX Message Flow protocol.
Simple Message: ** Set the **Message Name for the name of the outgoing message that the remote endpoint is waiting for. This can be set as a static definition, inside a process variable, returned by a SQL query, or returned by a PL/SQL expression or function body.
Correlation Key and Value: Set the correlation key and its value for the return message. This should be a pre-arranged format, and the value should be something that the receiver already knows. So, in this case the customer had sent a PO message earlier that would have contained the customer PO number. Now both parties know the Customer PO - and so this could be used as the return message key. This can be set as a static definition, inside a process variable, returned by a SQL query, or returned by a PL/SQL expression or function body.
Payload: Specify the message payload to be sent with the message (optional). The payload variable is of type CLOB, so could contain text or a JSON document. In this situation, the payload would likely contain the supplier’s Sales Order number (not yet known by the customer), item availability and pricing, and any other information. The return payload is a CLOB.
Send Task. A BPMN send task can also be used to perform the same function as a message intermedate throw event.
Message Intermediate Catch Event ( )
Behaviour: When a standalone Message Intermediate Catch Event becomes the current object on proess instance execution, the event creates a message subscription for the specific message name, key name and key value that it is expecting. Process execution then waits for the message flow listener to receive an incoming matching (correlated) message. When a message is received and correlated, any attached message payload is stored into a process variable, and the process instance moves forward.
Variable Expressions: A message catch event can contain an on-event variable expression, which fires after the incoming message has been correlated.
Event Type: Select Simple Message for the Flows for APEX Message Flow protocol.
Simple Message: ** Set the **Message Name for the name of the incoming message that we are expecting. This can be set as a static definition, inside a process variable, returned by a SQL query, or returned by a PL/SQL expression or function body.
Correlation Key and Value: Set the correlation key and its value for the incoming message. This should be a pre-arranged format, and the value should be something that the receiver and sender already know. So, in this case the customer had sent a PO message earlier that would have contained the customer PO number. Now both parties know the Customer PO - and so this could be used as the return message key. This can be set as a static definition, inside a process variable, returned by a SQL query, or returned by a PL/SQL expression or function body.
Return Payload Into: Specify the process variable to return the message payload into (optional). The payload variable is of type CLOB, so could contain text or a JSON document. In this situation, the payload would likely contain the supplier’s Sales Order number (not yet known by the customer), item availability and pricing, and any other information. The return payload is a CLOB.
Receive Task. A BPMN receive task can also be used to perform the same function as a standalone message intermedate catch event.
Message Intermediate Boundary Catch Events ( )
Interruptions: Message Catch Boundary Events can be defined as either interrupting or non-interrupting.
- An interrupting message boundary event ( ) can model alternative flows when a specific message is received, such as an error message or a cancellation request. This allows the process to adapt to new information and handle exceptions gracefully. When the message is received, processing of the sub-process and any child sub-processes is interrupted. The parent subflow continues along the route forward from the interrupting message boundary event. You can have one or more interrupting message boundary events attached to an object.
- A non-interrupting message boundary event ( ) can be used to create an additional process path if a specific message is received. When the message arrives, processing of the parent task continues. In addition, a new subflow processes tasks on the boundary event route. You can have one or more interrupting message boundary events attached to an object.
Parent Object: Message Catch Boundary Events can be placed on the following activities:
- Task
- Sub Process
- Call Activity
Behaviour: When a Message Boundary Catch Event becomes the current object on proess instance execution, the event creates a message subscription for the specific message name, key name and key value that it is expecting. Process execution then waits for the message flow listener to receive an incoming matching (correlated) message. When a message is received and correlated, any attached message payload is stored into a process variable, and the process instance moves forward.
- Interrupting Boundary Events ( ) : If the message boundary event is interrupting, a correlated incoming message will additionally interrupt the current object and processing will move to the boundary event path.
- Non-Interrupting Boundary Events ( ) : If the message boundary event is non-interrupting, a correlated incoming message will create an additional process execution path (subflow) after the message boundary event. The parent object will continue to be executed.
Configuration: As for a standalone intermediate message catch event.
Variable Expressions: A message boundary catch event can contain an on-event variable expression, which fires after the incoming message has been correlated.
Edition: Message Boundary Events are only available with the Flows for APEX Enterprise Edition.
Message Throw End Events ( )
A Message Throw End Event additionally prepares and sends a messageFlow simple message to its designated endpoint when it occurs.
Use Cases: This can be used to implement the following collaborating behavior:
- inform a waiting process that this process is complete
- send an final document as payload to another process
- start another process once this process is complete
- interupt or change the path of another process when this process completes.
Configuration: Configuration is similar to other message throw events.
Process or Sub Process: Message Throw End Events can be used at the end of a sub-process or at the end of a process.
Edition: Message Throw End Events are only available with the Flows for APEX Enterprise Edition.