Sending an event from a workflow¶

A step can tell other instances that something happened. The Send an event step sends a named event, as a webhook does from outside: delivered to the step waiting for it, broadcast to every step waiting for it, or starting the workflows that start on it. Then it goes on.

An example¶

An order workflow waits for the goods before it ships. A stock reception workflow counts what arrived, and tells the order:

# In the order workflow, started with the order number as correlation key.
n_wait_stock:
  type: event
  config:
    event: stock_received
    payload_variable: stock

# In the stock reception workflow, which holds the order number in `order`.
n_tell_the_order:
  type: send_event
  config:
    event: stock_received
    reach: deliver
    correlation_variable: order
    data: "quantity\nwarehouse|location"
    payload_variable: told

The order instance carrying the order number resumes, with stock.quantity and stock.location. The reception instance goes on at once, and told holds resumed.

Settings¶

Setting	What it does
Event (`event`)	The machine name of the event, such as `stock_received`.
Delivery (`reach`)	`deliver` to the one step waiting for it, `broadcast` to every step waiting for it, or `start` the workflows starting on it. See Deliver, or broadcast and Starting a workflow on an event.
Keep an early event for (`keep_seconds`)	Delivered only: how long the event is kept when its step is not waiting yet. An hour by default. See An event that arrives early.
Event data (`data`)	The variables sent as the event's data, one per line: `name`, or `name\\|field` to send it as another field. A variable this instance does not carry is left out.
Workflow (`workflow`)	Delivered or broadcast: only the instances of this workflow.
Correlation key variable (`correlation_variable`)	A variable of this instance holding a correlation key: only the instances carrying it are reached, or the instances started carry it.
Select by variables (`criteria_variables`)	Delivered or broadcast: only the instances holding the same values as this one, one variable per line: `name`, or `name\\|their_name` when the other instances name it differently.
Payload variable (`payload_variable`)	Where what became of the event is written, for the flows to route on.

An event always stays in this instance's tenant. A start refuses the Workflow and Select by variables settings: it selects no instance.

Which instances it reaches¶

The step selects the running instances of its tenant that all of its settings name: the workflow, the correlation key, the variables. Naming none reaches every instance of the tenant waiting for the event, as event names belong to the tenant.

The sending instance is never one of them. It cannot resume its own waiting step, and an event kept for later is never taken by it either. To move a branch of the same instance on, a flow does it.

A variable the step selects by must hold a value. When the correlation key variable or a Select by variables variable holds none, NULL included, or the key is longer than a correlation key can be (255 characters), the step fails as any step does, on an incident by default, rather than sending the event to every instance of the tenant.

What became of the event¶

The payload variable holds one word:

Value	Meaning
`resumed`	The event resumed a waiting step, or several for a broadcast.
`kept`	Delivered, the instance selected was not waiting yet: the event is kept for it.
`started`	The event started at least one workflow.
`no_instance`	No other running instance is selected.
`not_waiting`	No step waits for the event: broadcast, or delivered with nothing kept (Keep an early event for at 0).
`several_waiting`	Delivered, several steps wait for it: broadcast it, or select fewer instances.
`no_workflow`	Starting, no workflow of the tenant starts on the event.
`not_unique`	Starting, each workflow starting on it refused a second instance with the same start data.
`too_large`, `invalid`	The event data is over 64 KB, or cannot be sent.

A refusal is not a failure: the step goes on, and its flows route on the value. For example, to wait for the order when the event found nobody:

- id: f_nobody
  from: n_tell_the_order
  to: n_try_again_later
  condition:
    plugin: comparison
    settings: { variable: told, operator: '==', value: no_instance }

Sent once per pass¶

The step sends in an advance of its own. A failure after the sending rolls it back, steps reached included, so the step's retry sends the event once. A loop passing through the step again sends it again.

When the instances reached go on¶

A workflow starting on the event starts in the same advance as the sending step, as a subprocess does, and runs as its execution mode says.

An instance resumed by the event goes on at the next drain, on cron or from the drain endpoint, even when it runs synchronously: a synchronous run only ever advances its own steps, never another instance's (see Execution mode).