Skip to content

Documents & the Lifecycle

Audience: everyone who authors, reviews, or releases controlled documents.

A controlled document in LQMS moves through a fixed lifecycle — Draft → In review → Released, and later Revised into a new version or Withdrawn/Revoked (§7b). A version that should not continue at all is discarded (§7a). Every controlled action is recorded; the system never lets you take a step you are not allowed to take, so if a button is missing or greyed out the reason is shown next to it.

0. The two screens, and how they are laid out

Nearly everything in this chapter happens on one of two screens, and it is worth two minutes to know where each screen puts its controls.

The documents view is a folder column beside a list. Above the column stand the four category chips — All, Documents, Records, Templates — and under its Folders heading a Filter documents… box that narrows the tree as you type. The chips are the category filter, and all four are permanently on screen so you can always see which one is active (it is the filled one) and what the alternatives are; there is no hidden state to discover.

The chips sit with the tree deliberately: the tree is what they filter, so the control and its subject stay together. Collapse the column with Folders and, on the list, the chips move up into the head row beside the reopen control rather than disappearing with it — a filtered list is never on screen without the control that filtered it. On a document page, where neither the tree nor the list is showing, they are simply absent.

A document page opens with two header lines and then the document:

  • The first line is where you came from and what you can do. An icon back control, then a breadcrumb — project code, the folders above the document, the document's own id — every step of it navigable. The document's acts cluster at the right of that line as one block (Move…, Language, New draft, and whatever else your role may do here); on a narrow screen or behind a long breadcrumb the whole cluster moves to its own line together, never breaking apart.
  • The second line is the title line, and it carries the document's standing: the id and title on the left, and on the right a state chip that names the version — Released · v2, Draft · v3 — beside a marker if somebody else is editing right now. A version that is superseded, disposed or not yet effective says so in the same place, and a document whose draft was discarded reads Discarded (§7a). There is no separate subtitle line: the facts a reader needs about a version are which state it is in and which number it is, and those are a chip, not a paragraph. At the end of that line, when you hold the standing for one of them, sits a quiet ⋮ — More actions. It holds the rare acts and nothing else: Discard draft (§7a), Revoke (§7b) and Restore document (§7c). They are kept out of the everyday flow deliberately: they are uncommon, they are consequential, and none of them belongs a click away from the buttons you press every day. If you hold none of the three standings on this version, the ⋮ is simply not there.

Below the document body come its cards — Export, References, Trace links, version and draft history, the audit trail — each appearing only when it has something to say and you may see it.

1. Creating a document

New draft is on the documents view. You choose:

  • Scope — which project/QMS the document belongs to. A document lives in exactly one scope and never moves between scopes.
  • Type — SOP, work instruction, record, template, … from the types activated in that scope. The type decides the document's category (the Documents / Records / Templates chips), its ID prefix, and the default review and training rules copied onto the document (see §4).
  • Folder (optional) — where it sits in the scope's folder tree. You can move it later; moving is organizational only and never touches content or versions.
  • Title and the ID designator (an auto-number or a short slug, depending on the type).

The new document starts as v1 in Draft.

Starting from a template

Some records are not written from scratch — they are filled in: an intake checklist, a batch record, a verification protocol. Those start from a released template, and the result is a new record draft with the template's variables substituted and a provenance link back to the exact template version. Variable values are fixed at creation.

There are two ways into the same act, and which one you want depends on where you are standing:

  • From your project (the usual one). With a single project in context, the documents view offers From a template beside New draft. It lists the released templates you can reach — including ones that live in the QMS project rather than yours — and creates the record in the project you are in: there is no "into which project?" question, because you already answered it by being here.
  • From the template. Open the template itself and use Use template. This is the librarian's direction — a quality manager handing a template to a project — and there the target genuinely is the question, so the dialog asks it.

A template becomes a record, so the project needs a record type activated in it. If it has none, the From a template list says so plainly and points at Project setup, where a document type can be activated — rather than letting you find out from an empty type dropdown.

Whichever way you take, the view follows the new record: the category chip switches to the one that contains it and the tree reveals it, so it is never hidden by the filter that led you to the act.

Variables can declare a type. A template author may say what kind of value each variable expects, and the fill-in form then offers the matching control (the template's variable table shows the type, so you can see it before you start):

  • Text — a plain text field, and the default when the template says nothing. Anything you type is taken as written.
  • Date — a date picker. The value is stored as 2026-07-15 (year-month-day) whatever your language displays, so audit dates sort and age correctly later; something that is not a date is refused rather than filed.
  • Number — a numeric field, stored as a plain decimal (12.5). 1'250 and 12,5 are accepted as you write them and normalized; words are refused.

Older templates that declare no type keep working unchanged — every variable in them is text.

2. Editing a draft

The draft editor opens in the visual (WYSIWYG) editor by default — a Word/Confluence-like surface: a toolbar for headings, bold/italic, colour, lists, tables, alignment, links, images, and an insert menu; a mid-line slash menu (type /) for blocks like tables, diagrams, formulas.

  • Checklists — the slash/​list controls include task lists (checkbox items). They are part of the record: a released document shows them as read-only ticked/unticked boxes.
  • Source mode — a toggle switches to a plain-Markdown editor over the same content for people who prefer typing Markdown. Leaving source mode re-imports your text into the visual document.
  • Images and files — paste or upload images (shown inline) and attach any other file (shown in the Attachments section, download-only). See the diagrams chapter for draw.io.
  • In-text document links — type [[ to link to another controlled document by its stable ID; the link survives the target's folder moves and title changes.

A picture in the record is one of the document's own attachments — never one fetched from elsewhere. An image you upload or paste becomes an attachment of this document, and it renders as a picture everywhere the document does: in the editor, in the reading view and in the PDF. An image whose source points outside LQMS — a URL on an intranet or the web — deliberately does not render as a picture anywhere. On screen it shows as a small link chip naming the reference instead; in an exported PDF it appears as its alt text in brackets, with the other things the PDF cannot typeset (§8).

The reason is stability, not security. A released document is an artifact somebody is entitled to rely on, and its bytes are frozen when it is released; a picture served from somebody else's server could change tomorrow, silently, and the released document would then say something different from what was approved. So the rule holds even where LQMS could perfectly well fetch the image: being resolvable is not the same as being stable.

Nothing you wrote is thrown away. The reference stays in the document exactly as you typed it, the chip names it (long addresses keep their beginning and their end, so the file name at the tail stays readable), and the resource remains perfectly usable as a link. If the picture belongs in the record, download it and attach it — that is the one act that makes it part of the document.

The details panel. Beside the text sits everything about the draft rather than in it — the change reason, the addressees and process owner, the workflow roles, the content language. On a wide screen it is a column of its own; on a narrower one it slides in from the right. Either way the Details button in the editor's top bar shows and hides it, and LQMS remembers your choice for next time. Closing it gives the width back to the text. Nothing you need in order to know whether a document is in force lives only there: the state, the version and the effective date are all on the document's own title line (§0, §4).

Saving is optimistic-locked: if someone else saved while you were editing, your save is rejected with a clear message rather than silently overwriting their change. Only the draft (Author side) is editable — reviewers comment, they never edit your text.

2a. The draft history — every save, including the first

While you work, LQMS records a save-point for every explicit save of the draft: the state you committed, who committed it and when. Not every keystroke — only the states somebody chose to save. The Draft history panel (in the editor's drawer, and as a card on the reading view) lists them newest first, lets you open any of them to read exactly what it held, and restore an earlier one. A restore is never a rewind: it lands as a new save naming the point it reproduced, so the history only ever grows.

The list starts at the draft's birth. The oldest entry is the state the draft was born holding, and it says where that state came from — as created, as filled in from the template, as copied from v2, as derived, as imported. That matters most where the draft did not start empty: a record instantiated from a template, a revision that opens as a copy of the released version, or a document that arrived from another system. Before you change anything, that first entry is what the document looked like when it reached you — and it stays one click away for as long as the version exists.

Two limits worth knowing:

  • A first entry holding plain Markdown rather than the visual document (a template fill-in, for instance) can be read but not restored — there is no way back into the visual editor from plain text, so the panel offers reading only.
  • Drafts created before this was introduced keep the history they already have. Theirs starts at the first edit and carries no birth entry; nothing was invented for them after the fact.

The history is kept for the life of the version, including after release — that is what makes it possible to reconstruct how a released document came to be. After release it is read-only: you can read any point, but there is no draft left to restore into.

3. The review round — from both sides

When the draft is ready, Submit for review. Submit freezes the content, the change reason (§5), and the workflow roles for this round.

As an author / submitter:

  • After submit the document is In review and read-only. You can follow the reviewers' comments (see the review-comments chapter).
  • If you need to change something, Withdraw the document (§7) back to Draft, edit, and resubmit.
  • Under four-eyes rules you cannot also approve your own round.

As a reviewer:

  • The document appears in your inbox because you hold one of its Reviewer roles. Open it and record your verdict — Approve or Reject — with an optional comment. Rejecting sends the document back to Draft for the author.
  • Add anchored review comments on the text as you go; unresolved comments can block release (§4).

As a releaser:

  • Once the required approvals are in (the right roles, in the required numbers), Release becomes available. The action tells you exactly what is still missing if it is not yet allowed (e.g. "awaiting 1 approval from Quality Reviewer", "3 unresolved review comments").

4. Release, and what gates it

A release makes the version the controlled, effective version of the document. What must be true first is set per document type in Scope configuration (see training.md §4):

  • Approvals — the required roles have approved, in the required counts.
  • Review comments resolved — if the comment gate is on, every open review comment must be resolved first.
  • Training questionnaire — if the type trains by questionnaire, the version must carry an authored questionnaire.
  • Release mode — Explicit (a releaser clicks Release) or Automatic (the final approval releases the document; still held back by unresolved comments or a missing questionnaire until those clear, then a releaser finishes it).

Effective date. A released version is effective from its release time by default. Releasing now asks you to confirm first, and the confirmation carries one optional field — In force from. Leave it empty and the version takes effect immediately, which is the ordinary case. Give it a date and the version is released now but does not take effect until the start of that day: the previous version stays in force until then, which is what you want for a change people have to be trained on, or one timed to a regulatory deadline.

The date can only be in the future — the calendar offers nothing earlier, and if you type a past date anyway the system refuses the release and says so. A version that is released but not yet in force says that plainly on its own page: the title line carries an In force from ⟨date⟩ marker beside the state chip, with no hovering needed. A version that is in force is quiet about it — hover (or long-press, on a touch screen) its state chip and it tells you In force since ⟨date⟩.

The document detail always shows the currently effective version to readers.

4a. Direct release (records only)

For record types, a scope can set Release flow (records) to Direct (single-person release from draft) (Scope configuration → Review policies, on a record type). Records — meeting notes, verification records, "proof the process ran" documents — need no independent approval (ISO 13485 §4.2.5), so forcing the full review round on them is pure friction. When a type is set this way, an authorised releaser sees a Release button straight on the Draft, beside Submit for review: releasing then makes the draft the released version in one attributed, audited step, skipping submit and approve. You are asked to confirm first — the Release directly dialog says plainly that this skips submit → approve and makes it a single-person, attributed release, and it carries the same optional In force from date as the ordinary release (§4).

This is a permission, not a rule: the standard submit → approve → release flow stays available on a direct-mode type whenever you want the extra ceremony, and it is the only option for prescriptive documents and templates, which always get independent review. The comment-resolution gate still applies, and the release is recorded like any other. Direct release is what makes recurring-obligation records (see Recurring obligations) frictionless end to end.

5. Revising — with a reason

To change a released document, Revise it. This starts a new draft version and asks for:

  • Reason for change (required) — why the change is being made.
  • Impact (optional) — what is affected (other documents, training, downstream records).

The reason and impact are visible throughout review, so the approvals attest them; they freeze at submit like the content and appear on the version in the history. A first version (v1) has no reason — there is nothing it changed.

6. Versions, history, and PDF export

The document detail lists every version with its state, effective date, and change reason. From here you can:

  • Read any version — the default landing is the latest effective version, but superseded and future-effective versions remain readable.
  • Export a PDF — Download PDF is available on Released (and Revoked) versions. See §8.
  • See the source history — documents imported from the previous QMS carry a muted "History from the source system" section under the version history. It lists the legacy version and status changes (who/when, as recorded in the old system) so the document's real age and history are visible — but it is clearly separated from LQMS's own audit trail. LQMS never claims that those legacy acts happened in LQMS; the section is provenance, not LQMS audit.

7. Withdrawing

Withdraw takes a document from In review back to Draft. Any holder of an Author role can do it. Withdrawing voids the round's approvals, cancels the reviewers' tasks, and unlocks the workflow roles for editing; when you resubmit, a fresh review round begins. Use it whenever a round needs to be corrected rather than rejected.

7a. Discarding a draft — and what "discarded" means

Sometimes a document should not continue: it was started by mistake, it duplicates another, or the work it was for went away. Discard draft closes a Draft or In review version as discarded. It sits under More actions (⋮) in the document's title line — not with the everyday acts, because it cannot be undone — and you confirm first.

It is not a deletion, and the dialog says so. LQMS has no trace-free deletion of a controlled document, by design:

  • the document keeps its number — an ID is never reissued and never leaves a hole in the sequence, so nobody can later wonder what PA-SOP-014 was;
  • the version stays in the record as a discarded one, and the full trail — who started it, who closed it, when — remains readable;
  • a discarded version cannot be reopened. Closed is closed — though the document itself can be taken up again, as a NEW version under the same number (§7c).

Who may discard: the version's author, always; plus whoever holds a role that the document type's Discard draft standing grants in this project (Scope configuration → Review policies — see review policies). If the action is absent from the ⋮, that row grants you nothing here.

One word about the record. Screens say discard — it names exactly one thing, while cancel is also how you dismiss a dialog. The stored state has always been called CANCELLED, and it still is: you will meet that word in the raw audit trail on the document page, in exports and in the API. They are the same ending under two names, and the stored one does not change because a label was clarified.

The two endings are not the same thing

A document released at least once governed something. Whatever became of it since — revoked, superseded, or a revision abandoned mid-flight — it keeps its place and its ending is shown as it happened. It must never quietly disappear.

A document never released at all — every version closed without ever taking effect — is a different thing: a beginning somebody abandoned. That difference shows in what HAPPENS to it, not in a different word: the chip on any discarded version reads Discarded either way, because the act's own button says Discard draft and one ending does not need two names. What is different is where the document appears — see the exclusions just below. Nothing is deleted or altered: the version is still a cancelled one in the record, and the whole trail is one click away.

Because a discarded document is nobody's working directory, it is left out of the document tree and out of the document list — both of those show what you might work on or must follow. It is also left out of search: neither the search box nor the reference picker offers one, because an abandoned beginning is not something to cite or to be sent to, and search clutter compounds. (That rule is about the document, not about its state: a released document with a discarded revision draft is still findable everywhere, because that document did take effect once.)

What remains is deliberate: any link to it still opens, so a citation written while it was alive is never broken, and Administration → Discarded documents lists every one in a project with its number, its title and who closed it when — with its own filter box, since that listing is now where these documents are searched. Each row leads straight into the normal document page.

7b. Revoking a released document

Discard draft (§7a) ends a version that never took effect. Revoke ends one that did. Use it when a released document must stop being binding — the process it describes no longer exists, it was superseded by something outside LQMS, or it turned out to be wrong and there is no revision coming.

Revoke sits under More actions (⋮) in the title line of a Released version's page, beside Discard draft and for the same reason — it is rare, it is grave, and it used to sit close enough to the everyday buttons to be reached by accident. You confirm first, and as with discarding, the dialog states what actually happens rather than asking whether you are sure:

  • the document's validity ends — from that moment nobody may work to it;
  • it is not a deletion: the version stays in the record as a revoked one, and the trail keeps both who released it and who revoked it;
  • an audit of the period the document governed still finds it whole — which is the whole reason a QMS revokes instead of deleting;
  • a revoked version cannot be put back in force. If the document is needed again, that is a new release, not an undo.

A revoked version stays readable and still exports to PDF (§6), so the record of what was in force during its period is never lost.

Who may revoke: whoever holds a role that the document type's Revoke standing grants in this project (Scope configuration → Review policies — see review policies). Unlike discarding, being the author is not enough — revocation ends something other people are relying on, so it takes the standing and nothing else. If the action is absent from the ⋮, that row grants you nothing here.

7c. Restoring a discarded document

Sometimes an abandoned beginning turns out to have been needed after all — the project it was for came back, or the duplicate it was taken for was not one. Restore document takes the document up again.

What it does is deliberately narrow, and the dialog says it before you act:

  • the discarded version stays discarded. It is not reopened and it is not edited. Closed is closed, and the trail keeps who closed it and when;
  • a new draft begins under the same number, holding the discarded version's content. No second id is minted — the number was always this document's, and LQMS leaves no holes;
  • the trail shows both acts side by side, so a reader a year later can see that this document was abandoned on one date and taken up again on another. Nothing is quietly re-written.

From there the new draft behaves like any other: edit it, submit it, release it (§3–§5). It carries no "nature of change" note, and does not ask for one — nothing was ever in force to describe a change from.

Restore document sits in the same More actions (⋮) as its two siblings (§0), because it is the same kind of act: uncommon, consequential, and not something to reach by accident. It is also on each row of Administration → Discarded documents, which is where you are most likely to meet the document you want back.

Who may restore: whoever may create documents in this project. That is the deliberate answer — bringing a document back is authoring, not administration, so it takes the standing an author already has rather than a separate governance grant. If neither the ⋮ nor the listing offers Restore, you do not hold that standing here.

8. PDF export and "uncontrolled copy"

Download PDF produces the version as a PDF, rendered by the system (not your browser) so it is identical for everyone and recorded as an EXPORTED audit event (who exported what, when).

Every exported PDF carries, on every page, the band:

UNCONTROLLED COPY — exported \<date> by \<name>

This is a deliberate distribution control (ISO 13485 §4.2.4). The authoritative, controlled copy is always the version in LQMS: the moment a document is printed or saved as a file it is no longer under change control, so the band says so. A superseded, future-effective, or revoked version also states its standing in the header, so an out-of-date copy identifies itself twice. Drafts and in-review versions cannot be exported — they have no controlled identity to stamp.

Some content degrades in the PDF by design (it is the record typeset, not a print designer): Mermaid diagrams appear as a labelled source block, math as its $…$ source, and internal doc: links as plain text. An image referencing something outside LQMS appears as its alt text in brackets, for the reason §2 gives. Draw.io diagrams and the document's own attached images render normally.

Updated 2026-08-03 (feedback round #7, #8 + #9): the template coverage is re-anchored project-first — the project's own "From a template" door leads, the template-side path follows, the view now follows a newly created document, and template variables can declare a type.

Updated 2026-09-22 (v1.0 acceptance round, register rows 97 + 98): §2a added for the draft history and its birth entry — a draft's history now starts at the state it was born holding, labelled by origin; §7a added for cancelling a version and for the Discarded distinction between a document that was valid once and one that never was.

Updated 2026-09-24 (register row 109, his edge retest): the act is named Discard draft on every screen (the stored state is still CANCELLED — §7a says so), and it moved, with Revoke, into More actions (⋮) in the title line — rare and irreversible acts do not belong a click away from the ones you press every day.

Updated 2026-09-24 (register rows 107 + 109 d): §7c added — a discarded document can be restored, as a new draft under the same number, with the discarded version left closed; and §7a now states that discarded documents are out of search as well as out of the tree and the list, while every direct link to one still opens.

Updated 2026-09-24 (register row 108 item 16): the version's state chip reads Discarded whether or not the document was ever released — the ending has one word, the same one the button uses. The two endings are still told apart by what happens to the document (§7a's exclusions), and the stored state is still CANCELLED in the trail, in exports and on the API.

Updated 2026-09-06: §0 added for the rebuilt document header (back + breadcrumb on one line, the state chip carrying the version on the title line) and the category chips beside the folder tree; §2 gains the record-stability rule for images referenced from outside LQMS.