ECA integration¶

The orchestra_eca submodule bridges Orchestra and ECA in both directions, so workflows and event-driven automation can drive each other with no custom code.

ECA → Orchestra: start a workflow from an event¶

The "Orchestra: start process" ECA action launches a process instance from any ECA event. Model "when a node is published, start the review workflow" entirely in ECA: point the action at a workflow, and optionally store the new instance ID in a token for later actions.

Orchestra → ECA: ask ECA from a workflow¶

The eca_event task type is the other direction. When a token reaches the node it emits a custom ECA event, and (this is the useful part) it can take an answer back from whatever ECA model reacts, and route on it.

Node settings:

Setting	What it does
Event ID	The custom event dispatched when the token arrives. ECA models react to a "Custom event" with this ID.
Result variable	The process variable the answer is written to, so outgoing flow conditions can route on it. Leave empty for a fire-and-forget notification.
Result scope	`instance` (shared) or `token` (local to this branch).
Result token	The ECA token the answering model writes to. Defaults to `orchestra_result`.

The node exposes the waiting task to the reacting model as the ECA token [orchestra_token], so the model can answer the right task.

Answering the task¶

Use the "Orchestra: resume a waiting task" action to answer. It works whether the model answers now or later:

Synchronously (the model answers inline): it hands the result straight back to the task, which advances with it.
Asynchronously (the model answers later): it resumes the task that was waiting.

flowchart LR
  ask["eca_event<br/>(Ask ECA)"] -->|fires event| model[ECA model reacts]
  model -->|Orchestra: resume<br/>a waiting task| ask
  ask -->|routes on the result| out([approved / rejected])

Synchronous (answer now)¶

The ECA model reacts to the event and, in the same run, calls "Orchestra: resume a waiting task" with the result (e.g. approved). The task reads it and continues immediately, no waiting. This is the example_eca_sync workflow.

(You can also answer by setting the result token directly with ECA's "Set token value" action, naming it to match the node's Result token, but the resume action is the simpler, name-free way.)

Asynchronous (answer later)¶

Sometimes the answer can't be produced inline: it is queued (eca_queue), runs on cron, or comes from a remote system. In that case the model declares it will respond later:

The reacting model calls "Orchestra: answer this task later", which parks the task (the workflow waits), and stashes [orchestra_token] somewhere it can find it later (e.g. ECA "State write").
When the deferred work finishes, it calls "Orchestra: resume a waiting task" with the result, resuming the parked task.

This is the example_eca_cron workflow: an async responder parks the task and remembers its token; a cron-triggered model later reads the token and resumes it. On a preview you can hit Run cron to watch the parked instance resume.

Keep it unambiguous: one event, one responder¶

ECA tokens are a shared, last-writer-wins scratchpad. If several models react to the same event and write the same result token, you get whichever ran last, and the order is not guaranteed. So give each question its own event ID, reacted to by a single responder. Then the answer is deterministic and "which value did I get?" can't arise.

Reacting to a timeout¶

The other way Orchestra talks to ECA is on a timeout. A parking node with timeout_action: notify (see Timers) announces a timeout instead of resuming; orchestra_eca re-dispatches it as the orchestra_task_timed_out custom event. React to it in a model (branch on [orchestra_tag], send an email, post to a channel) to build reminders and escalations with no code. These tokens are exposed:

Token	Value
`[orchestra_token]` / `[orchestra_instance]` / `[orchestra_node]`	The timed-out task's IDs.
`[orchestra_tenant]`	The tenant.
`[orchestra_tag]` / `[orchestra_message]`	The node's `notify_tag` / `notify_message`.

Because the task stays parked, the event recurs each timeout window until it is handled.

Examples¶

The orchestra_examples submodule ships ready-to-run round-trips (each with its responder ECA model, so they self-complete):

Workflow	Shows
`example_eca_sync`	ECA answers inline; the task advances and routes on the result.
`example_eca_cron`	ECA answers later; the task waits and cron resumes it with the result.
`example_reminder`	A timeout fires the `orchestra_task_timed_out` event; a model records a reminder.