Messages

Message events pause execution until a message with the correct name and correlation key is delivered to the instance.

<intermediateCatchEvent id="waitForPayment">
  <messageEventDefinition messageRef="PaymentReceived" />
</intermediateCatchEvent>
<message id="PaymentReceived" name="payment.received" />

Message correlation

Correlation key expressions let you target a specific process instance. The expression is evaluated at subscription creation time using the instance’s current variables, and the resolved string value is stored.

<message id="PaymentReceived" name="payment.received"
  activiti:correlationKey="${orderId}" />

Supported expression formats:

The correlation key must resolve to a string or number. If the variable is not found the subscription is created without a key (open subscription — matches any sender).

Matching logic:

• If the subscription has no stored key → matches any sender correlation key
• If the sender sends no correlation key → matches any subscription
• Otherwise → stored key must exactly equal the sender’s correlation key

Delivery tiers

When POST /api/messages is called, the server matches subscriptions in this order:

1. Message boundary subscriptions — active boundary events on running tasks
2. Intermediate catch event subscriptions — waiting catch events inside running instances
3. Message start definitions — creates a new instance if the message matches a start event
4. Event subprocess subscriptions — triggers a message event subprocess inside a running instance

At most one subscription is matched per tier (ambiguous matches return HTTP 409). If multiple tiers match, the higher tier (lower number) takes precedence.

Sending a message

curl -X POST http://localhost:3000/api/messages \
  -H "Content-Type: application/json" \
  -d '{
    "messageName": "payment.received",
    "correlationKey": "order-99",
    "variables": { "paymentId": "pay_xyz" }
  }'

Variables in the message payload are merged into the receiving instance’s variable scope.

Optional targeting fields: