Document template

This is the template designer. Here you write a template's wording, drop in merge fields that fill from the record, build tables that repeat for every line item, choose the letterhead and page layout, check the result against a real record, and publish it so people can generate documents from it.

Where to find it

On Document templates, click a template's code or name, or its pencil icon. The designer also opens straight after you create or duplicate a template. The page heading is the template's name, and the breadcrumbs read Settings > Documents > Templates > <template code>.

A link from the AI assistant can also open the designer with a record already chosen in the Preview panel (shown as "Record from the assistant") and the preview rendered once on arrival.

You need the View permission on Document Templates. Without it the page shows "No access" and "You do not have permission to view document templates. Ask your administrator." A template that doesn't exist, or belongs to another organization, shows "That item could not be found."

With only the View permission the designer opens read-only: the fields are greyed out and the editors have no toolbar.

Before you start

• To see how the template will look, you need at least one record of its record type (a demand for a demand letter, an estimate for a cost sheet) and the View permission on that record's module.
• To brand the page, set up a letterhead first.

What you see

Header

Next to the name you see the kind badge, the status badge, the current published version (for example "v3") and, in amber:

• Unsaved changes while you have edits on the page that aren't saved yet;
• Draft differs from the published version on a published template whose saved draft has changes that aren't published yet.

The line under the name says what the template renders against and how its documents are numbered, for example "Renders against a demand; numbers run DL-<financial year>-nnnnn."

On a Draft template an information bar reads "Drafts cannot be used yet. Publish the template to offer it on demand records and in workflows." (with the template's own record type).

Details

Field	What it means
Name	Required, up to 100 characters ("Name is required", "Use at most 100 characters").
Kind	Demand Letter, Termsheet, Offer Letter, Agreement, Allotment Letter, Receipt, Cost Sheet or Other.
Number prefix	The start of every document number, for example "DL" (hint "DL, TS, AGR…"). Letters and digits only, up to 10 ("Letters and digits only", "Use at most 10 characters"). Leave it blank to use the kind's usual prefix.
Letterhead	The letterhead wrapped around every page (hint "Logo, header and footer wrapped around every page."). Leave it on "Default letterhead (project's, else the organization's)" to let the record's project decide. Project letterheads show as "<name> (<project>)". Only active letterheads are listed.
Document title	The title of each generated document, which also becomes its file name (hint "Merge fields allowed; becomes the file name."). For example "Demand {{ entity.demand_no }} – {{ contact.name }}".
Description	Shown under the name in the template list (hint "Shown in the template list.").

The link Page settings (size, margins, font) opens the page layout (Hide page settings closes it):

Field	What it means
Page size	A4, A5, Letter or Legal.
Orientation	Portrait or Landscape.
Font	Noto Sans, Noto Sans Devanagari, DejaVu Sans, Arial, Times New Roman or Georgia.
Font size (pt)	6 to 24, in steps of 0.5. Blank means 10.5 (hint "Blank = 10.5").
Top margin (mm), Right (mm), Bottom (mm), Left (mm)	Required, 0 to 80.
Page numbers	"“Page x of y” in the footer."
Sort order	A whole number, 0 or more. Lower numbers come first in the template list and in the generate picker.
Active	"Inactive templates are hidden from pickers."

Number fields show "Enter a number", "Must be at least <n>", "Must be at most <n>" or "Whole numbers only" when the value is wrong.

Body

The main editor, with the hint "Insert fields from the toolbar or the list on the right; put the cursor in a table row and use “Repeat row” for schedules and line items." Its toolbar has the usual text formatting, colours, alignment, lists, indents, font size and paragraph style, links and images, table tools (insert a table, add or delete rows and columns, merge and split cells), three merge tools ({{ }} Field, Repeat row, Show when), undo and redo, and View HTML to see and edit the page's code directly.

Header and footer overrides

A collapsed card ("Blank = the letterhead's header and footer. {{ logo }} places the letterhead logo."). It opens by itself when the template already has its own header or footer. The two small editors, Header and Footer, replace the letterhead's header and footer for this template only.

Merge fields

The list on the right shows everything the template can fill in, with a search box ("Search fields…"):

• the record's own fields (for example "Demand (entity.…)");
• the related records, such as the contact, unit, project or booking;
• the lists you can repeat over, such as a demand's lines or an estimate's charge groups, each with the hint to use Repeat row;
• Totals, where the record type has them;
• Document: the document number, generation date, title, the organization's name, today's date and the letterhead logo (the list marks it "header / footer only"; the logo is placed in a header, see Letterheads);
• Formatting: ways to show values, such as amounts with Indian grouping (12,50,000.00), with or without the ₹ sign, amounts in words (in lakh and crore), and dates.

Amounts are inserted already formatted with Indian grouping, and dates as dates. Click a field to insert it at the cursor in the body. If you can't edit the template, a click copies it instead and you see "Copied to the clipboard."

Preview

Pick a record of the template's record type ("Search demand records…"), then preview it on screen or as a PDF. After a preview, a line shows the document title, the page size and orientation and the letterhead used, above the rendered page.

What you can do

Versions

Versions (<n>) opens "Versions of <template name>": every published version, newest first, as "Version <n>" with a green Current badge on the one in use, and the publish date and time, how many documents it produced and its notes. A template never published shows "Not published yet." The footer explains "Restoring copies a version into the draft without publishing it. Generated documents keep the version they were made with." and links to Generated documents.

• Who: anyone who can open the template.

Restore into draft

Next to each version in the Versions dialog. It copies that version's body, header, footer, document title, page settings and letterhead into the draft, and shows "Version <n> copied into the draft." Nothing is published: review it, then Publish changes to put it back in use.

• Who: anyone with the Edit permission on Document Templates. The button isn't shown on a Retired template; reopen it first.
• The Versions dialog closes after the restore.

Save draft

Saves your edits to the draft. You see "Template saved." A published template keeps producing documents from its published version; the saved edits show as Draft differs from the published version until someone publishes them.

• Who: anyone with the Edit permission on Document Templates, on a template that isn't Retired. In the default roles that is the Administrator, the Sales Manager and Legal & Documentation. Without the permission the button isn't shown.
• Greyed out while there is nothing to save. No reason is shown on hover.
• If a merge tag is broken, the save is refused. The message starts with the part of the template that failed ("body_html" for the body, "header_html", "footer_html" or "title_template"), then the problem and its line, for example "body_html: unexpected '}' (line 12)". View HTML helps you find the line. A body over 500 KB is refused with "The HTML exceeds 500 KB"; large pasted images are the usual cause.

Publish

Shown on a Draft template (as Publish changes on a published one; see below). It opens "Publish template": "The draft is snapshotted as version <n>. Documents generated from now on use it; earlier documents keep the version they were made with." (version 1 the first time). If you have unsaved edits it begins "The draft is saved first, then snapshotted…". Add Notes (optional) ("What changed in this version") and choose Publish. You see "Published as version <n>." The template becomes Published and is offered on its records and in workflows.

• Who: anyone with the publish permission on Document Templates (the role editor shows it in lower case). In the default roles that is the Administrator, the Sales Manager and Legal & Documentation. Publishing unsaved edits also needs the Edit permission, because they are saved first. Without the permission the button isn't shown.
• A template with an empty body can't be published. The page then shows "Please correct the highlighted fields." although nothing is highlighted: add content to the body and publish again.

Publish changes

The same action on a Published template. The dialog is titled "Publish a new version" and the draft becomes the next version number. Documents already generated keep the version they were made from.

• Who: as for Publish.
• Greyed out when there is nothing new to publish: no unsaved edits and the saved draft is the same as the current version. No reason is shown on hover (see Greyed-out buttons).

Retire

Shown on a Published template. It asks "Retire this template?" with "It disappears from the generate pickers and workflows that use it will fail. Existing documents are unaffected. You can reopen it later." Choose Retire. You see "Template retired." The template becomes Retired and inactive. Its fields are greyed out and the editors lose their toolbars until it is reopened.

• Who: anyone with the publish permission on Document Templates.

Reopen

Shown on a Retired template, in place of Save draft, Publish and Retire. You see "Template reopened." The template goes back to Published if it was ever published, otherwise to Draft, and is active again.

• Who: anyone with the publish permission on Document Templates.

Preview

Renders the template against the record you picked, on screen, using what is on the page now, including unsaved edits to the body, header, footer and page settings. The document number shows as "<prefix>-PREVIEW". Nothing is saved and no number is used up.

• Who: anyone who can open the template and also holds the View permission on the record's module (for example Demands for a demand letter). Without it the record search fails and the preview shows a message starting "Missing permission".
• Greyed out until you pick a record.
• If a field can't be worked out, the preview shows "Template could not be rendered:" and the reason.

Open PDF

Makes the same preview as a PDF and opens it in a new browser tab, so you can check page breaks, margins and the letterhead as they will print.

• Who and greyed out: as for Preview. If the PDF can't be made you see "PDF could not be produced:" and the reason.

Enlarge

Appears after a preview and shows it in a large dialog.

{{ }} Field

The toolbar button (tooltip "Insert a merge field") opens "Insert merge field", the same searchable list as on the right. Pick a field to insert it at the cursor. It is also in the header and footer toolbars.

• Who: anyone who can edit the template.

Repeat row

Makes one table row repeat for every item of a list, such as a demand's charge lines or a booking's payment schedule (tooltip "Repeat the current table row for every item of a list"). Put the cursor in the row, then choose the button. In "Repeat table row" ("The row under the cursor is repeated once per item; inside it write {{ row.<field> }}."):

• Repeat over: pick one of the record type's lists ("Choose a list…"), or Other expression… to type one.
• Row name: the name you use for each item inside the row; it starts as "row".

Insert marks the start of the row's first cell and the end of its last cell. Then fill the row's cells with the list's fields. Messages: "Choose what to repeat over.", "The row name may contain letters, digits and underscores.", "Put the cursor inside a table row first."

• Who: anyone who can edit the template.

Show when

Prints a paragraph, table or list only when a condition holds, for example only when TDS applies (tooltip "Show the current paragraph or table only when a condition holds"). Put the cursor in the block and choose the button. "Show block when" explains: "Wraps the paragraph, table or list under the cursor in a condition. Examples: entity.tds_amount > 0, contact.pan_no, entity.status == "Issued"." Type the condition and choose Insert. Messages: "Write a condition.", "Put the cursor inside the block to wrap."

• Who: anyone who can edit the template.

Statuses

Status	Meaning	How it gets there
Draft	Being written; can be previewed but not used.	A new or duplicated template, or Reopen on a template never published.
Published	Offered when people generate documents and in workflows, using the current version.	Publish; Publish changes adds a version and stays Published; Reopen on a template that has a version.
Retired	Hidden from the generate pickers; its workflow steps fail.	Retire.

Things to know

• Documents always use the published version, never the draft. You can rework a live template safely: nothing changes for users until you publish, and every generated document remembers the version it was made with. That is why a buyer's letter from last year can still be reproduced exactly.
• The preview uses your unsaved wording, but the saved letterhead and title. Changes to the body, header, footer and page settings show in the preview straight away. A change to Letterhead or Document title shows only after Save draft.
• Saving the template fixes its page layout. The page settings panel always holds a value for every field (starting at A4, Portrait, 20 mm top and bottom, 18 mm left and right, page numbers on), and Save draft stores all of them with the template. From then on they win over the letterhead's page size, orientation, margins and page numbers for this template. Only Font size (pt) falls through when blank. If you want a template to follow its letterhead's layout, set the same values here. The six starter templates carry no page settings until someone saves them in the designer.
• Unticking Active hides a template too. Only templates that are Published and Active are offered when people generate documents.
• Changing the kind doesn't change the number prefix. The prefix stays as it is. Clear Number prefix and save to take the new kind's usual prefix (DL, TS, OL, AGR, AL, RC, CS or DOC).
• The record type is fixed. It is chosen when the template is created and can't be changed here. To render against another record type, create a new template.
• Which letterhead a document gets. The template's own letterhead if one is picked; otherwise an active letterhead of the record's project; otherwise the organization's default letterhead (or, if none is marked default, the first active organization-wide letterhead by name). The template's header and footer overrides, when filled in, replace the letterhead's header and footer.
• Misspelt fields print blank. A field name the record doesn't have, or a list written under the wrong name, prints nothing rather than raising an error. Always preview against a real record before publishing.
• Keep repeat and show-when markers inside cells. Writing them between table rows by hand in View HTML breaks the table: the app moves stray text out of tables when it saves. Repeat row and Show when always place them correctly.
• Retired templates stop workflows. A workflow rule that generates a retired or unpublished template fails with "Template <CODE> is not published". Check Rules before retiring.
• Closing or reloading the browser tab with unsaved edits makes the browser ask whether you want to leave. Moving to another screen inside the app (a breadcrumb, the sidebar) does not ask, so Save draft first.
• There is no History button on this page; changes to templates are recorded in the Audit log.

Related

• Document templates
• Letterheads
• Generated documents
• Rules
• Greyed-out buttons
• Audit log