In one sentence
External documents — regulations, customer specs, supplier docs, industry standards — are stored alongside your internal SOPs as first-class controlled documents, sharing the same approval, version-history, acknowledgment, distribution, and cross-module linking, with the only difference being that the body is a PDF in a viewer instead of editable HTML.
- Same register, same lifecycle. Internal and external documents live in the same
/documentslist, share categories and classes, and move through Draft → Under Review → Approved → Obsolete the same way. The Type pill on each row is the only at-a-glance signal of which kind it is. - The body is a PDF, not HTML. External docs render their uploaded PDF in a viewer; internal docs render their TipTap-edited HTML. Everything around the body — approval chain, distribution list, version snapshots, links from MOCs / NCRs / Audits, Ask-the-Library search — is identical.
- A separate External status tracks the publisher's view. Current, Superseded, Withdrawn — independent of your internal approval status, so you can mark "Acme Aerospace QCS-100 — Superseded by Rev C" even while your controlled copy is still the active version internally.
Where they live
External documents share the unified register at /documents.
- Type filter in the sidebar — All / Internal / External. Clicking External narrows the list and updates the URL to
/documents?kind=external. - Type column on each row, with an Internal or External pill.
- The legacy URL
/documents/externalstill works — it redirects to/documents?kind=externalso existing bookmarks keep working. - Categories and document classes are shared between kinds. Both pull from the same admin tables at Admin → Documents → Categories & Classes; there's no separate "external category" anymore.
Creating an external document
Documents → New → External, or Documents → External → New, or /documents/external/new directly. Admin-only.
The form takes:
- Title and a Ref Number auto-generated as EXT-001, EXT-002, etc. The number is locked once the doc exists.
- Issuing Body (e.g. a customer, a regulator, or an industry body), Standard Number (e.g. QCS-100 Rev B), Clause Reference, Edition / Version.
- Category (shared with internal docs) and External Status (Current / Superseded / Withdrawn).
- Owner — defaults to you if blank.
- Effective Date, Next Review Date, Review Frequency.
- Source URL — link to the authoritative source (registrar's site, customer portal).
- PDF Upload — the file that gets rendered in the viewer.
- Notes — free-text "what is this doc" context, kept on the first version row.
- Linked Supplier or Linked Client — pick at most one. The pickers are shown together; selecting one clears the other (the schema enforces mutual exclusivity).
On save, the document is direct-published as version 1.0 — first registration doesn't wait on an approval chain, since there's nothing to compare against and a new external entry typically just records what already exists.
Editing and replacing the file
Edit on the detail page, or /documents/external/[id]/edit. The same form. Two paths from there depending on whether the file changed and how the org's auto-publish toggle is set.
What happens when you save the edit, depending on whether you uploaded a new file and whether auto-publish is on.
The auto-publish toggle lives at Admin → Document Settings → Auto-publish external document file replacements. Default is off, which means external file replacements get the same audit-grade approval treatment your internal documents get — the legacy "swap and go" behavior is opt-in.
For any audit or regulated context, the default — auto-publish off — is the safe one. It enforces that when a controlling external document is reissued — a customer revising their quality specification, a regulator publishing updated guidance — the update gets the same review-and-approve traceability your internal SOP changes get. Only flip auto-publish on for low-stakes external libraries where the file genuinely just needs to be replaced.
The revision banner
Internal documents flag what changed in a revision with margin revision markers — but those need HTML headings to anchor to, and an external document's body is an opaque PDF. So a revised external document announces the change with a revision banner across the top of its detail page instead:
Revised to Rev 2.0 · approved 12 Jul 2026 · supersedes Rev 1.0 What changed: Adopted the 2024 amendment; clause 7.3 retitled.
The banner is assembled from the version snapshot: the current revision, the date it was approved, the revision it supersedes, and the approver's change notes (the What changed line, shown only when notes were written). It also links through to the full version history. The banner appears only once the document has actually been revised — a first-registered external doc (version 1.0, nothing to supersede) doesn't show one.
This gives a reader opening a reissued customer spec or updated standard the same at-a-glance "what's new in this revision?" that markers give on an internal SOP, without needing to diff a PDF.
Status: internal vs external
Two status fields, kept distinct:
| Field | Tracks | Values |
|---|---|---|
| Document status | Your internal lifecycle | Draft, Under Review, Approved, Obsolete |
| External status | The publisher's view | Current, Superseded, Withdrawn |
Both surface as badges on the detail page. So a single external entry can be Approved + Current (the typical case), Approved + Superseded (the publisher has issued a newer edition you haven't yet adopted), or Obsolete + Withdrawn (you retired the entry because the publisher pulled the document).
Supplier, client, and product linking
An external document can carry three optional cross-module links — set on the create / edit form and shown in the document's sidebar.
Supplier or client (one only). Pick at most one of the two; they're mutually exclusive at the schema level. Use this for "customer X's quality clauses" (link to the client) or "supplier Y's certification" (link to the supplier) so the document follows its owner across the system. The supplier or client's detail page surfaces a Documents tab listing both internal and external docs tied to it.
Products (any number). Many-to-many — an external standard can govern several parts in your catalog, and a single part can cite several external standards. Linked products appear in the document's sidebar with an unlink control; the document appears on each product's Documents tab and Overview card. Linking is locked while the document is in Obsolete state.
The same linking surface is available on internal documents — see Documents.
PDF search via Ask the Library
When you upload (or replace) a PDF, the file gets text-extracted page-by-page and pushed through the embedding + full-text-search pipeline. That means:
- External documents appear in Ask the Library alongside internal docs. Question-and-answer cites the external doc with a page number.
- Replacing the file re-runs ingestion; prior section embeddings for that document are wiped and replaced, so search results stay consistent with the latest file.
- Metadata-only registrations (no file uploaded, just a source URL) are skipped — there's nothing to ingest.
See AI in documents for how Ask the Library uses the index.
Detail view
External documents render through the same unified detail page as internal documents. The body region shows the PDF in an in-app viewer. The sidebar carries the same panels: approval, version history, links, references, distribution, access. All actions you do on an internal doc — submit for approval, distribute, link to an MOC, archive — are available here too.
Reviewing external documents
The Next Review Date field is the same as on internal documents and feeds the same overdue / due-soon badges. Use it as a reminder schedule — "check the registrar's site quarterly for an updated edition" — not a deadline gate. The review work is still your team checking with the issuing body; QFormance only flags the date.
Admin
| Page | What you configure |
|---|---|
| Admin → Documents → Categories & Classes | Categories and classes (shared between internal and external) |
| Admin → Document Settings → Auto-publish external document file replacements | Off (default): file replacements enter draft and approval. On: legacy direct-publish behavior |
| Admin → Documents → Approval Routing | The same routing rules drive approver selection for both kinds — facility / class / category → reviewer + approver |
If you delete an external document
External documents have a Delete button on the detail page, gated on the Discard any draft permission (documents.discard_any, Admin by default and grantable to any role or individual). Deleting soft-deletes the whole record to Trash for 90 days, where an admin with the Manage trash permission can restore it — metadata, version history, supplier/client linkage, and cross-module references all come back exactly as they were. An external document can be deleted at any status — unlike an approved internal document, which can't be deleted once approved (you retire it instead).
To keep an external document on file but flag it as no longer in force, retire it rather than deleting: set its internal status to Obsolete, or move its External status to Superseded / Withdrawn. A retired doc stays searchable with its full history intact.
See Soft-delete — how it works for the broader pattern.
Related
- Documents — the controlled-document register and lifecycle
- Document approvals & versions — how the approval chain and version history work
- Revision markers — the margin markers internal docs get, and the banner external docs get instead
- Document training & acknowledgements — distribution and acknowledgement
- AI in documents — Ask the Library and PDF search
- Suppliers
- Clients
- Compliance mapping