The template lifecycle

A template lives two lives at once: a draft you keep changing, and published revisions that never change and that workflows use. Keeping them apart is what lets you improve a template on Tuesday without breaking the catalogue that Monday’s workflow prints. This page follows a template from its first draft to production and beyond.

draft ──(sample sets, exact preview, readiness)──► publish ──► revision 1 ──► workflows pin revision 1
  ▲                                                              │
  └──────────────── keep editing the draft ──────────────────────┘──► publish ──► revision 2 ──► review, move pins

The draft

Every template has one editable draft. Each change — in the editor, through element tools, or by replacing the whole document — creates a new draft revision with its ETag (dd-draft-r7-…). Every write must send the ETag it read (If-Match, or if_match in MCP): if someone else changed the draft in between, the write is refused with 412, and you read again instead of overwriting their work. Writes also carry an idempotency key, so a retried request is applied once.

In the editor, the draft is what you edit; Save writes it. Leaving the editor with unsaved changes loses them — save before you navigate away.

Sample sets: realistic data inside the template

A sample set is a named set of values stored in the template — the same shape as the data a workflow sends. Sample sets are how a template is tested, and they travel with it: previews use them, readiness checks them, and whoever opens the template sees what it was designed for.

POST /api/v1/design-templates/{tpl_id}/draft/sample-sets
{ "name": "Longest title, sold out", "values": { "title": "…", "stock": 0 } }

MCP: edit_design_template_sample_set (add, set_values). Write sample sets for the longest and shortest values, every branch of every condition, every market — see Fields and data.

In the editor, sample sets are chosen and edited in the Fields panel (list items as JSON); Reset values restores them.

Exact preview

The exact preview renders a sample set with the production engine — the same that prints the PDF — and returns the page images with a short layout report and readability checks: texts that did not fit, lists that overflowed, images that failed. It costs nothing and calls no AI.

GET /api/v1/design-templates/{tpl_id}/draft/sample-sets/{sample_set_id}/exact-preview?max_page_dimension=1200

MCP: preview_design_template_sample_set. Look at every page of every sample set — a template is judged by its pages.

In the editor, Preview & readiness on the right shows the Live canvas (instant, approximate) or the Exact preview (Rasterized from the runtime PDF) for the chosen Sample set, with the coverage of the fields and the contract changes since the last publication.

Publish readiness

Before publishing, the readiness check runs every blocking rule the server applies:

GET /api/v1/design-templates/{tpl_id}/draft/publish-readiness

It returns can_publish, the checks with their severity and a suggested action, and the draft ETag to publish with. Blocking checks — a sample set that does not render, an invalid document — stop the publication; it also reports the required fields that no sample set exercises. Warnings (a text cut in one sample, for instance) do not block, but read them.

Publishing: an immutable revision

POST /api/v1/design-templates/{tpl_id}/draft/publish        (If-Match: the draft ETag)

MCP: publish_design_template_draft. Publishing freezes the draft as revision 1, 2, 3… — its content and its contract (the fields, their types, required flags and defaults, the item keys of every list) never change again. The draft stays editable for the next revision.

In the editor, Publish opens Publish readiness with the checks and the Input contract — First publication — the initial contract will be frozen, or the changes against the current published version.

Changing a template that workflows use

• Render Document Template nodes keep the revision they were built with. A new revision changes nothing until someone moves the pin.
• To see what changed for a workflow, review it: GET /api/v1/workflows/{wf_id}/template-revisions (MCP get_workflow_template_revisions) lists each template node’s saved and latest revision, the changed fields and whether the change is compatible.
• To move a compatible node to the new revision, upgrade it: POST /api/v1/workflows/{wf_id}/template-revisions/upgrade (MCP upgrade_workflow_template_revision). Nothing else in the workflow changes.
• template_version_policy: "latest_compatible" on the node lets new runs use a newer revision automatically when the change is compatible — same fields and types, same pages, lists that still fit — and falls back to the pinned one otherwise.
• Generate PDF and Multi-page PDF without template_revision render the draft at every run: set the revision before relying on them.

A change is compatible when the data the workflow sends still fits: restyling, moving and resizing are compatible; removing or retyping a field, adding a required one, or changing the pages is not.

Duplicate, archive, return to draft

You want	Do
A new template starting from this one	POST /api/v1/design-templates/{tpl_id}/duplicate (a revision or the draft)
To start the next revision from an older one	Read GET …/versions/{revision}/content and put it as the draft
To take a template out of selection while it is reworked	revert-to-draft (MCP change_design_template_lifecycle)
To retire a template	archive — it disappears from selection and can no longer be edited

Workflows pinned to a revision keep rendering it after the template is returned to draft or archived.

Sharing a template

A template can be shared with other workspaces as a link to a published revision. Opening the link shows a preview; importing it creates an independent copy in the receiving workspace — later changes on either side do not reach the other. To pass on a new revision, share it again. A workflow shared with its templates follows the same rule.

• The link can require sign-in and limit the number of imports; it can be revoked.
• Images stored in Madoo travel with the template; images on external URLs must be imported into storage first.
• Fonts: built-in fonts are everywhere. A private font uploaded to your workspace travels only if you include it and declare that you have the right to share it with the link’s recipients; the receiver’s workspace then gets the same font file. Otherwise the receiver must use their own copy of the font or choose another.

In the editor, Share template creates a link for the current published revision (Share published revision), with Require sign-in and Limit imports, and lists the Active links with Copy share link and Revoke share link.

Checklist before production

• Sample sets cover the longest and shortest values, every branch and every market.
• Every page of every sample set has been looked at in the exact preview.
• Readiness shows can_publish: true and no warning you did not decide to accept.
• Every workflow node that uses the template has a fixed revision.
• Before a new revision, the workflows that use the template have been reviewed.