Skip to content

Context Variables

Context variables carry data between steps in a workflow run.

For a declarative sketch of workflow-scoped variable slots (names, types, optional defaults, provider link), see Workflow YAML — Scoped context (sketch).

For the implementation plan (run observability, registry metadata, designer phases), see Plan — scoped context (variables).

For runner-owned state vs stateless variables operations, see ADR 0008 — Stateless variables provider.

For the broader scope concept (sub-workflow–like units: input, output, context; connections at workflow level; visibility rules), see ADR 0003 — Workflow scope concept.

Scoped context: values and types

When a workflow declares scoped_context:

What Where
Runtime values Orchestrator run context keys (same name as the variable)
Types Reserved context key _scoped.declarations — JSON list of {name, type}
Initial values scoped_context.variables[].init.value merged at run start (unless trigger/initial_context already set the key)

The variables capability provider does not store values. It exposes stateless operations (variables.string_concat, variables.numbers_add, …). Operands are sent in the service_call POST body.

Type checks on variables.* calls

  1. Orchestrator — if payload_from is context:<name> and <name> is declared in _scoped.declarations, the declared type must match the operation (e.g. numbers_add requires a number declaration).
  2. HTTP header — orchestrator sends X-Scoped-Declarations on variables.* calls so the provider can enforce rules on future name-based operations.
  3. Provider — Pydantic validates request body shape (parts as strings, numbers as floats).

Typical Sources

  • Initial request payload.
  • Step outputs (including service_call response bodies via outputs[step_id] or output_key).
  • Trigger metadata and headers.
  • Runtime configuration values.
  • scoped_context.init defaults.

For conditional branching (if, when) on values inside JSON or XML — including output from a service_call — see Conditions & Path Expressions.

Best Practices

  • Use stable, descriptive context keys.
  • Declare types in scoped_context when using variables operations or designer tooling.
  • Avoid storing large blobs unless required.
  • Redact or avoid secrets in context where possible.
  • Keep context contracts documented for reusable workflows.