Document Templates

How Templates Work

A document template turns a record into a letter, form or report. It has two halves that are configured separately.

Where to find it

Architect Panel → Layout & Pages:

• Document Templates — the templates themselves
• Document Designer — page size, margins, header and footer

Architect Panel → Data:

• Documents — the generated output

The template

Names its datastore, holds the content, names a design, and says what output format it produces. It can also point at a custom page where the document needs to be generated rather than composed.

The design

Everything about the page itself: default font, size and colour, background colour and image, orientation, page width and height, margins on all four sides, and the header and footer HTML with the footer’s vertical position.

Designs are separate from templates deliberately — one design serves every letter you produce, so your letterhead is defined once.

Build the design first

Templates inherit it. Getting margins, header and footer right once, before writing any content, saves adjusting every template afterwards.

Content is merged with the record

The template refers to fields, and generating replaces them with that record’s values. So one template produces a letter for every case, every order, every customer.

Empty fields are the thing to plan for

A letter reading "Dear ," or containing a blank line where an address should be is the characteristic template failure. Decide what each merged field does when it is empty before you send anything to a customer.

Output format matters

A document intended to be printed, signed or archived should be a fixed format. One intended to be edited afterwards should not. Choose by what happens to the document rather than by habit.

Templates are business documents

Which means somebody other than an administrator owns the wording — legal, compliance, the service manager. Changing the words in a template is changing what your organisation says.

Have a review before publishing a new one, and keep a note of who approved it.

Generated documents are records

They are stored, and they are evidence of what you sent. That means retention, permissions and versioning apply to them exactly as to anything else.

Worked example

An organisation built one design carrying its letterhead, margins and footer, then six templates using it. When the registered office address changed, the footer was updated once and every template followed.

Recommendations

• Build the design first, then the templates.
• Decide what empty fields do before sending anything.
• Have the wording approved by whoever owns it.
• Treat generated documents as records with retention.

Building a Template

A template is content with fields merged into it. Most of the work is in the edge cases.

Where to find it

Architect Panel → Layout & Pages:

• Document Templates — the templates themselves
• Document Designer — page size, margins, header and footer

Start from a real document

The letter you send today, in whatever form it exists. Turning an existing document into a template is much faster than writing one, and it starts from wording somebody has already approved.

Identify the merged parts

Work through the document marking everything that varies: the name, the reference, the dates, the amounts, the specific details. Everything else is fixed text.

Anything that varies and is not merged is something somebody will have to edit by hand every time, which defeats the point.

Plan for every merged field being empty

The most important habit. For each one, decide:

• Is it always present? Then make it required on the record.
• Can it be absent? Then the surrounding text has to still read correctly.

"Your reference is ." is the sentence customers notice.

Watch the addresses

Address blocks are where blank lines appear. An address with no second line should not produce a gap, and a letter with a gap in the address is a letter that looks automated and careless.

Format dates and amounts explicitly

A date appearing in the database’s format rather than a readable one, or an amount without its currency, is the second most common template fault.

Keep it short

The document is read by somebody who has a question. Long templates accumulate paragraphs added over years for cases that occurred once, and each one makes the important part harder to find.

Test with awkward records

Not the tidy one. A record with a very long name, one with missing optional fields, one with a note that runs to several paragraphs, one with an unusual character in the name.

Those four find nearly every template problem.

Print it

If it will ever be printed. Margins, page breaks and footer position behave differently on paper, and a document that breaks mid-address on page two is only visible when printed.

Get it approved before it is live

The template is what your organisation says to somebody. Whoever owns that wording should see the output, not the template.

Worked example

A template was built from the existing letter, with every varying part merged and each optional field checked for the empty case. Testing with four deliberately awkward records found an address gap and a date in the wrong format, both fixed before the first real letter.

Recommendations

• Start from the letter you already send.
• Check every merged field for the empty case.
• Test with four awkward records, not one tidy one.
• Print it if it will ever be printed.

Generating Documents

Generating produces a document from a template and a specific record.

Where to find it

Architect Panel → Layout & Pages:

• Document Templates — the templates themselves
• Document Designer — page size, margins, header and footer

Architect Panel → Data:

• Documents — where output is stored

Architect Panel → Automation:

• Workflow Builder — generating as part of a process

Three ways it happens

• By hand, from a record.
• From a workflow, as a step in a process — the letter node.
• In bulk, across many records.

Generating from a workflow is the useful one

It means the document is produced at the right moment, every time, without anybody remembering. A decision letter generated automatically when a case reaches its outcome is a letter that always gets sent.

Bulk generation needs care

Producing five hundred letters is producing five hundred letters. Check a sample before running the whole batch — a template fault multiplied across a mailing is expensive and public.

Generate ten, read them, then generate the rest.

The output is stored

Generated documents are records in their own right. That means they are the evidence of what you sent, which is exactly what you want when somebody disputes it.

It also means storage grows, and that retention applies.

Keep what you sent, not what you would send

An important distinction. Re-generating a document from today’s record produces today’s content, not what the customer received last March.

The stored copy is the record. Do not rely on being able to reproduce it.

Generation is not sending

Two separate things, and worth being clear about in a process. A document generated and not sent is a document nobody received, and it looks identical in the record to one that was.

Watch for failures

A generation that fails — a missing design, an unavailable field, a record in an unexpected state — should be visible. A workflow step that silently failed to produce a letter is a customer who was never written to.

Check the first one of each type

When a template goes live, read the first real document it produces. That is the cheapest possible quality check and it catches the thing testing missed.

Worked example

An organisation generates decision letters from a workflow at the point a case closes, storing each against the case. Bulk runs are sampled at ten before proceeding. Reading the first live letter of a new template found a merged field that was empty for one case type.

Recommendations

• Generate from workflows so it always happens.
• Sample ten before a bulk run.
• Keep the stored copy — do not rely on regeneration.
• Read the first live document of every new template.