Lifecycle and transitions

What this page is — the tab where a type's states, the buttons that move documents between them, the approval workflows that gate those moves, and the decision rules that pick a workflow by value, are defined.

What it is for — so a document goes through exactly the steps your organisation requires, with approval demanded where it matters and nowhere else.

The problem it solves — documents skip the reviews your organisation requires, or wait on approvals nobody configured.

Route: /org/papers/designer/<type> → Lifecycle · Permission: Create/edit/retire project types and template versions..

Figure 1 — States at the top, the moves between them below, and the approval matrix under that.

---

1. What it is

There is no product-wide list of document states. Each type defines its own, which is why two documents in the same list can show states that do not exist for one another.

A state has three properties:

Property	Example	Notes
Code	internal_review	Must be unique
Label	In Review	What people see
Kind	start, approval, terminal, or none	start is where new documents begin; approval is a gate; terminal ends the road

A transition is one button on the document:

Property	Example
From	draft
Action	submit
Label	Submit for review
To	internal_review
Approval workflow	Legal review — or blank

Four things in the product depend on exact names here, and nothing on the tab tells you:

Name	Effect
States draft, negotiation, returned	The only states in which a document's fields can be edited
Action submit	The only transition that enforces required fields
Kind approval	Where the approval guardrail applies
States executed / active	Where Requires signature refuses an unsigned document

---

2. Why you would use it

• "Approved" becomes a fact. A document reaches approved by a route defined in advance and recorded, not by an email saying so.
• Approval scales with value. Decision rules send a £2m deal to Level-2 finance and a £20k one to the default reviewer — from one lifecycle.
• The family's standard chain is one click away. An Agreement loads draft → internal review → approval → send → negotiation → signature → executed → active → archived.
• You find broken routing before users do. Validate workflow readiness reports gated transitions that cannot actually run.

---

3. How it spreads

Surface	Uses
The document's lifecycle bar	One button per transition from the current state
Approvals inbox	Documents waiting in a gated transition
Behaviour settings	Requires approval (checked at finalize), Requires signature, the approval guardrail
Documents list	State badge and state columns on the board
Required-field and editability rules	The exact names in §1

---

4. Step by step

1. Load default chain for family — replaces states and transitions, with confirmation if any exist.
2. Adjust states: add, rename, reorder with the arrows. The bin removes a state and every transition touching it.
3. Adjust transitions: from, action, label, to, workflow.
4. Apply to many sets one workflow on many transitions: Fill blank, Set on all or Clear all.
5. Validate workflow readiness.
6. Save draft, then Publish.
7. Once published, author Decision rules below the editor, Save rules, and use Test before it bites.

---

5. Field reference

Banners and refusals

Message	Means
Duplicate state codes (red)	Two states share a code
Transitions reference missing states (yellow)	A transition points at a state that does not exist. Renaming a code re-points its transitions automatically
Lifecycle is not valid: …	Publish refused; the problems are listed
No lifecycle actions available (on a document)	The type has no transitions from that state
"this document is waiting on an approval decision (…). Approve, reject or return it from the Approvals Inbox…"	Someone pressed a transition while an approval is open

Validate workflow readiness

Read-only. It checks, from this type's own lifecycle, whether each gated transition will run. Where a fix belongs in Module State Management, it says so — those settings are keyed by organisation and module, not by type, so changing one changes behaviour for every Papers document in the organisation.

Decision rules

Part	Rules
Rule set	One per state: On entering state plus a mandatory default workflow
Condition rows	IF field / operator / value THEN workflow — first match wins, top to bottom
Blank THEN	Falls back to the set's default
Save rules	Validates, then takes effect immediately — no republish
Test before it bites	Dry-runs the saved rules against sample values as JSON; touches no document
Attached to	The type's current published version
On a new publish	Carried forward onto the new version if it has no rules of its own; the old version keeps its copy

A brand-new type shows "Decision rules attach to the published version" until it is published once.

Order of routing

For a transition, the approval workflow is resolved in this order, the last word winning:

Step	Source
1	The transition's own workflow
2	Decision rules for the entered state — first matching row
3	The type's approval guardrail, if the document's guarded value is at or above its threshold

The guardrail runs last on purpose, so no rule can route a high-value document around it. See behaviour settings.

---

6. Worked example

A legal operations lead configures a Master Services Agreement type.

Load default chain for Agreement. They keep it, and set the transition draft → internal_review to action submit — not send_for_review — because they want required fields enforced.

Workflow. internal_review → approval (kind approval) gets Legal review. Apply to many → Fill blank puts the same workflow on two other approval transitions they had forgotten.

Readiness. Validate workflow readiness flags that Legal review has no approver persona that resolves to a user. They fix the workflow before any document tries it.

Publish. Then decision rules on entering approval:

IF	THEN
contract_value > 1,000,000	Level-2 finance
governing_law neq India	International legal
(default)	Legal review

Test before it bites with {"contract_value": 1500000, "governing_law": "UK"} → Level-2 finance (matched rule #1). The UK row never fires for that document because the first match wins, so they move the governing-law row to the top, save, and test again.

---

7. The admin contract

Must be true	Where	What breaks without it
Approval workflows exist and resolve to real approvers	Approval engine	Gated transitions refuse; readiness reports it
The draft's outgoing action is submit	This tab	Required fields are never enforced
Editable states are named draft, negotiation, returned	This tab	Documents are read-only from creation
A transition leads to executed or active	This tab	Requires signature has nothing to enforce against
The type is published before authoring decision rules	Header	The rules panel stays empty

---

8. Downstream

When you…	Then
Publish a lifecycle change	New documents run it. Existing documents keep their version's lifecycle
Save decision rules	They apply at once to documents on the current published version
Publish a new version	Rules carry forward if the new version has none
Delete a state	Its transitions go too

---

9. Don't confuse this with…

Approvals inbox	Where approvers act. This decides when they are asked
Behaviour settings	Whether approval and signature are required. This decides the route
Stages on the documents board	Derived from seal and signature, identical for every type. States are per type
Approval routing (AI)	Recommends a route. This enforces one

---

10. Troubleshooting

Symptom	Cause
An existing document did not get a new step	Lifecycle changes apply to new documents only
A document moved without approval	That transition has no workflow, and no rule matched
A rule never fires	An earlier row matches first, or the rule set's state is never entered
Rules vanished after publishing	The new version had its own rules, so nothing was carried forward
Required fields are not enforced	The action is not submit
A new document is read-only	Its start state is not named draft
Lifecycle is not valid on publish	Read the listed problems — usually a missing state

---

Related

• Behaviour settings
• Approvals inbox
• Type Designer