WeaveKit Docs
GuidesWorkflow

Admin & guardrails

Admin override, reactivate, definition write-back, and how guardrail policies and the approval queue gate transitions.

Most of the time the normal actions are all you need. The rest of this page is the admin escape hatches and the policy gate in front of a transition.

Admin role

Admin actions require the caller to hold the role admin (the constant WORKFLOW_ADMIN_ROLE). Regular actions don't need it — they go through normal RBAC plus the workitem gate.

Override a running instance

PATCH {prefix}/objects/:name/:id/workflow moves a record to a node, or ends it — even while it's running:

{ "node": "manager" }                  // jump to this node (re-opens its workitems)
{ "state": "canceled" }                // terminate
{ "state": "finished" }                // mark done

Use this to unstick a record whose assignees have left, or to force a state an action can't reach.

Re-activate a finished/canceled instance

POST {prefix}/objects/:name/:id/workflow/reactivate   { "node": "manager" }

Admin-only. Re-opens a terminal instance at a chosen node, on the same pinned revision (the definition hash doesn't change). A node that isn't in that revision fails with workflow.node.unknown.

Read/write the definition

GET {prefix}/objects/:name/workflow/spec
PUT {prefix}/objects/:name/workflow/spec

Admin-only, and the routes need adapters.rest.adminRoles plus a schemaDir (they write the project tree). GET returns the raw workflow.json source plus a content-hash version.

PUT validates the candidate against the registered object and writes it through the shared source transaction (atomic replace + git commit --only). Body is either the raw file or a structured form:

{ "source": "{ \"nodes\": [ … ] }" }
{ "nodes": [ … ], "version": 2 }

Pass expectVersion for optimistic locking — a stale value is rejected (409), so two editors can't silently clobber each other. Changes affect new records; running instances keep their pinned revision. (Same as editing the file and running weave workflow:switch.)

The approval gate

A node can declare "requiresApproval": true. When it (or a guardrail policy) demands approval, the action is routed through the approval queue — the same queue used for tool calls — before it fires:

  • approval pending → 409 workflow.transition.pending
  • the node needs approval but no queue is configured → 409 workflow.approval.unavailable

Guardrail policies run on every transition and self-filter on the action key workflow.transition.<object>.<action>, so a policy only sees the transitions it names. For the queue itself and how to resolve entries, see Approvals and Custom tools & guardrails.

On this page