Documents

What. Controlled documents (policies, procedures, work instructions, forms) with versioned files, an approval chain, publish + acknowledge. Where. /documents

Lifecycle at a glance

┌──────┐  upload  ┌──────┐  Submit   ┌────────┐  Approve   ┌──────────┐  Publish   ┌───────────┐
│ New  │ ───────▶ │ Draft│ ────────▶ │ Review │ ─────────▶ │ Approved │ ─────────▶ │ Published │
└──────┘  file   └──────┘ chain mat. └────────┘ each step  └──────────┘ owner sign └───────────┘
                                          │ Reject
                                          ▼
                                       (back to Draft)

A Document has metadata (title, code, type, owner, retention). A Document Version carries the actual file blob, the status, the approvals, and the publish timestamp. Only one version is is_current_published at a time; previous published versions become obsolete.

Create a document

1. Side nav → Documents → New Document.
2. Fill Title, Document Code, Doc Type (policy, procedure, work-instruction, form…).
3. Optional: pick the owning Department. Without one, no approval chain resolves at submit time and submission will fail.
4. Click Save.

You're redirected to the document detail page. Status shows Draft, and you'll see "No versions yet" with an Upload first version button.

Upload a version

1. Click Edit in the app bar (or Upload first version).
2. The editor opens. Click Upload File (PDF, DOCX, etc.).
3. Optional: fill Summary and Change Notes.
4. Click Save.

Now the Versions tab shows v1.0 with status Draft and a Download link. The status badge at the top shows Draft.

Submit for review

1. Click Submit for Review.
2. Confirm in the dialog.
3. Behind the scenes the system:
   • Resolves the applicable approval chain for this doc. Resolution order: chain assigned to this doc's department → chain assigned to this doc_type → if neither, throws "No approval chain assigned…"
   • Materializes the chain into approvals rows (one per step) for this version, with decision='pending'.
   • Flips the version status to review.
4. The status badge updates to In Review. An Approvals tab appears.

No chain? If submission fails with "No approval chain assigned…", an admin needs to create a chain at /approval-chains and assign it to either the document's department or its doc type. See Approval Chains.

Approve / reject

If you're a current step's approver:

1. Open the document. The status row shows Approve and Reject buttons.
2. Click Approve.
3. A dialog asks for an optional comment. Click Approved.
4. The approval row updates with decision='approved', your user id, and timestamp.
5. When all approval steps are approved, the version auto-flips to Approved.

If you reject, a comment is required. The doc stays in review until the author re-submits a new version.

Publish

Once status is Approved:

1. Click Publish in the status row.
2. Confirm in the dialog.
3. Version status flips to Published, published_at and published_by are set, documents.current_version_id updates, and any prior published version becomes obsolete.
4. The Acknowledgements tab appears so users can sign that they have read the new version (if doc requires acknowledgement).

What every tab does

• Versions - every version with status, file size, downloader, change notes. The current published version is highlighted.
• Approvals - only present when a version is in review or approved. Renders the approval stepper with each step's status, approver, comment, and decided-at timestamp. If you're a pending approver, the inline Approve/Reject buttons appear here.
• Acknowledgements - only present when a version is published.

Test it

• Create a new document with a code and assign it to a department that has an approval chain.
• Click Upload first version → upload a small PDF → Save. v1.0 shows with Draft status.
• Click Submit for Review. Status flips to In Review and the Approvals tab shows the materialized chain steps.
• Sign in as a step approver. The Approve / Reject buttons appear at the top of the page.
• Approve with a comment. The approval row records your decision and decided-at.
• After the last step approves, status auto-flips to Approved and a Publish button appears.
• Click Publish. Status becomes Published and the doc shows the new current version.
• Reload the detail page from a different browser tab - status, tabs, and decision history match within ~2s of any DB change (realtime).
• Pasting the doc URL while signed into a different org rejects with "Wrong organization".