Correlation for Intermediate Message Events

Correlation Conditions

If you use intermediate message events in your process, you have to configure correlation conditions for them. The correlation condition is a Boolean test that determines whether or not the incoming message would be delivered to the respective process instance. This condition may refer to both the message payload and the process data context. Conceptually, these conditions are expressions that can only consist of equality predicates that check whether the left or right side of an expression is exclusively relating to the message payload or the process context.

The default value of the correlation condition is true . This means that all of the process instances with that intermediate message event always match the message that is referred to. If the value of the correlation condition expression is false , then the message is never matched and none of the process instances that has the intermediate message event picks up the message.

The expressions could be complex and incorporate functions such as the built-in functions in the expression editor or custom mapping functions, as well as business rules that are exposed as functions. You can also use literals and constants within an expression. For equality comparison, you can use the functions boolean-equal (boolean, boolean), string-equal (string, string) and numeric-equal (long, long).

For more information about expressions and functions, see:

• Creating Expressions

• Built-In Functions

• Creating an External Function, Exposing It as an EJB, and Using it as a Mapping Function

Correlation conditions allow the comparison of complex keys which can only be accomplished by the logical conjunction (AND) of expressions over the message payload and process context.

When you use message context and process context within one expression in the correlation condition, you can use them only if they are on different sides of the equation. In case you are using a function for the comparison, one of the parameters of the function can reference either the incoming message payload or the process context. This is automatically checked by the SAP NetWeaver Developer Studio and the build.

Message Receipt and Consumption

Receiving a message happens in multiple transactions, matching and delivery. These transactions are asynchronously decoupled and can run at different points in time.

• Matching: The message is delivered to the process server. In the matching transaction, an incoming message is matched against the correlation conditions of all process instances that contain an intermediate message event for the corresponding message trigger. If at least one process instance matches the message, that is, the correlation condition of its intermediate message event evaluates true , the message is queued for delivery to that process instance in the delivery transaction.

• Delivery: The process server actually executes the intermediate message event, that is, it receives the message, output maps its payload to the process data context, and proceeds in the respective control flow branch. If multiple process instances have matched a single message, the message is delivered to all of those process instances in multiple delivery transactions, which can happen at different points in time.

When you formulate a correlation condition that compares the message payload to the process context, a message is initially matched if, and only if, the defined condition holds against the state of the process context at the time the message is received. To deliver the message to the intermediate message event successfully, the defined correlation condition needs to permanently hold until the message is delivered to the process instance. If there is a change in the process context between the matching and delivery transaction and the correlation condition no longer holds, the message is not matched, and is removed from the queue for the respective process instance.

If, between matching and delivery, the correlation condition is first invalidated and later holds true again, the delivery of the respective message that was initially matched to the process instance cannot be guaranteed. Other process instances that concurrently match the same message can get the message delivered.

If more than one message arrives, only one of them will be delivered. The other messages and the messages that come in after the flow has progressed beyond the intermediate message event are still matched. As long as the process instance has not terminated and continues to match messages, the messages stay in the queue. If you want to avoid the message being purged from the queue when the process instance has terminated, you use the conditional start feature. Conditional start is enabled by using the same message trigger for the process start event and for one or multiple intermediate message events that are included in the process. Matching messages that cannot be delivered to an instance of that process will be queued and delivered to a new instance of that process definition. That is, the start event of that new instance consumes the message. For more information about modeling start events and defining a start condition, see Modeling Events .

Message Receipt During the Process Life Cycle

Receipt and consumption of messages can happen at different points in time during the process flow. Once a process is instantiated, it can receive messages regardless of the events it has reached or its status. All running process instances and their intermediate message events are able to receive messages, whether they are currently suspended or not. These messages would be consumed only when the process instance is resumed and reaches intermediate message events that listen for these messages. The consumption of these messages is not organized in any particular order.