Workflow Operations

Operate, observe, and recover delivered workflow runs safely.

Lifecycle#

A run is created as pending, then normally becomes running. It can be delayed while waiting for a scheduled time or handler delay, awaiting while an approval or external continuation is outstanding, and finally completed, failed, or cancelled. The terminal state is retained with a redacted operational summary even when detailed evidence is later pruned.

Runs execute against the immutable published version that was pinned when the run started. Editing or publishing a newer draft does not rewrite an existing run. A workflow must be published and active before it can be triggered.

Cancelling, retrying, and running again#

Operators with workflows.run can request cancellation from the run view. The request records the actor and reason and is cooperative: an in-flight handler finishes its cancellation boundary before the run becomes cancelled.

These recovery actions have different meanings:

• Retry failed step creates a linked recovery run starting at the latest eligible failed node; the failed source run stays unchanged. It requires workflows.view and workflows.retry-failed-step, retained run context and the pinned version, and is only available for a failed run whose workflow is still active.
• Rerun from start starts a separate linked run from the beginning using the current published version. It requires workflows.view and workflows.run-again, revalidates the retained trigger and subject, and does not undo effects from the original run.

Both actions are idempotent by their command key. A pruned run, an unavailable subject, or an inactive workflow must be repaired or made eligible before the action can proceed.

Delays, schedules, and approvals#

Handlers may return a delay or suspend with a correlation. Delayed runs retain their timing state; scheduled workflows are dispatched by signals:dispatch-scheduled-workflows. Schedule misfires use the workflow's configured policy: run the latest due occurrence, run all due occurrences, or skip them. Dispatch and timing reconciliation are bounded and non-overlapping scheduled operations.

An approval suspension can resolve as approved, rejected, expired, or cancelled. A decision is accepted once; duplicate or late decisions do not produce another outcome. The run remains awaiting until the suspension is resolved or expires.

External systems resume a correlated suspension with POST /api/v1/workflow-resumes (api.v1.workflow-resumes.store). The endpoint is not Sanctum-protected: the one-time 64-character alphanumeric token in the body is the credential, and the route is limited to 10 attempts per minute per client IP. The body requires token, status (approved, rejected, or expired), and a present result that satisfies the suspension contract. A successful call consumes the token and returns { workflow_run: { id, status } }. A wrong outcome leaves the token usable (422 workflow_resume_token_wrong_outcome); an invalid token returns 404; a used, revoked, expired, or unavailable token returns 410; a contract mismatch returns 422 workflow_resume_invalid_result; excess attempts return 429 workflow_resume_rate_limited. See Workflow Triggers & Conditions and the Workflow Handlers Reference.

Integrations and execution boundaries#

Inbound workflow integrations use a configured credential and signed request; POST /api/v1/workflows/{workflow}/inbound/{credentialKey} (api.v1.workflow-inbound-runs.store) accepts a rental subject plus arbitrary workflow input, verifies the HMAC over the raw body, and acknowledges accepted work with a workflow run reference. Replayed signatures, inactive or unpublished workflows, and disabled credentials do not queue another run. External HTTP handlers enforce HTTPS, response and redirect limits, retry limits, and the configured outbound private-target allowlist. A workflow service principal executes handlers with the capabilities declared by the workflow; missing capabilities fail execution rather than silently widening access.

Workflow work is queued on the dedicated redis-workflows connection and workflows queue, consumed by its own worker (see config/queue.php workers). Queue attempts and backoff are part of the delivered runtime configuration, so a transient handler failure is distinct from an operator-initiated retry or a new run.

Evidence and sensitive data#

Run summaries expose operational metadata and a redacted outcome. Detailed trigger payloads, context, errors, and step data are available through the evidence view while retained, but are not included in the summary resource. Payloads are JSON-serializable and size-limited; configured dot paths, including wildcard paths, are redacted before persistence or display.

Use sensitive expansion only for an authorized investigation. It requires workflows.view-sensitive-run-data, records an audit event, and is unavailable after evidence has been pruned. The retention command removes detailed payload, context, error, input, and output data while keeping the redacted operational summary; the configured minimum retention is 90 days.

Common recovery#

1. Check the lifecycle state, pinned workflow version, lineage, service principal, and retention state in the run summary.
2. Read redacted evidence and the audit trail before retrying. If the run is awaiting, resolve the outstanding approval or external continuation rather than starting a duplicate run.
3. For a terminal failed run, use Retry failed step when the original pinned version and retained context are still valid. Use Rerun from start only when a fresh run is intended and the original effects are understood.
4. If timing is parked or inconsistent, preview with signals:workflow-timing:repair --dry-run, then use signals:workflow-timing:repair --repair --reason="..." for a bounded live repair. Preview and live repair are separate modes; a repair does not execute the workflow.
5. If a plugin dependency is unavailable, incompatible, disabled, missing, upgrade-required, or invalid, restore a compatible enabled plugin or publish a replacement workflow version before starting new runs.

See Workflows, the workflow-run operations in the OpenAPI reference, and workflow extension contracts.

Evidence retention is run by signals:workflow-evidence:prune --days=...; the command enforces the configured minimum retention and preserves redacted summaries.

Workflow API and MCP#

All paths below are under /api/v1. The OpenAPI reference describes request and response fields, errors and token abilities. Workflow reads require workflows:read; writes and starts require workflows:write. The corresponding workflow policy and operation-specific permissions also apply.

The definition write, validation and import endpoints accept an object under definition. Validation reports errors at JSON pointers and does not save. Replacing a draft is atomic; importing creates an inactive, unpublished draft with fresh node keys. Restoring a version replaces the draft, not the published snapshot. A manual start requires a published, active manual workflow; a dry run simulates a draft without executing its effects.

Canonical definition#

Exports use signals.workflow/v1. This complete example shows a manual trigger and a halt step; handler configuration and condition branches depend on their schemas. Positions and canvas metadata are editor layout, while status, version and active describe the export rather than publishing or activating an import.

{
  "schema": "signals.workflow/v1",
  "workflow": {
    "name": "Manual completion",
    "description": "Stop successfully after a manual start",
    "status": "draft",
    "version": 0,
    "active": false,
    "execution_mode": "queued",
    "concurrency_policy": "serialize",
    "settings": {"execution_mode": "queued", "concurrency_policy": "serialize"},
    "trigger": {"kind": "manual", "key": "manual", "config": {}},
    "canvas": null,
    "steps": [
      {
        "key": "11111111-1111-4111-8111-111111111111",
        "type": "halt",
        "handler": null,
        "label": "Stop successfully",
        "description": null,
        "config": {},
        "failure_policy": null,
        "position": {"x": null, "y": null}
      }
    ]
  }
}

Condition nodes contain a branches object keyed by branch name, each holding an ordered array of nested steps; their branch configuration declares the corresponding rules. Sensitive fields in exports are replaced with __redacted__. When updating an existing workflow, that sentinel preserves the existing value at the same path; it cannot supply a secret to a new workflow or a path with no existing value. Supply an appropriate value before importing into a new draft. Exports do not expose credentials.

MCP tools#

The curated server exposes list-workflows, get-workflow, create-workflow, update-workflow, delete-workflow, duplicate-workflow, create-workflow-from-template, publish-workflow, activate-workflow, deactivate-workflow, export-workflow-definition, import-workflow-definition, create-workflow-from-definition, validate-workflow-definition, list-workflow-versions, get-workflow-version, diff-workflow-version, restore-workflow-version, list-workflow-runs, get-workflow-run, get-workflow-run-evidence, export-workflow-run-evidence, run-workflow, dry-run-workflow, cancel-workflow-run, retry-workflow-run, rerun-workflow-run, get-workflow-run-log, get-workflow-failure-strip, list-workflow-handlers and list-workflow-events. The same policy and capability boundaries apply.