Stage rules

Rules attached to a stage decide what happens when a task enters it, and what may move it on. There are five rule types, plus workflow-level limits on how many tasks a set of stages may hold. Every rule and constraint on this page needs admin to list or change. See Authentication.

For an honest account of which of these advance a task with no person in the loop, and which still need one, read What moves a task without a person.

How a rule's scope is chosen

The five rule types share a scope with six axes, from least to most specific: space, workflow, stage, task type, tag, and afk. The last, afk, is the task's autonomous (unattended) flag (see Tasks): a rule pinned to afk: true matches only autonomous tasks, one pinned to afk: false only attended tasks, and one that leaves it unset matches either. What makes a rule more specific is the most-specific axis it pins, not how many axes it pins: a rule pinned by task type outranks one pinned only by space, workflow, and stage together.

For a given subject on a given task, the most specific matching rule wins — except that rules pinned by tag are additive: a task carrying several tags can match several tag-scoped rules at once. What counts as the "subject" differs per type and is noted below. Rules with different subjects always apply together.

How a rule is attached to a stage

Every rule belongs to one stage. How you name that stage when you create the rule depends on the rule type:

• Check, resolution, and property rules take the stage's numeric stage_id, which is required. Get it from stages_list — it needs the space_key and the workflow's workflow_slug, and its response lists each stage on the workflow with its id. A stage_id that is not on one of your workflows is refused with unknown stage_id.
• Assignment and sentinel rules take the workflow and stage by name — workflow (the workflow's slug) and stage (the stage's name) — or by id, with workflow_id and stage_id. Omitting the workflow is refused with workflow or workflow_id required, an unknown workflow slug with unknown workflow slug, and an unknown id with unknown workflow_id; omitting the stage is refused with stage or stage_id required. An unknown stage name is refused by an assignment rule with unknown stage name, and by a sentinel rule with unknown stage '<name>' — the name you gave, quoted back to you. A sentinel rule whose action is transition also names the stage to move the task to, with target_stage (a stage name) or target_stage_id.

A WIP constraint is scoped to a workflow rather than a single stage; it names the stages it counts with stage_ids (see WIP constraints).

Over the web interface you attach a rule from the stage you are already viewing, so you do not pass an id.

Assignment rules

An assignment rule routes a lease to a pool when a task enters the stage. MCP assignment_rules_create, assignment_rules_update, assignment_rules_delete, assignment_rules_list; the web interface. No /api/v1 route.

Fields:

• pool_id — the pool to lease the task to. Required. The subject is the pool, so rules for different pools are additive: a stage can be staffed by several pools.
• target — self (the default) leases the entering task; parent leases its parent instead.
• parent_task_type — an optional condition that only applies to parent rules: the rule fires only when the parent is of that type.

An assignment rule you create fires when a task enters the stage. A parent rule whose task has no parent is skipped, not an error.

Check rules

A check rule ties a check to the stage. MCP check_rules_create, check_rules_update, check_rules_delete, check_rules_list; GET/POST /api/v1/spaces/:space_key/check_rules, PATCH/DELETE .../check_rules/:id; the web interface.

The effect is one of:

• create — a pending check result is materialised on the task when it enters the stage. Re-entering the stage resets an existing result back to pending.
• require — the task cannot enter the stage until the check has passed.

An enabled flag (on by default) lets you keep a rule without it firing. The subject is the check, so different checks are additive.

When a require rule blocks entry, the move is refused with requires check <code> to be passed (currently <state>), where the state is missing, pending, or failed. Forcing the transition (see Tasks, admin) bypasses a require gate, but create rules still fire, since a forced move is still stage entry.

Sentinel rules

A sentinel rule can move a task on its own once the checks at its stage reach a state. MCP sentinel_rules_create, sentinel_rules_update, sentinel_rules_delete, sentinel_rules_list; the web interface. No /api/v1 route.

Fields:

• predicate — the condition over the stage's create checks: all_passed (every such check has passed), any_failed (all are resolved and at least one failed), or none_required (the stage has no such checks). The subject is the predicate.
• action — transition moves the task to target_stage; hold sets a hold with hold_reason. Defaults to transition.
• parent_state — an optional condition on whether the task has a parent: any (the default), empty, or present.

A sentinel rule only runs on a workflow with auto_advance_enabled set, and only for a task with no blocking hold whose stage work has settled: every lease of the pools named by the stage's assignment rules that apply to the task, created since the task entered the stage, has ended. Leases of other pools, such as one started by a scheduled rule or an assignment to a pool, do not hold it back. Exactly what it does and does not guarantee — and where it will wait forever for a check a person must set — is spelled out in What moves a task without a person.

Resolution rules

A resolution rule sets or clears a task's resolved and completed state when it enters the stage. MCP resolution_rules_create, resolution_rules_update, resolution_rules_delete, resolution_rules_list; the web interface. No /api/v1 route.

It is attached to its stage by stage_id (see How a rule is attached to a stage). The effect is one of resolve, unresolve, complete, or uncomplete — the subject is the effect. resolve/unresolve set and clear the resolved mark; complete/uncomplete set and clear the completed mark; the two pairs are independent. An optional parent_state (any, empty, present) conditions the rule on whether the task has a parent.

Property rules

A property rule requires a named property be set before a task may enter the stage. MCP property_rules_create, property_rules_update, property_rules_delete, property_rules_list; the web interface. No /api/v1 route.

Besides the stage_id that attaches it to its stage (see How a rule is attached to a stage), its one field is property_key — the property that must be set. The subject is the key, so different keys are additive. When the property is not set, the move is refused with requires property <key> to be set (currently <state>), where the state is missing or blank.

WIP constraints

A constraint caps how many tasks a set of stages on a workflow may hold at once. MCP constraints_create, constraints_update, constraints_delete, constraints_list; the web interface. No /api/v1 route. Constraints are workflow-scoped and do not use the six scope axes above.

Fields:

• name — the constraint's name, used in its refusal message.
• limit — the maximum number of tasks, greater than zero.
• stage_ids — one or more stages on the workflow whose tasks are counted together.
• task_type — an optional filter; without it, all types count.
• tags — an optional filter; a task counts if it carries any of these tags.
• per_parent — when set, the limit applies per parent task rather than across the workflow.

A constraint only blocks a task entering the counted stages from outside the set — moving between two counted stages never blocks. At the limit, the move is refused with constraint <name> is at its limit of <limit> (with a per-parent suffix when per_parent is set). This block is temporary: it clears as tasks leave. Forcing a transition (admin) bypasses every constraint.