Correlation is declared on the intermediate message event (or the message start event): the event references a UCA, and in its Correlation section you pair a field of the UCA's output with an instance variable expression; the engine resumes only the instances whose variable equals the value in the arriving message.
UCA "OrderShipped" (output: shipment (ShipmentInfo) with orderNumber, carrier, trackingId; the UCA's service just passes the message through)
BPD "Order handling": ... [Wait for shipment] (intermediate message event, UCA = OrderShipped)
Correlation: tw.local.order.number == shipment.orderNumber <- the matching rule
Output mapping: tw.local.shipment <- shipment
# sending the event from outside (JMS / event message format, BPM 8.5+ / BAW) - one of the accepted forms
<eventmsg>
<event processApp="ORD" ucaname="OrderShipped">OrderShipped</event>
<parameters>
<parameter><key>shipment</key><value><orderNumber>ORD-42</orderNumber><carrier>DHL</carrier><trackingId>123</trackingId></value></parameter>
</parameters>
</eventmsg>
# the message is put on the event queue (JMS) or sent through the Event Manager's HTTP endpoint (/teamworks/webservices/...); in newer releases the REST API can also send messages to UCAsWhy instances do not resume:
- The instance is not yet waiting at the event when the message arrives - messages are not queued for future correlation unless the event is marked durable subscription (question on durable subscriptions); with a non-durable event a message that arrives before the token reaches the event is lost.
- Correlation value mismatch: type or formatting differences ("42" vs 42, trailing spaces, case); compare after normalising in the UCA's service.
- The UCA's service returned no output or the field name in the correlation is different from the mapped field.
- The snapshot: messages are delivered to the UCA of the snapshot addressed by the message (the default snapshot when none is given); instances of other snapshots do not see it.
Why all instances resume: no correlation was defined (a UCA event without correlation is a broadcast - every waiting instance resumes). Debugging: Process Admin > Event Manager shows the UCA executions and their outputs; the BPD's instance shows the token waiting at the event; enable the WLE trace loggers for a few minutes. Design: one correlation key (a business key you control, like the order number), stored in a top-level instance variable, indexed for search - and make the sender include it in every message.
References