Designing a document

Documents are designed on the dashboard under Workbench › Documents. Select New document, enter a key (for example policy_schedule) and a name. You can also add a description and a product module key, which the list shows and can filter by. The key must be unique among your organisation's documents that are not archived, and can use lowercase letters, numbers and _. A new document starts disabled; enable it once it is published (see Document concepts).

Chapters

A document is made of one or more chapters, rendered in order and joined into one PDF. Each chapter is one of:

Static PDF: a finished PDF, placed into the document exactly as uploaded. Use it for fixed wording such as policy terms.
pdfme template: a base PDF with merge fields positioned over it in the Designer. What you place is what prints. With no PDF to upload, select Start with a blank page to begin on a blank A4 page. In the chapter header, Add blank page adds a page after the current one, and Remove page removes the current page and its fields. Fields on later pages move with their page.

Use Page settings on a chapter to include it in page numbers, let tables flow onto new pages, and set the top and bottom margins for those pages.

📘
Fonts
Documents render in Noto Sans Regular and Noto Sans Bold, the only fonts the Designer offers. Any other font in an imported template is drawn in Noto Sans Regular.

Merge fields

A field's name is a lowercase dot-path into the entity's data, such as policy.policy_number or policyholder.first_name. Number segments index into lists: policy.module.covered_items.0.make. A path with no value prints blank; it never fails the document. Open Field names in the editor to search the available paths.

To mix wording and values on one line, use a multi-variable text field (multiVariableText in the Designer's Type list) and write each value in braces:

Dear {policyholder.first_name}, your cover starts on {policy.start_date|date}.

Add a formatter to any path to shape its value:

|date: a date in a readable format.
|cents-to-rands: an amount in cents, printed in rands.
|currency:GBP:en-GB: an amount in cents, printed in the given currency and locale.
|start-case: third_party_fire printed as Third Party Fire.

Besides the entity's data, every document can use document.key, document.name, document.version and document.policy_sequence, and the page values page.number, page.count, chapter.page.number and chapter.page.count.

Expressions

Anything in braces that is more than a path is an expression, calculated when the document renders:

{fmt.date(dates.add(policy.start_date, 3, 'days'), 'D MMMM YYYY')}
{policy.module.excess ?? 'None'}

Expressions work in multi-variable text, table cells, conditional paragraph wording, and fields with Editable unticked. They support arithmetic, comparisons, a ? b : c and ??, and two sets of helpers:

Helpers	Use
`fmt.*`	Formatting: `zar`, `currency`, `date` and `startCase`. `fmt.date` takes any date format and prints in your organisation's timezone; the `\|date` formatter always prints in UTC.
`dates.*`	Date calculations in your organisation's timezone, such as `add`, `subtract`, `diff`, `startOf`, `endOf`, `addBusinessDays` and `isBefore`.

The canvas shows an expression as typed. Use Preview document to see it calculated. An expression that fails prints blank. In a field with Editable unticked, an expression that can't be parsed, or that fails without reading the entity's data, fmt or dates, prints as typed.

Conditional paragraphs

A conditional paragraph (conditionalParagraph in the Type list) prints different wording depending on the data. Each variant has rules, such as policy.module.cover_type equals comprehensive, and matches when all (or any) of its rules hold. The first variant that matches is printed; if none does, the default paragraph is printed. Leave the default empty to print nothing. Rules can also test page values, for wording that only appears on the first page.

Tables

A table (table in the Type list) either has rows typed in the Designer, whose cells can hold merge fields, or takes its rows from a list in the data. For the second kind, name the table after the list (for example policy.module.covered_items), turn on Rows come from a policy list, and give each column the item field it prints. With Flow tables onto new pages on, a long table continues onto new pages, up to 500 pages and 5,000 rows per chapter. A chapter over either limit doesn't flow, and rows that don't fit its table are cut off.

Previewing and saving

Select Preview document and pick a policy to see the document filled with real data. A preview is not stored or sent. When you're happy, select Save to draft and describe what changed. The draft can then be published.

A chapter's template can also be exported and imported as JSON, to copy a design between documents.