Approval Chains
Author approval chain definitions — triggers, conditions, stages, and approvers — and publish immutable versions.
Overview
Approval chains decide which transitions need sign-off, who signs them off, and in what order. A definition is edited as a draft and published as an immutable version, so in-flight approval requests keep the rules they were raised under. Published and paused versions are read-only; fork one to make a new draft. Archived versions remain available for audit but cannot match new requests.
Where it lives
Route: /admin/settings/approval-chains (admin.settings.approval-chains)
Open Admin → Users & Security → Approval Chains. The page requires approvals.manage.
Chains configure approvals; they do not action them. Decisions are taken in the approvals inbox at /approvals, reachable from the Approvals icon in the header action strip (gated on approvals.view), which badges the number of actionable requests in Needs you.
The builder has three columns:
- Chains and Delegations — choose a version, inspect its active/paused/draft state, or manage time-bounded delegation cover. When this navigation has focus, ↑ and ↓ switch chains.
- Editor and Test this chain — configure the selected draft and dry-run it without creating an approval request.
- In plain English — read the current rule back as sentences before saving or publishing it.
Key workflows
- Create a draft, pick the trigger event, and combine snapshot conditions with all (AND) or any (OR) matching.
- Build ordered stages resolved to a role, named internal account, or the record owner's manager. Each stage retains quorum, SLA, optional skip condition, escalation, and delegation-window settings.
- Configure a fallback role, named account, or owner manager, plus the request expiry window and behaviour.
- Validate and save a draft, then publish it as a new immutable version. Earlier versions remain pinned to their existing requests; use Create draft from this version to fork a published or paused version.
- Add delegation cover from one active internal account to another for either every chain or one chain version. Cover has an explicit start and end, can be edited while active, and can be revoked early. Revoking it also removes authority derived from that cover.
Batch approval cap
The approval chains settings page also offers an optional tenant-wide bulk approval value cap in the base currency. Enter the displayed currency amount; Signals stores it in minor units. Leave it unset to omit the value test. When set, a request needs a comparable value at or below the cap to qualify for batch approval. Single-stage, authority, deadline and exclusion checks still apply. See Batch Approvals.
Archive, restore, and delete
The chain list hides archived versions by default. Turn on Show archived to inspect or restore them.
- Delete permanently removes only a never-published draft that no approval request references. The action is confirmed inline and cannot be undone.
- Archive retains an unreferenced published or paused version, its immutable definition, and its active or paused flag. Archived versions do not match new approval requests and cannot be forked.
- Restore makes an archived version visible in the normal list and eligible to match again according to its preserved active or paused flag. Restore a version before using Create draft from this version.
Archive and restore accept an optional reason. Each lifecycle transition is audited and emitted through the webhook event catalogue. A definition referenced by even one approval request cannot be archived or permanently deleted, so historical requests always retain their definition.
The API exposes the same lifecycle through POST /api/v1/approval-chain-definitions/{approvalChainDefinition}/archive, POST /api/v1/approval-chain-definitions/{approvalChainDefinition}/restore, and DELETE /api/v1/approval-chain-definitions/{approvalChainDefinition}. All three mutations require approvals:write and approvals.manage, participate in idempotency handling, and accept a stable Idempotency-Key for safe retries.
Testing a chain
Test this chain calls the same matcher and approver resolver used by the approval engine, but persists nothing. Choose one of the most recent rentals that reached an approval gate or enter a free JSON payload. A short free payload is treated as the captured snapshot:
{
"amount": 250000
}
For requester-conflict and subject-aware resolution, use the full scenario form with snapshot, actor_type, requester_account_id, and optionally the registered subject_type and subject_id.
The result states whether the chain matched, did not match, or is paused. It then shows every condition and stage, including resolved direct and chain-delegated approvers, quorum, SLA, escalation, skip-condition evaluation, fallback use, and requester conflicts. Legacy free-text skip conditions are shown as configured but unevaluated; they are never presented as a successful rule evaluation.
When a recent persisted request is selected, its progress lists every assigned actor and every active delegation in a parallel stage; the current marker follows whichever assignment is actionable.
Amount-banded resolver
Existing definitions may contain a two-role amount band (band_limit, lower-band role, and upper-band role). The builder displays both bands read-only so the stored definition remains intelligible. The approval engine does not yet implement this resolver, so administrators cannot select or edit the banded option. Use a supported resolver until engine support is added.
Permissions
| Ability | Grants |
|---|---|
approvals.manage |
Reach and edit the Approval Chains admin page |
approvals.view |
See the approvals inbox and the header Approvals badge |
approvals.act |
Approve, request changes, reject, or delegate an assignment |