Document lifecycle

Every governing document moves through the same seven states. The platform enforces the transitions: an illegal move is rejected rather than quietly applied, so the status on screen is always a state the document actually reached by a legitimate route.

The states

draft → in_review → approved → published → effective → under_review
                                                            ↓
                                                        effective

retired is reachable from every state and is terminal.

Status	Means
draft	Being written. Editable. Deletable. Not visible as policy.
in_review	With its reviewers. Content is frozen.
approved	Authorised, but not yet issued. Nobody is bound by it.
published	Issued and visible. People can read it ahead of the date it binds them.
effective	Live. This is the version people are held to.
under_review	Still effective, but its periodic review window is open.
retired	End of life. No path out — a replacement is a new document or version.

Published is not effective

This is the distinction people conflate, and it is the reason the module has both states.

• Published — the version exists, is final, and can be read.
• Effective — it is the version people are actually held to.

A policy can be published weeks ahead of its effective date, so staff can read it before it binds them and the organisation can evidence that it gave notice. Until the effective date arrives, the previous version is still the one in force.

Which transitions are legal

From	Can move to
draft	in_review, retired
in_review	draft (returned), approved, retired
approved	published, draft (pulled before issue), retired
published	effective, retired
effective	under_review, retired
under_review	effective, retired
retired	—

Two of these are worth calling out:

• approved → draft exists so an authorised-but-unissued document can be pulled back. Use it when something is wrong with a document that has been approved but not yet published. It discards the reviewers' recorded decision, so it needs a manager; so does retiring any document that has left draft (an analyst may still retire their own draft).
• published → retired skips effective entirely. That is the emergency revoke path — a document issued in error can be pulled without ever binding anyone.

Driving the lifecycle

On the document's Details tab, the available action follows the status:

Status	Where	Action
draft	Details	Submit for Review
in_review	Approvals	Approve / Return for changes
approved	Details	Publish
published	Details	Mark Effective (Go Live)
effective	—	(the page confirms the document is live)

Returning sends the document to draft rather than killing it, and records the action in the approval history. It is a routing decision, not a verdict.

What each transition now requires

Transition	Refused unless
draft → in_review	the document has a version to review and at least one required reviewer
→ approved	every required reviewer has approved. It cannot be set directly by any route
→ published	the current version is approved and carries a confirmed uploaded file

The publish rule matters more than it looks: publishing launches an attestation campaign across the organisation. Without the rule, an empty draft could be published and everyone would formally confirm they had read a document that did not exist.

The cron does two of these for you

A daily job runs across every organisation and:

• activates scheduled go-live — a published document whose effectiveDate has arrived is moved to effective, along with its current version. This is the half of the lifecycle you do not have to remember. The Mark Effective (Go Live) button covers the other case: going live now.
• flips overdue acknowledgments, and sends reminders — see Attestation.

The job is idempotent: re-running it changes nothing that has already been applied, and no reminder is sent twice.

Versions have their own status

The policy carries a status, and so does each of its versions. They are kept in step deliberately: publishing a version makes it the policy's current version and moves the policy's own status with it. In practice you drive the lifecycle from the document and the version follows.

A version with no confirmed uploaded file cannot be published, on either route. The artefact is the legal record; there is nothing to publish without it, and an upload that was started and abandoned does not count.

Review dates

reviewFrequency — quarterly, semi-annual, annual or biennial — sets when a document comes back round. On approval the platform adds that interval to the approval date, and the dashboard surfaces documents falling due in the next 30 days and any already overdue. All four frequencies schedule a review; a document with no frequency set simply has none scheduled.

When the review window opens, move the document to under_review. It stays effective throughout: people are still bound by it while it is being reviewed. From there it either returns to effective (reviewed, no change needed) or a new version carries the change.

Retirement

Retiring stamps the retirement date and clears the document from active use. There is no way back. A policy that needs to return is a new document, or — more usually — the retirement is the wrong tool and what you want is a new version of the existing one.