Letter templates
Letter templates let you manage your organisation's standard letters. A template is a reusable layout with merge fields (such as the client's name) that are filled in automatically when you compose a letter from it. The screen is meant for organisation administrators and practitioners who manage letters.
Overview
| Route | /organization/letter-templates, /organization/letter-templates/new, /organization/letter-templates/:id |
| Audience | Practitioner / organisation administrator |
| Required permission | letter_templates.manage |
The overview lists every template in a table. A template moves through three statuses: Draft (being edited), Active (usable for new letters) and Archived (no longer usable). An archived template can no longer be edited.
How it works
A template is not a finished letter but a reusable layout with merge fields. The template itself holds no client data; that data is only filled in the moment you compose a letter from it. Once you understand this model, you also understand why a template has a lifecycle and why you never send a template directly.
Merge fields and where their data comes from
A merge field is a placeholder that is automatically replaced with real data when you compose a letter. The available fields are grouped by category; the data always comes from the context of the letter you are composing:
| Category | Examples | Source of the data |
|---|---|---|
| Client data | name, address, date of birth | The client in whose record you compose the letter. |
| Form answers | answer per question | The client's completed forms. |
| Date | date (short/long) | The day the letter is composed. |
| Practitioner | name, function, AGB code, BIG registration | The signed-in practitioner composing the letter. |
| Organisation | name, address, KvK number, logo | Your organisation's settings. |
| Care trajectory | name, start and end date, diagnosis, lead practitioner | The client's active care trajectory. |
| Referrer | name, type, AGB code, referral date | The referrer of that active care trajectory. |
| GP | name, practice, AGB codes | The client's own GP, from their care circle. |
| Care request | presenting complaint, request for help, goals | The client's care request. |
The complete list is under All merge fields.
Scrivio invents nothing. Every merge field is read literally from the underlying record at composition time — nothing is completed, corrected or capitalised for you. If something looks wrong in the letter (a first name without a capital, say), it is usually wrong in the record. Correct it there and compose the letter again.
If a field has no value at composition time (for example a client without a referrer), Scrivio simply leaves that spot blank — no placeholder or temporary text remains. When you compose the letter, Scrivio counts those empty fields for you; see What "missing values" means. Preview additionally lets you check up front how the template looks, so you don't send a half-finished letter.
Lifecycle and why archiving leaves existing letters untouched
The three statuses determine what you can do with a template:
| Status | Editable? | Usable for new letters? |
|---|---|---|
| Draft | Yes | No — activate it first. |
| Active | Yes | Yes. |
| Archived | No (read-only) | No. |
When you compose a letter from an active template, Scrivio takes a snapshot: the merged content and the values filled in at that moment are stored in the letter itself. The letter is then decoupled from the template. If you later edit or archive the template, previously composed letters do not change with it — they keep their own version. Archiving therefore only takes a template out of use for new letters; it does not rewrite history.
Editing creates a new version; the previous one is archived
When you edit an active template, Scrivio does not change the existing template but records your change as a new version — and the version you edited moves to Archived. This is intended behaviour, not a fault: it is how the exact template of already-generated letters is preserved, so a sent letter remains reproducible from the template it was built with.
What that means in practice:
- The overview keeps showing one row per template: the newest version. Older versions sit behind Show older versions on that row.
- A template with the Draft status is updated in place; no new version is created as long as the template has not been activated.
- If an archived template turns up that you did not archive yourself, it is almost always a previous version of a template you just edited. Nothing is lost: the newest version is simply Active.
- Archived therefore means two things: a version superseded by a newer one, and a template you took out of use yourself with Archive template. For readers with repository access: the underlying model (lineage, versions and keeping the head of the chain) is described in ADR-032.
From template to sent letter
A template is the starting point, not the end point. You don't send from this screen: you open a client's record, compose a letter there with an active template (filling in the merge fields) and then send it securely via Zivver. Composing and sending is a separate journey — see the Drafting and sending a letter journey. Zivver must be connected on the Integrations screen for this.
All merge fields
Below are all the merge fields Scrivio knows, grouped the way the editor's picker groups them. You don't have to type them: use Insert merge field and the spelling is guaranteed correct. A field you type yourself that is not in this list is never filled in — Preview lists such unknown fields separately.
Client data
From the record of the client you are composing the letter for.
| Merge field | What it renders |
|---|---|
{{client.name}} | The client's full name (including any name prefix) |
{{client.firstName}} | First name |
{{client.lastName}} | Last name |
{{client.initials}} | Initials |
{{client.email}} | Email address |
{{client.phone}} | Phone number |
{{client.address}} | Full address on one line |
{{client.addressStreet}} | Street and house number |
{{client.addressHouseNumber}} | House number on its own |
{{client.addressHouseNumberSuffix}} | House letter or suffix |
{{client.addressPostalCode}} | Postal code |
{{client.addressCity}} | City |
{{client.dateOfBirth}} | Date of birth, written out |
{{client.bsn}} | BSN |
{{client.gender}} | Gender in Dutch. If it is unknown or not filled in, it stays blank — a letter never says "Onbekend". |
Form answers
The picker shows one field per question from your organisation's forms here, not a fixed list. The field renders this client's most recent answer to that question; if the client never answered it, the spot stays blank.
If a template points at a question that has since been archived, the value is still rendered when there is one, but the letter reports it among the missing values when you compose it — so you know the template points at a question that is no longer asked.
Date
The day you compose the letter — not the date of the appointment or the care trajectory.
| Merge field | What it renders |
|---|---|
{{date}} | Today's date, for example 28 februari 2026 |
{{date.short}} | Today's date as 28-02-2026 |
{{date.long}} | Today's date with weekday, for example vrijdag 28 februari 2026 |
Practitioner
The signed-in practitioner composing the letter — not necessarily the care trajectory's lead practitioner; the {{hoofdbehandelaar.*}} fields below cover that. You manage this data on your own Profile.
| Merge field | What it renders |
|---|---|
{{behandelaar.name}} | Full name |
{{behandelaar.firstName}} | First name |
{{behandelaar.lastName}} | Last name |
{{behandelaar.email}} | Email address |
{{behandelaar.phone}} | Phone number |
{{behandelaar.functionTitle}} | Job title |
{{behandelaar.agbCode}} | AGB code |
{{behandelaar.bigRegistration}} | BIG registration number |
Organisation
From Organisation settings.
| Merge field | What it renders |
|---|---|
{{organization.name}} | Organisation name |
{{organization.address}} | Full address on one line |
{{organization.addressStreet}} | Street and house number |
{{organization.addressPostalCode}} | Postal code |
{{organization.addressCity}} | City |
{{organization.phone}} | Phone number |
{{organization.email}} | Email address |
{{organization.agbCode}} | The organisation's AGB code |
{{organization.kvkNumber}} | Chamber of Commerce (KVK) number |
{{organization.logo}} | The organisation logo, as an image — see below |
The practice logo
The logo on a letter is a single merge field: {{organization.logo}}. It is the only field that renders an image rather than text, at the spot in the letter where you place it.
Two things matter here:
- You upload the logo once, at Practice details → Manage logo. There is no separate per-template logo upload; every template uses the same file, so a new logo applies immediately to every letter you compose afterwards.
- The logo only appears in a letter if the template contains the field. Scrivio never places a logo at the top of a letter by itself: a letter's layout belongs to the practice. New organisations start with three default templates (Briefpapier, Terugkoppeling aan de verwijzer and Afsluitbericht aan de huisarts) that open with this field. Existing templates were left untouched, so if your template has no logo yet, add the field at the top yourself with Insert merge field.
If you have not uploaded a logo, the spot simply stays blank and nothing else about the letter changes.
Care trajectory
From the client's active care trajectory. If the client has no active trajectory, all of these stay blank. If the client has more than one, Scrivio cannot choose and the letter is not composed: close one of the trajectories first.
| Merge field | What it renders |
|---|---|
{{zorgtraject.naam}} | Name of the care trajectory |
{{zorgtraject.startdatum}} | Start date |
{{zorgtraject.einddatum}} | End date (blank while the trajectory runs) |
{{zorgtraject.setting}} | Treatment setting |
{{zorgtraject.status}} | Active or Closed |
{{zorgtraject.diagnose}} | The recorded DSM-5 diagnoses, primary first |
{{zorgtraject.diagnoseStatus}} | Differential or definitive |
{{zorgtraject.dsm5Code}} | DSM-5 code of the primary diagnosis |
{{zorgtraject.dsm5Omschrijving}} | Description of the primary diagnosis |
{{zorgtraject.icd10Code}} | ICD-10 code of the primary diagnosis |
{{zorgtraject.profiel}} | Basis GGZ profile that applies on the letter date |
{{zorgtraject.zorgvraagtyperingCode}} | Care-demand typing code on the letter date |
{{zorgtraject.zorgvraagtypering}} | Description of that care-demand typing |
{{hoofdbehandelaar.naam}} | Name of the trajectory's lead practitioner |
{{hoofdbehandelaar.email}} | The lead practitioner's email address |
{{hoofdbehandelaar.agbCode}} | The lead practitioner's AGB code |
Referrer
The referrer of that same active care trajectory — who referred this trajectory. If no referral is recorded, the fields stay blank.
| Merge field | What it renders |
|---|---|
{{verwijzer.naam}} | Referrer's name |
{{verwijzer.type}} | GP, medical specialist, occupational physician or other referrer |
{{verwijzer.email}} | Email address |
{{verwijzer.agbCode}} | AGB code |
{{verwijzer.verwijsdatum}} | Date of referral |
GP
The client's own GP, from the care circle in their record. That is not the same as the referrer above: often it is the same person, but not always — a progress report goes to the GP, a referral letter names the referrer. If no GP is recorded, or the care circle holds more than one active GP, the fields stay blank; Scrivio never picks one itself.
| Merge field | What it renders |
|---|---|
{{huisarts.naam}} | The GP's name |
{{huisarts.praktijk}} | Name of the GP practice |
{{huisarts.adres}} | The practice address on one line |
{{huisarts.agbCode}} | AGB code of the GP themselves |
{{huisarts.praktijkAgbCode}} | AGB code of the practice |
{{huisarts.email}} | Email address |
{{huisarts.telefoon}} | Phone number |
Care request
From the care request in the client's record.
| Merge field | What it renders |
|---|---|
{{zorgvraag.aanmeldklacht}} | Presenting complaint |
{{zorgvraag.hulpvraag}} | Request for help |
{{zorgvraag.doelen}} | Treatment goals, separated by semicolons |
{{zorgvraag.hulpaanbod}} | Help offered |
What "missing values" means
When you compose a letter in a client's record, Scrivio checks which merge fields in the chosen template actually resolve to a value. If any stay blank, a notice appears above the letter reading something like "3 ontbrekende waarden in de brief" (3 missing values in the letter). Expand it to see which fields those are.
This is not an error in the template, and it blocks nothing:
- The letter can be generated and sent as normal. The empty fields simply stay empty in the final letter.
- It is an invitation to complete the underlying data: if
{{verwijzer.naam}}is blank, no referrer is recorded on the care trajectory. Fill that in, compose the letter again, and the notice is gone. - A field pointing at an archived form question is listed here too, even when there is an answer.
A different thing is the notice in Preview about unknown placeholders: those are fields that do not exist at all, usually a typo in a manually typed field. They always stay blank — fix them in the template with Insert merge field.
Create template
Click New template at the top right to open a blank template. Fill in the fields and save; the template starts as a Draft.
| Field | Required | Description |
|---|---|---|
| Name | Yes | The name the template appears under in the overview. |
| Description | No | A short note on the purpose of the template. |
| Content | No | The letter body with formatting and merge fields (see Edit content). |
Edit template
In the overview, click a row or the edit icon to open a template in the editor. Here you change the name, description and content. Changes are only kept once you save as draft. If you leave the page with unsaved changes, Scrivio asks for confirmation. An archived template is read-only.
When you edit an active template, your change is recorded as a new version and the previous version moves to Archived — see Editing creates a new version.
Duplicate template
The duplicate icon in the overview creates a copy of an existing template. The copy gets the Draft status so you can adjust the content without touching the original. Handy for basing a new letter on an existing one.
Archive template
The archive icon takes a template out of use. Scrivio asks for confirmation first. An archived template can no longer be used for new letters and can no longer be edited; existing letters are unchanged. Use the status filters to find archived templates again.
Filter by status
Above the table, tabs let you filter the list by status: All, Active, Draft and Archived. Each tab shows the number of templates in that status. By default you see all templates.
Sort
Click a column header to sort the table; click again to reverse the order. You can sort by Name, Status and Last modified. The list defaults to last modified, newest first.
Edit content
In the editor you compose the letter body with a formatting toolbar: headings, bold, lists and text alignment. Alongside plain text you insert merge fields that are filled in automatically per letter (see Insert merge field).
Insert merge field
The merge-field button in the toolbar opens a searchable list of available fields, grouped by category. Pick a field to insert it at the cursor position. When you compose an actual letter, the field is replaced by the matching data, for example the client's name. Which fields exist and where their value comes from is listed under All merge fields.
Save as draft
Save as draft stores your changes without activating the template. The template stays in Draft status and is not yet usable for new letters. A name is required before you can save.
Activate
Activate moves a template from Draft to Active. Unsaved changes are saved first. Only after activation can you use the template to compose letters. The action is available only for templates with the Draft status.
Preview
Preview opens a window showing how the letter looks with the current formatting and merge fields. This lets you check the result before activating or using the template.
Because you have not picked a client here, the preview shows example values for the client fields; the organisation, practitioner and date fields are real. If the template contains fields that do not exist — a typo in a manually typed field, for instance — the preview lists those separately: they stay blank in every letter. How many fields stay blank for an actual client only shows when you compose the letter; see What "missing values" means.
Send via Zivver
You don't send a template directly. You use an active template to compose a letter in a client's record; that letter is then sent securely via Zivver. Composing and sending a letter is a separate journey — see the Drafting and sending a letter journey. Zivver must be connected on the Integrations screen for this.