11. Events and schedules

Triggers

Trigger	Mechanism
An application decides	POST /api/workflow/{name}
A person decides	The UI, which calls the same endpoint
A message arrives	An event handler
A time is reached	A schedule
Another run asks	START_WORKFLOW or SUB_WORKFLOW task

This page covers the third and fourth.

Event handlers

An event handler is a stored rule with four parts:

Part	Meaning
source	Where messages come from: eventgrid:{topic}, servicebus:{topic}/{subscription}, or eventhub:{hub}
condition	A JSONPath predicate on the message body, for example $.status == 'READY'. Empty means always.
actions	What to do: start_workflow, complete_task, fail_task, terminate_workflow
active	On or off. Default off.

Example, registered through POST /api/event:

{ "name": "start_fulfilment_on_order_ready",
  "source": "eventgrid:orders",
  "condition": "$.status == 'READY'",
  "actions": [ { "action": "start_workflow",
                 "start_workflow": { "name": "fulfil_order", "version": 1,
                                     "correlationId": "${orderId}",
                                     "input": { "orderId": "${orderId}" } } } ],
  "active": true }

${...} in actions refers to fields of the message body.

Sources

Event Grid, Service Bus topics, and Event Hubs each deliver to a trigger in the engine. All three call the same handler function, which loads the active handlers for the source, evaluates each condition, and runs the matching actions. Every attempt writes an event_execution row: handler, message id, action, result. GET /api/event/executions reads them.

Source	Use when
Event Grid	Discrete events. Also carries events the engine publishes itself with PUBLISH_EVENT.
Service Bus topic	Messages must be processed in order.
Event Hubs	High-volume streams from the data platform, evaluated in batches.

Status events

When a definition sets statusListenerEnabled: true, the engine publishes WorkflowStatusChanged and TaskStatusChanged to the Event Grid topic wos-status on every change. Consumers subscribe with a filter on workflow name. Typical consumers: a Teams notifier, a CRM mirror, the analytics platform.

Run-to-run messaging

A run publishes with PUBLISH_EVENT. A handler on the same topic starts or continues another run. Neither run knows the other's id. The correlationId field links them for search.

Schedules

A schedule is a row: {name, workflowName, workflowVersion, cron, input, active}, registered through POST /api/schedule. A timer function runs every minute, finds active schedules whose cron matches, and starts each with the stored input and correlation id {schedule name}:{timestamp}. Each schedule starts at most one run per minute.