Document concepts

Versions and publishing

Every document has at most one draft and one live published version at a time.

A new document starts with an empty draft, version 1.0.
Each time you save the draft, you add a short change note ("What changed"), and the draft moves up a minor version: 1.1, 1.2, and so on.
Publishing makes the draft the version used for new renders, as the next major version (2.0). Before publishing, Root checks that the document has at least one chapter and that every chapter has its content: a static PDF needs its file, and a pdfme template needs a base PDF and a template.
A published version never changes. Editing a published document starts a new draft from it, numbered like the live version (2.0). Its first save makes it 2.1, then 2.2, and so on. The published version stays live until you publish again.
Discarding a draft throws away its changes and leaves the published version live.

The Version history on a document lists the draft and every published version with its change note. The live version is marked Live, and the drawer explains which version renders in production and in sandbox.

📘
Renders keep their version
Each render records the exact version it used. Publishing a new version changes future renders only. PDFs already sent are never re-rendered.

Sandbox and production

A document is shared by your sandbox and production environments; only its renders belong to an environment.

Environment	Version rendered
Production	Always the published version.
Sandbox	The published version, so you see what production would send. For a policy issued against the draft product module definition, the draft is used.

A document with no published version is rendered only for sandbox policies issued against the draft product module definition. Anywhere else, the render is recorded as skipped instead, so the omission is visible on the policy.

Disabling, archiving and duplicating

Disable a document to stop it rendering without archiving it. Renders of a disabled document are recorded as skipped, and the dashboard doesn't offer it when you pick documents for a notification. Documents created on the dashboard start disabled: publish the document, then Enable it.
Archive a document when you no longer need it. Nothing is deleted, but it is no longer rendered and its key becomes free for a new document. To restore an archived document, turn on Include archived in the documents list and select Restore on its row. This works only if no other document has taken its key.
Duplicate a document to start a new one from its content. The copy has a new key and starts as an unpublished, disabled 1.0 draft.

Entity types

A document's entity type sets what the document is about and which data it can use. It is chosen when the document is created and can't be changed later.

Entity type	A document about…
`policy` (default)	A policy, such as a policy schedule.
`application`	An application, before the policy is issued.
`claim`	A claim, such as a claim acknowledgement letter.
`payment`	A payment, such as a receipt.
`payment_method`	A payment method, such as a debit order mandate.
`invoice`	An invoice.
`alteration`	A policy alteration package.
`application_alteration`	An alteration package applied to an application.

Documents created on the dashboard are policy documents. To create a document of another type, set entity_type when you create the document over the API.

Permissions

Documents use the customer notifications permissions.

Permission	Allows
`readCommunications`	Viewing documents, versions and renders, and previewing a document.
`createCommunications`	Creating, publishing and duplicating documents, and discarding a draft.
`editCommunications`	Editing a document's details, enabling it, archiving and restoring.

Designing chapters, saving drafts and previewing happen on the dashboard. Designing chapters, saving a draft and Duplicate document on a document's page need both createCommunications and editCommunications; without editCommunications, the editor opens read-only. Over the API you can create, update, publish, archive, restore and duplicate documents, and read their versions and renders. Because a document is shared by both environments, any change made over the API needs a production API key.