Messages, signals and timers explained

Processes often have to wait: for a payment, for an approval from another system, for a deadline. BPMN gives you three kinds of event for this.

Messages

A message event waits for a named message with a correlation key. The key is taken from a process variable — for example orderId — when the instance starts waiting. Only instances whose key matches are resumed.

curl -X POST http://localhost:3000/api/v1/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messageName": "payment-received", "correlationKey": "order-1234", "variables": {"paid": true}}'

Signals

A signal has a name but no key. Broadcasting it resumes every instance waiting for that signal and starts a new instance of every process whose start event listens for it.

curl -X POST http://localhost:3000/api/v1/signals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signalName": "price-list-updated"}'

Timers

A timer waits until a fixed date and time, or for a duration counted from when the token arrives. Durations use the ISO 8601 format: PT10M is ten minutes, P2D is two days.

On the edge of a task

Any of the three can also sit on the border of a task as a boundary event.

Sending a message or signal that nobody is waiting for is not an error. The API answers 202 Accepted with a count of the instances it resumed or started.