Skip to content

ADR 0005 — External triggers, payload contracts, and variables provider first

Status: Proposed (target architecture + near-term delivery focus)
Date: 2026-05-04
Related: ADR 0001, ADR 0002, ADR 0003, ADR 0004, Workflow YAML

Context

MeshFlows workflows today still carry an invocation block on the workflow document (HTTP vs schedule vs AMQP, optional filters, etc.). Scheduled runs use a dedicated orchestrator path (/invoke/scheduled) that is coupled to “this workflow allows schedule” semantics in YAML.

Product direction is different:

  1. Triggers are not authored inside the workflow as the primary “how may this run?” contract. A workflow is a definition (steps, optional scoped variables, connections, examples). Who may start it, when, and with which pre-checks live in separate trigger resources (and in dashboard-initiated runs). The scheduler / trigger provider decides scheduling and binding—not a schedule flag on the workflow as the long-term source of truth.

  2. Payload shape is workflow-owned. A workflow may treat its pipeline as XML, JSON, or RAW (opaque bytes/text). RAW is intentionally open-ended: e.g. plain text, base64-encoded binary, or other conventions the steps agree on. The engine should not over-specify RAW beyond transport and size limits; validation belongs to steps or explicit transforms.

  3. Example messages remain useful on the workflow for dashboard authoring and “run with sample” UX. Triggers may also carry example payloads (same purpose: documentation, test invocations, contract hints for operators).

  4. Delivery priority: validate the variables provider path end-to-end with a small test workflow before investing in other providers. That test flow may include control-flow steps (if, repeat / repeat_until, parallel, scopes) where they help prove isolation and wiring—without blocking the first milestone on full provider coverage.

Decision

1. Triggers are external; workflow is definition + examples

  • Normative intent: start contracts (which channels, which filters, which schedule bindings) are expressed in trigger documents (and dashboard actions), not by embedding a “trigger type” or HTTP/schedule matrix inside the workflow as the only gate.

  • Workflow document focuses on: steps, connections, scoped_context / variables (ADR 0002), default/example payloads for UX, and payload/response format hints where the designer needs them—not on owning the scheduler’s policy.

  • Retrospective / migration: until code and YAML are migrated, some workflows may still contain invocation for backward compatibility. New work should prefer external triggers + dashboard; orchestrator enforcement should converge on this ADR in follow-up changes (separate tasks).

2. Input / output: XML, JSON, RAW (workflow-defined)

  • The workflow (and its steps) define whether the primary body is interpreted as XML, JSON, or RAW.

  • RAW means “no engine-mandated structure”: may be UTF-8 text, base64-wrapped binary, or other agreed encodings between producer and steps. The orchestrator remains responsible for transport (size limits, tracing, storage of artifacts), not for interpreting every RAW variant.

  • Auto vs explicit hints (payload_format / response_format or successors) remain hints for tooling and the gateway/dashboard, not a second execution engine inside the orchestrator.

3. Example messages: workflow and triggers

  • example_payloads (or equivalent) on the workflow stay the primary place the dashboard loads samples for “try this workflow”.

  • Triggers MAY include example message(s) for the same reasons: operator docs, dry-run, CI fixtures, and consistent previews when a trigger is selected in UI.

  • No requirement that examples exist in both places; absence in triggers does not block dashboard examples, and vice versa.

4. Near-term milestone: variables provider test flow first

Goal (ordered):

  1. End-to-end test flow using the variables capability provider (scoped_context init in runner context + stateless variables.* operations), runnable from dashboard and/or a minimal trigger, with clear assertions (run trace, context). See ADR 0008.

  2. Optionally extend that same fixture with control flow—if, repeat / repeat_until, parallel, and scope constructs (ADR 0003, ADR 0004)—only insofar as they de-risk variables behaviour (e.g. per-scope declarations, parallel isolation). They are not a prerequisite for the first green path if they slow delivery.

  3. After that path is stable, revisit other providers (HTTP egress, messaging, etc.) with the same “external triggers + workflow-owned payload” framing.

This ADR explicitly defers broad refactors (removing /invoke/scheduled coupling, tightening “no start without trigger/dashboard”) to implementation tasks once the variables milestone is green.

Consequences

  • Documentation split: operator docs should describe triggers and dashboard as start surfaces; workflow YAML docs should emphasise definition + examples + variables, not “pick HTTP vs schedule here” as the main story.

  • Engine work (later): relax or remove orchestrator gates that duplicate trigger policy (_require_schedule vs trigger-only model), add optional “must have trigger binding” enforcement if product requires it, and align gateway routes with external triggers only.

  • Risk: until migration completes, two mental models coexist (YAML invocation vs external triggers). ADRs 0001–0004 remain the source for variables and scopes; this ADR adds start-surface and payload direction without superseding them.

See also