Workflows

A workflow is the set of statuses a document type moves through and the rules for moving between them. An organisation defines it once per document type, and the platform checks every status change against it: who may make the move, whether it publishes, and whether an AI step runs on the way.

A workflow is a list of statuses plus a list of transitions. One transition looks like this:

{
  "from": "ready",
  "to": "usable",
  "title": "Publish",
  "requiredRoles": ["publisher"],
  "bumpsVersion": false
}

A member holding the publisher role sees Publish in the status menu of a document at ready. Taking it moves the document to usable, which publishes it.

Reserved statuses

Four status names mean the same thing in every workflow. Custom statuses cannot take these names.

Status	Read-only	Signed snapshot	Meaning
draft	no	no	Entry status. Required in every workflow.
usable	yes	yes	Published.
withheld	yes	yes	Embargoed or scheduled; signed but held back.
cancelled	yes	no	Withdrawn. Kept, and can be reopened.

Arriving at usable or withheld produces a signed, immutable snapshot of the document, which is what webhooks deliver and what receivers verify. See Signatures.

Custom statuses, such as ready or in-review, can sit anywhere in the workflow. They are always editable and never produce a snapshot. Each status can also carry a title, description, icon and colour for display.

Anatomy of a transition

• from and to: the two statuses. Both must be declared in the same workflow.
• title: the label in the document's status menu. Use a verb, such as Publish or Send back to draft.
• requiredRoles: who may take it, as described under Roles below.
• bumpsVersion: increments the document's version. Required on any transition from a read-only status to an editable one, so that reopening a published document starts a new version.
• ai: optional. Runs an AI operation as part of the transition.
• confirm: optional. Asks the member to confirm before the transition happens, with an optional custom title, text, button label and a destructive style. Useful for cancellation.

The exact shape of a workflow document is in the document reference.

Roles

A transition lists the roles allowed to take it. The roles are the organisation's membership roles, owner, admin, publisher and editor, held in the organisation the document belongs to.

A member may take a transition when they hold any listed role. Matching is literal: a member holding only admin does not satisfy a transition that lists only publisher, so list every role that should qualify. A transition with no roles is open to every member.

Roles decide who may take a transition, not who can see a document. Organisation isolation is a separate, earlier check. See Security.

Which workflow a document follows

A workflow is itself a document. Members with the owner or admin role create and edit workflows in the Workflows view: from blank, from a template, or by importing JSON. Templates include a simple newsroom, an advanced newsroom and a newswire intake flow.

A workflow at usable that is marked Default for this type is the one new documents of that type follow. There is at most one default per document type. A workflow at draft or cancelled is not used for new documents.

A document is bound to its workflow when it is created, and keeps that binding, even if another workflow later becomes the default. The binding points at the live workflow, not a copy, so every transition is checked against the workflow's current definition.

With no default workflow for a type, the platform supplies one:

• Planning items: Draft, Ready and Cancelled, where Ready is usable.
• Every other type: draft, usable (titled Published) and cancelled.

A document whose workflow no longer exists falls back to the draft, usable, cancelled workflow.

Editing a workflow in use

A workflow can be edited at any status, usable included. An edit applies at once to every document bound to it.

• Labels, descriptions, icons and colours can change at any time.
• Adding a status or transition makes it available on every bound document.
• Removing a transition removes that move everywhere. A request for it from a menu opened before the edit is refused.
• Renaming or removing a status is refused while any document sits at it. The editor shows how many documents sit at each status, so move them first.
• Default for this type can be switched at any time. It only affects new documents.

Cancelling a workflow, or moving it back to draft, stops new documents from binding to it. Documents already bound keep following its current definition.

AI-bound transitions

A transition with an ai block runs an AI operation when a member takes it. The document stays at its current status, locked and marked as working, until the operation returns. On success the operation writes its results and the document moves to the transition's to status. On a permanent failure caused by the content, the document moves to the transition's On failure status if one is set; otherwise it stays where it was, with the error visible. See AI integrations and Adding AI to a workflow.

An AI-bound transition whose to is usable or withheld publishes the AI's answer with no person reviewing it. Such a transition is allowed only when the organisation turns on AI publishing without review in its settings, which is off by default:

• Off: a workflow holding such a transition is not saved, and the transition is refused if it runs.
• On: a document published this way carries meta.publishedWithoutReview in its signed snapshot, keeps its AI label on, and the public site discloses it. The mark is cleared when a member next moves the document into usable or withheld; moves by the platform leave it.

Transitions into usable or withheld that run no AI, such as publishing newswires on arrival, are not affected. See Publishing without review.

Recipes

A minimal editorial flow

draft     --(Submit, editor)-->                       ready
ready     --(Publish, publisher)-->                   usable
usable    --(Unpublish, publisher)-->                 cancelled
cancelled --(Reopen, publisher, bumpsVersion)-->      draft

An embargo step

draft    --(Submit, editor)-->      ready
ready    --(Schedule, publisher)--> withheld
withheld --(Release, publisher)-->  usable
withheld --(Pull, publisher)-->     cancelled

Release from withheld to usable needs no bumpsVersion: both statuses are read-only, so the document has not changed in between.

AI translation

Add a custom translated status, an AI operation that translates, and a transition from draft to translated bound to that operation. Adding AI to a workflow walks through it.

Limits

• Every workflow must include draft, and draft can be neither renamed nor removed.
• The document type a workflow applies to is fixed when the workflow is created.
• A status still used by a transition cannot be removed until the transition is removed.
• If a status disappears while documents sit at it, for example because the editor could not load the counts, those documents keep the status name with no way out. They stay there until a status of that name with an outgoing transition is added back.
• A document's workflow binding cannot be changed.
• An AI-bound transition into usable or withheld is refused unless the organisation allows AI publishing without review.

Related pages

• AI integrations
• Document reference
• Webhooks