Preview and versions
What this page is — the live preview beside the form, the version history of snapshots beneath it, and the Activity timeline that records who did what.
What it is for — so you see exactly what recipients will see while you are still writing it, and so "what did it say before we changed it?" always has an answer.
The problem it solves — authors discover layout problems after sending, and nobody can show what a document said before it changed.
Route: /org/papers/documents/<document> · Permissions: View this project's documents. to
read; Edit draft documents / data values. to checkpoint and restore.
1. What it is
Three records of the same document, each answering a different question:
| Record | Answers | Kept |
|---|---|---|
| Preview | What will it look like? | Never — always rendered fresh |
| Versions | What did it say at that moment? | Forever — immutable snapshots |
| Activity | Who did what, and when? | Forever — the audit trail |
The preview is generated, not edited. It is rendered on the server from the saved template, the filled fields, numbering and letterhead, and refreshes after every autosave. You cannot type into it.
A version is a snapshot of the document's content at a moment. There are four kinds:
| Kind | Created by |
|---|---|
draft | Checkpoint now, or a restore |
finalized | Finalize |
counterparty_round | A counterparty round being recorded |
amended | An amendment |
| A version | An amendment | |
|---|---|---|
| Applies to | This document | Creates a new linked document |
| Produces | A snapshot of the same document | A successor with its own lifecycle |
| When | Any time, including drafts | After a document is sealed |
2. Why you would use it
- The preview is the ground truth. It is built exactly as the sealed PDF will be, so a blank where a value belongs is caught before a recipient sees it.
- Checkpoints make risky edits safe. Snapshot before rewriting a schedule, and the old wording is one restore away.
- Diffs end arguments. Expanding a version shows content blocks added, removed or modified and each field's old and new value — contract_value: 40000 → 45000.
- Restores are never destructive. A restore is another step forward; the history is never deleted.
- Activity answers "who moved this to approved?" — every audited action, state move with reason, and comment on one timeline.
- Read aloud catches what skimming misses. Clumsy legal prose is far easier to hear than to see.
3. Step by step
Checkpoint — Checkpoint now in Version history, with a note such as "before counterparty round 2".
Compare — expand a version to see its diff against the one before.
Restore — Restore on a version, then confirm. Available only while the document is editable.
Read aloud — the button on the Preview panel.
Find a change — the Activity card; narrow with the chips Edits, Lifecycle, Sharing, Signing, People or Comments, and expand an edit's What changed.
4. Field reference
Preview
| Message or behaviour | Means |
|---|---|
| No preview yet — save the document first | Nothing has been saved, so there is nothing to render. Type into any field |
| Refreshes after autosave | Not on every keystroke |
| Attachments are not shown | The preview renders only the body — open files from the Attachments card |
| A blank where a value belongs | The field is empty, or the template references a code no field defines |
Checkpoint and restore
| Action | Allowed | Refusal |
|---|---|---|
| Checkpoint now | When the type allows versioning — on by default | this document type has versioning disabled — enable 'Allows versioning' on the type to keep a version history |
| Restore | Only in draft, negotiation or returned | document in state "x" cannot be restored to a prior version |
A note of only spaces is saved as no note.
What a restore does: copies that version's field values back into the document, records a
version_restored event, and mints a new draft version noted "restored from vN". Nothing is deleted.
Activity
| Element | Shows |
|---|---|
| Timeline | Newest first, grouped by day |
| Edit entries | What changed — a before → after table per field, using the field's label |
| State moves | The transition and its reason |
| Comments | Internal comments and counterparty portal comments, marked by kind |
| Resolve | Marks a comment settled |
Edits made before value-level recording started say so, instead of showing a blank comparison.
AI result freshness
AI results in the workspace show cached when computed on the current content, and a yellow computed on older version chip when the document has changed since. Re-run those.
5. Worked example
A legal counsel prepares a supply agreement for the counterparty's second round.
Before sending, they press Checkpoint now with the note "sent to Northwind — round 2". The history now
reads v3 (draft, their note).
Northwind returns redlines. Counsel accepts four suggestions and edits the liability cap from 12 to 18
months. On review, the commercial lead says the 18 months was never agreed. Counsel expands v4 in Version
history: the diff shows liability_cap_months: 12 → 18 and one modified block in clause 11.
They press Restore on v3. The form returns to 12 months; the history now reads v5 (draft,
restored from v3), and v4 is still there if anyone needs it.
A week later the CFO asks who moved the agreement to approved. Activity → Lifecycle shows the
transition by the head of procurement, Thursday 14:20, reason "within delegated authority".
6. The admin contract
| Must be true | Where | What breaks without it |
|---|---|---|
| Allows versioning is on — the default | Behaviour settings | Checkpoints are refused |
| The template references real field codes | Template builder | The preview shows blanks that reach the recipient |
| A letterhead is configured | Branding assets | The preview and PDF render without branding |
| The role holds Edit draft documents / data values. | Role editor | No Checkpoint or Restore |
| The PDF engine is installed on the server | Operations | Finalize cannot seal a PDF |
7. Downstream
| When… | Then |
|---|---|
| A version is restored | Field values revert; AI results show computed on older version |
| A document is finalized | A finalized version is minted, and restores stop — the document is no longer editable |
| Versioning is turned off on the type | Existing versions remain; new checkpoints are refused |
8. Don't confuse this with…
| Version diff | The AI capability that explains changes in meaning. The diff here is literal |
| Comparing versions | The counterparty-round view of the same history |
| Finalize | Produces the sealed PDF. The preview is a live render |
| Amend, renew, supersede | New documents, not new versions |
9. Troubleshooting
| Symptom | Cause |
|---|---|
| No preview yet | The document has never been saved |
| A blank in the preview | An empty field, or a template token naming no field |
| …versioning disabled… | Allows versioning is off on the type |
| …cannot be restored to a prior version | The document is not in draft, negotiation or returned |
| The preview looks stale | It refreshes after autosave — wait for saved |
| An uploaded file is not in the preview | Attachments are never rendered into the body |
| What changed shows no values | The edit predates value-level recording |