Workflows and stages

A workflow holds the stages a task moves through. Stages are grouped into columns (stage groups), and each task carries a task type. This page is the reference for configuring all four.

Most of the structure here is admin-only to change and read to view; each section states which. See Authentication. Replace https://cadence.example.com with your instance's address.

Workflows

MCP workflows_create, workflows_update, workflows_delete, workflows_get, workflows_list; PATCH /api/v1/spaces/:space_key/workflows/:slug; the web workflow pages. Viewing needs read; creating, updating, and deleting need admin. The web pages create, update, archive and unarchive a workflow but do not delete one, and the API only updates one: delete a workflow over MCP with workflows_delete. workflows_list lists only workflows that are not archived; read an archived one with workflows_get.

A workflow has:

When auto_advance_enabled is true, the sentinel rules on the workflow's stages are evaluated and may move or hold a task with no person involved. A sentinel rule acts on a task only when the space, the stage and the task are not archived, the task has not been resolved since it entered its stage, the task has no blocking hold, no lease of a pool named by an assignment rule at the stage that applies to the task, created since the task entered the stage, is still active, and the rule's predicate over the stage's checks is true. A rule can act when no such lease ever ran. The full list is in What moves a task without a person § A sentinel rule advances or holds the task.

When it is false, only sentinel rules stop: no sentinel rule moves a task, and Cadence places none of the holds that come from the sentinel sweep. Tasks can still move without a person. A worker whose lease reaches a task can still move it with tasks_transition or tasks_transfer, and pools still start work on it. A blocking hold on the task stops pools from starting work on it and keeps sentinel rules from evaluating it, but it does not stop a worker whose lease already reaches the task: that worker can replace the blocking hold with an advisory one, clear the advisory hold, and move the task. No single setting keeps a task where it is until you act. For everything that must be true for a task to wait for you, see Web interface § Making a task wait for a person.

Each workflow also has a numeric id. The workflow permalink, a notification rule's workflow filter, and an inbound rule's workflow setting all name a workflow by this id, not by its slug. Over MCP, the id is the number at the start of the last segment of the url in the ref that workflows_get returns, and that workflows_list returns for each workflow that is not archived. In …/workflows/31-intake, for example, the id is 31. Over the API, PATCH returns it as the workflow's id.

A newly created workflow starts with one empty stage group named Default. Deleting a workflow is refused while it still has any stage groups, stages, or tasks, archived ones included, with workflow has children — empty stages and tasks first. To take a task off the workflow, move it to another workflow with tasks_transfer (see Tasks § Move a task to another workflow). Emptying it is not always possible. A stage cannot be deleted while any task is on it, archived or not, or once it has visit history (see Stages), and a task that is archived, or completed or uncompleted by a move, leaves visit history on the stages it passed through. Moving the task to another workflow does not remove that history. So a workflow with such a stage cannot be deleted; archive it instead.

Deleting a workflow also deletes, with no warning, every rule that names it by id:

• every inbound rule whose action_params workflow names it.
• every notification rule whose filter workflow names it. The messages those rules sent stop.

Before you delete, find these rules. Both lists need admin:

• inbound_rules_list space_key=OPS, then look for the workflow's id in each rule's action_params workflow. Point each such rule at another workflow with inbound_rules_update, or save its settings so you can recreate it.
• notification_rules_list space_key=OPS, then look for the workflow's id in each rule's filter workflow. Point each such rule at another workflow with notification_rules_update, or save its settings so you can recreate it.

Deleting a workflow also takes its history out of the audit feed. Once it is deleted, none of its audit events can be listed again, not even the workflow.deleted event. If you want that record, list the workflow's events before you delete it and save the output, following next_cursor until the last page:

curl "https://cadence.example.com/api/v1/audit_events?space=OPS&subject_type=Workflow&subject_id=31" \
  -H "Authorization: Bearer smc_your_token_here"

See Audit events § Events about a workflow.

Archive a workflow

Archive a workflow in the web interface: open its settings page, …/workflows/:slug/settings, and click Archive workflow at the end of the General section, then confirm. There is no MCP tool or API route for it. Archiving is refused while any task on the workflow is not archived, with cannot archive a workflow that still has active tasks — archive them or move them to another workflow first. Archive each task, or move it to another workflow with tasks_transfer, first. To bring the workflow back, click Restore workflow in the same place. The team's settings page lists archived workflows under Archived.

An archived workflow is hidden from workflows_list and the web listings, its web settings can no longer be saved (Archived workflows are read-only.), POST /api/v1/spaces/:space_key/tasks refuses it with workflow is archived, and tasks_transfer refuses it as a destination with destination workflow is archived.

Archiving does not stop everything aimed at the workflow, and some of it runs with no person involved:

• tasks_create over MCP still creates a task on it.
• An enabled inbound upsert-task rule that names it still creates tasks on it when events arrive, and an event for a task already on it unarchives that task.
• A task can still be unarchived on it.
• Once a task on it is not archived, its assignment rules start pools on that task and, if auto_advance_enabled is true, its sentinel rules move and hold it, as on any other workflow.
• An enabled scheduled rule whose subject is the workflow still starts its worker when it comes due, and a lost worker at the workflow is still started again (see What moves a task without a person § A scheduled rule starts a worker on a clock).
• workflows_update over MCP still changes it.

Archiving a task does not stop workers starting on it either, so the workflow's archived tasks are not protected:

• An enabled inbound dispatch-worker rule still starts its pool on an archived task when an event names that task or matches its properties. These rules name a task, not the workflow, so they do not show up when you look for rules that name the workflow.
• An enabled scheduled rule whose subject is one of the workflow's tasks still starts its worker on that task when it comes due.
• A worker that was running on a task when you archived it is still started again if it is lost, on the usual conditions (see What moves a task without a person § A pool could not be dispatched).

Neither archiving a task nor archiving the workflow stops a worker that is already running on it.

Renaming a workflow's slug (over MCP, with new_slug) keeps its stages, rules, and tasks attached.

Over the API, PATCH accepts slug, name, synopsis, position, auto_advance_enabled, and default_stage_id — so renaming the workflow's slug is available over the API as well as over MCP and the web interface. Changing the workflow's team is done over MCP or the web interface. Changing its default task type is done over MCP only.

Workflow URLs

A workflow's web address is team-scoped: /spaces/:space_key/teams/:team_slug/workflows/:slug, where :space_key is the space's key (for example OPS). That address opens the workflow's board view, the kanban that draws its stage groups as columns. The workflow's settings, its stages and their rules, its stage groups, and its constraints sit directly under it — for example …/workflows/:slug/settings.

No web address containing /boards/ resolves. The /spaces/:space_key/boards/:slug and /spaces/:space_key/boards/:slug/edit shapes no longer redirect anywhere, so replace any bookmark that uses them with the team-scoped address or the permalink below.

Every workflow also has a permalink that names it by id: /spaces/:space_key/workflows/:id-:slug. Opening it while signed in redirects you to the workflow's team-scoped page. Only the id is read — the slug after it is there for readability, and /spaces/:space_key/workflows/:id works as well — so the permalink keeps working after the workflow's slug is renamed or the workflow is moved to another team. The url in a workflow's or stage's entity reference is this permalink, so to replace a broken bookmark, copy the url from the workflow's ref in workflows_get or workflows_list, or open the workflow from its team in the web interface.

Stage groups

Stage groups are the columns (or lanes) that a workflow's board view draws its stages in. MCP stage_groups_create, stage_groups_update, stage_groups_delete, stage_groups_list; the web interface (with reorder). Every one of these needs admin.

A stage group has a name, an optional description, an accent, and a position that is unique within the workflow.

Stages

MCP stages_create, stages_update, stages_delete, stages_archive, stages_list; the web interface. Listing needs read; creating, updating, deleting, and archiving need admin.

A stage belongs to a stage group on its workflow, and has:

In the web interface, a stage's form groups sort_key, sort_direction, recency_days, and card_limit under a Board view section, labelled Display order, Direction, Recency window, and Card limit. The stage's settings panel has a Board view section too. There, the direction appears in brackets after Display order, Recency window appears only when one is set, and Card limit shows the limit in effect. They change only how the stage's column is drawn, never which tasks the stage holds.

accepted_task_type_ids is enforced when a task is created on the stage and when a task transitions into it without force. A forced transition, which needs admin, lands a task of any type, and tasks_transfer does not check the type at all, so a task of a type the stage does not accept can still be there.

reentry_limit holds a task that keeps returning to the stage, on any workflow. abandoned_work_detection holds a task only through the sentinel sweep, so only on a workflow with auto_advance_enabled in a space that is not archived. It looks at the checks the stage's create check rules expect, not at require checks, and holds the task only when a lease of a pool named by an assignment rule at the stage that applies to the task has run since the task entered the stage, all such leases have ended and the newest more than 3 minutes ago, the task has no unresolved dependency that blocks at its current stage, and one of those expected checks is still missing or pending. The full conditions for both are in What moves a task without a person § A blocking hold waits for a person to clear it.

card_limit bounds only what a column in the board view draws, never what the stage holds. A column that hits its limit shows the first cards by its sort_key and sort_direction, and the column header still reports the stage's true total — the number of tasks in the stage that are not archived, within the recency window and the board view's active parent filter, not the smaller number drawn. A truncated stage shows a footer reading Showing <drawn> of <total> with a Show all <total> link. Following it reloads the whole stage-group column uncapped, every stage in it, carrying the board view's active parent filter (the column endpoint renders every task in scope when its request carries ?full=1). The recency window and the card limit compose: the window trims by age first in the stage's column, then the limit caps how many of the surviving tasks are drawn.

To reorder the cards within a stage that sorts by position, the web interface posts a new order to POST /spaces/:space_key/teams/:team_slug/workflows/:slug/board/stages/:id/reorder_tasks.

A stage that still has any task on it, archived or not, cannot be deleted or archived. Deleting it is refused with stage has tasks — move or archive them first, and archiving it with stage has tasks — move them first. Archiving a task does not take it off the stage, so move the task to another stage with tasks_transition, which works on an archived task too. A stage with visit history cannot be deleted at all; deleting it is refused with stage has visit history — archive it instead.

Task types

A task type labels what kind of work a task is. PATCH /api/v1/spaces/:space_key/task_types/:slug; MCP task_types_list, task_types_create, task_types_update, task_types_delete; the web interface. Over the API, task types are update-only. Listing needs read; creating, updating, and deleting need admin.

A task type has a slug, a name, a glyph, a hue (0–359), a position, and a default flag. At most one type per space is the default. Deleting a type is refused while any task, rule, workflow default, stage, or constraint still references it, naming what to detach first.