SIGNALS Docs

Workflows

Author workflow definitions, publish immutable versions, run manual workflows, and review recent execution.

The workflow handler ID rentals.transition.order accepts an optional to input restricted to order and invokes the guarded order confirmation action with the rentals.edit capability. For REST callers, use POST /api/v1/rentals/{rental}/transitions with {"to": "order"}, the rentals.edit permission and the rentals:write token ability. The approval guard records rental.transition.order as its transition identity. See rental state transitions.

Overview

Workflows automate business processes: a trigger starts a run, and an ordered list of steps carries it out. The admin area is where those definitions are authored — drafted, validated, and published.

Editing and running are deliberately separated. The draft in workflows / workflow_steps is always editable; publishing takes an immutable copy-on-publish snapshot into workflow_versions. Runs are pinned to the version they started on, so editing a draft can never rewrite what an in-flight or historical run executed.

Where it lives

Route: /workflows (workflows.index), /workflows/{workflow}/edit (workflows.edit), /workflows/{workflow}/runs/{run} (workflows.runs.show), /workflows/runs (workflows.runs.index)

Open from the command palette (search Workflows), the header Extensions menu, or go directly to /workflows. Viewing requires workflows.view; creating workflows.create; draft edits workflows.update; publishing, activating, and deactivating workflows.publish; deleting workflows.delete. Running and cancelling require workflows.run. Retry and run-again are separately gated by workflows.retry-failed-step and workflows.run-again, and sensitive run evidence requires workflows.view-sensitive-run-data.

Build a workflow on the canvas

The workflow editor canvas

Select the trigger card to choose an event, schedule, inbound or manual trigger and edit workflow settings in the inspector. For an event, browse or search the event library by business area. Available triggers appear first; expand Coming soon to see events that cannot yet be selected. Their presence in the catalogue does not mean they can start a workflow.

Drag empty canvas space to pan, use the mouse wheel or zoom buttons to zoom, and choose Fit to screen to frame the nodes. Drag a card to position it; layout changes save automatically once the workflow has a step. Arrow keys select neighbouring nodes, + and - zoom, 0 fits, T starts a test, and Escape closes the palette or clears selection. Delete or Backspace removes a selected step; removing a condition also removes its branch steps after confirmation. Keyboard shortcuts do not operate while typing in a field.

Add and configure steps

Click a connector + to open the searchable step library at that position. Choose an action or a control step; the plus on a condition branch inserts into that branch. Conditions evaluate their configured rules and follow the matching branch. Stop workflow is a halt step that ends the run successfully at that point.

The step library opened from a connector

Select a step to edit its name, notes and settings in the inspector. If this step fails chooses Halt, Skip or Retry; the last test result is shown there when available. Review required fields and use the inspector to remove a step.

A selected step and its inspector

Save, publish and status

Save saves your draft, including unfinished steps. Once it has a step, changes also save automatically after about two seconds. The top bar shows Saving…, All changes saved, Unsaved changes, or Not saved with a reason you can open. Invalid or unapplied JSON must be fixed or discarded before saving. If another tab or person has saved a newer draft, reload before continuing; your unsaved edits remain in this tab until then.

Publish checks the draft and creates a fixed version; resolve its issues before publishing. Activate a published workflow to allow triggers to start it, and deactivate it to stop new starts. Existing runs stay pinned to the version they started with.

The editor badge shows Draft before the first publication, Active or Inactive for a published workflow, and Unpublished changes when the draft differs from the published version or has unsaved changes. A workflow must be inactive before deletion; deletion retains versions and run history.

JSON view

The editable workflow definition in JSON view

Choose JSON to edit the workflow definition. Apply validates the JSON and replaces the editor state only when valid; then the draft saves automatically, or you can choose Save. Returning to the canvas centres the steps again. Errors identify the problematic location, and invalid JSON is not applied. Copy or Download the definition, or Import a JSON file into the pane and apply it. When leaving with unapplied edits, choose whether to apply, discard, or continue editing. Sensitive values are redacted; see the definition API guide for the sentinel and import rules.

Test the draft

Choose Test run (or press T on the canvas) to run the current draft against a synthesised sample payload, including unsaved edits. This is a dry run: action handlers simulate their results rather than performing writes, sending messages or making HTTP requests. Trigger conditions and branch rules are evaluated against the sample and simulated outputs; delays are fast-forwarded and waiting steps report that they would wait. A successful simulation is not proof that a live run will pass its permissions, data and external-service checks.

The Run log bar stays above the footer. Open its drawer to see sample data, step results, timings and messages. Drag the drawer’s top edge to resize it; its height is remembered for you. Scroll inside the drawer for longer logs. Trace chips appear on the canvas and the selected step shows its last test. It initially shows the latest real run when one exists, and switches to Test run after a test. It refreshes while a real run is active.

The test run log and canvas traces

Runs and versions

Use the Runs tab for this workflow's runs, status/date/subject filters, the seven-day failure strip and the selected run's evidence and recovery actions. Links can retain the selected tab and run. The separate Workflow runs page at /workflows/runs lists runs across workflows; the full run page provides detailed evidence. Retry and rerun have separate permissions and eligibility checks, described in Workflow operations.

Runs tab with a selected run
The all-workflow runs page

Choose History in the top bar to list published versions, compare versions, or restore one as the current draft. The Activity section groups consecutive edits by the same person within ten minutes and hides layout-only changes. Restoration does not publish it or change historical runs; review and publish the restored draft when ready.

Workflow version history and comparison

Duplicating workflows and using templates

Use Duplicate from a workflow row or the editor toolbar to create an independent, inactive draft named Copy of …. The draft keeps the trigger settings, conditions, steps, and handler configuration. It does not copy credentials, published versions, runs, or schedule occurrence history, so review credential-backed actions before publishing the copy.

When a workflow includes a customer-communication action, its step editor offers eligible communication templates; templates with attachment configuration are excluded from that selector. This is separate from duplicating a complete workflow definition.

Why some event triggers are greyed out

Choosing Event as the trigger lists the system's events, and some appear greyed out and cannot be selected. That is deliberate, not a permissions problem or a bug.

An event is selectable only when the system knows how to start a run from it — which record the run is about, whether the workflow is allowed to read that record, and which fields must be withheld from the run's stored evidence. That knowledge is added one area of the application at a time. Events whose area has not been enabled yet stay listed so you can see the event exists and plan for it, but they cannot be chosen.

If a trigger you need is greyed out, ask for its area to be enabled rather than working around it — the alternative would be a workflow that publishes successfully and then never fires.

A published workflow also records which area definition it was published against. If that definition later changes shape, the workflow is refused rather than run against evidence it was not authored for, and the run view names the reason. Re-publishing the workflow picks up the current definition.

What a workflow cannot do to your data

The Fire Event step emits a custom signal that other workflows can listen for. It cannot emit a business event such as "invoice paid" or "approval completed". Those describe things that have genuinely happened, and a workflow is not allowed to assert one that has not.

To make a workflow actually change something, use the step built for that change — change a status, generate a document, request an approval. Those steps enforce the same rules a person is held to, and the business event follows from the real change.

Signed inbound triggers

Choose Inbound as the trigger when a sending application should start the workflow with a signed HTTP request. The Inbound endpoint panel lets an editor create or rotate a workflow-scoped signing credential, copy the endpoint and sample signed curl command, or revoke the credential. A new or rotated secret is revealed once only; save it in the sending system before navigating away or reloading. After a rotation the replaced secret keeps verifying for 24 hours (WORKFLOW_CREDENTIAL_ROTATION_OVERLAP_SECONDS) so the sender can switch over, then it expires. Revoke the credential instead when a secret has leaked and must stop working at once. Failed signature checks are limited to 60 a minute per credential and sending address; valid deliveries do not count.

Define the request's JSON shape in Inputs (JSON). Save and publish the workflow, then activate it before sending requests. The sender must use the timestamp and HMAC signature headers shown in the sample command. Accepted requests return a run reference asynchronously, while replayed, stale, or invalidly signed requests are rejected.

Rotation does not shut off the preceding secret. It creates a new active version while keeping prior versions usable during an intentional grace period. If a secret may have leaked, rotation alone is not sufficient: use Revoke to disable every active version of that credential, then create a replacement credential if inbound access is still required.

Runs and suspensions

A published, active manual workflow can be started using Run now in the trigger inspector. This starts a real run with real effects, unlike Test run. Runs distinguish queued or running work from delayed and awaiting work; awaiting can represent an approval or external continuation. The run inspector and full run page show the pinned version and evidence.

Notes

  • A workflow must be published before it can be activated, and deactivated before it can be deleted.
  • Deleting a workflow is a soft delete; published versions and run history are retained as evidence for runs that already happened.
  • Step types come from the workflow handler registry, so plugins that register handlers appear in the editor automatically.

Administration and runtime dependencies

Workflow authority is intentionally split into granular abilities and domain permissions. The API abilities are workflows:read for definitions, versions, and run summaries, and workflows:write for workflow writes and starts; the domain policy still applies to each operation. The seeded management roles explicitly carry workflow management, run, sensitive-evidence, and run-again grants. A workflow's service principal is not an interactive user: it executes with the configured capability set, and a handler's missing capability fails the run.

That capability set is the single global list workflows.service_principal.capabilities in config/workflows.php; it applies to every workflow. The shipped default is read-mostly, so these handlers fail until an admin adds the capability they need:

Handler Capability
rentals.allocate_asset, rentals.allocate_assets, rentals.change_status, rentals.transition.order rentals.edit
activities.create activities.create
documents.generate; communications.send with a generated-document attachment documents.create
invoices.generate_from_rental invoices.create
invoices.issue invoices.issue
repairs.create repairs.create
assignments.create resource-assignments.create
rentals.create rentals.create
accounts.create accounts.create
records.update the chosen record type's view and edit capabilities (for example rentals.edit), plus any per-field capability

external.http and webhook.signed need external.http and integrations.credentials.use; both are in the shipped default, and publishing checks them like every other declared capability.

Add only the capabilities your published workflows require; every workflow run gains them.

Detailed trigger, context, error, input, and output data is size-limited and redacted by configured paths, including wildcard paths. The evidence retention operation removes detailed data after the configured period (minimum 90 days) but preserves redacted operational summaries. Sensitive expansion is audited and cannot restore pruned details.

Workflow execution uses the dedicated redis-workflows connection and workflows queue with a dedicated worker. External HTTP execution enforces HTTPS, timeout, response-size, redirect, retry, and private-target allowlist limits. Signed inbound integrations require a configured credential; an accepted request returns a run reference rather than running synchronously in the request.

Repair and reconciliation

Scheduled dispatch and timing reconciliation are bounded, non-overlapping operations. If a delayed run is parked or its timing state needs repair, use signals:workflow-timing:repair with an operator reason; its --dry-run preview does not execute the workflow, while --repair applies the bounded repair. Do not repair by editing run history or by starting an unlinked duplicate.

If a plugin dependency is incompatible, disabled, missing, upgrade_required, or invalid, new runs and affected publication/activation paths are blocked. Enable or install a supported plugin, or publish a replacement workflow version. Existing pinned-run history and redacted health diagnostics remain available for reconciliation.

For account capabilities and refusals, see Accounts.