Overview

Cuspy document templates are Word (.docx) files enriched with special merge field tags. When a document is generated, Cuspy replaces those tags with real investor and account data — producing a personalised PDF for each recipient.

This guide walks you through:

• Understanding the two types of merge fields

• Writing correct merge field syntax

• Structuring your template for different use cases

• Uploading and managing templates in Cuspy

• Testing your template before going live

Template Basics

A Cuspy document template is a standard Word document (.docx) that you design using any word processor — Microsoft Word, Google Docs, LibreOffice, or similar. You control the layout, branding, fonts, colours, and structure entirely.

To make the template dynamic, you insert merge field tags directly into the document text. These tags act as placeholders that Cuspy fills in at generation time.

Template Types

When uploading a template, you must assign it a type. The type determines which merge fields are available and how the template behaves during generation.

Merge Fields

Merge fields are special tags you place inside your Word document. When Cuspy generates a document, each tag is replaced with the corresponding data value for each investor account.

Merge Field Syntax

<<[FieldName]>>

System Merge Fields

System merge fields are built into Cuspy and are available in all templates. They give you access to standard investor and account data such as names, holdings, transactions, and organisation details.

For example, to display your organisation name, use the following merge field in your Word template.

<<[org.name]>>

For the full list of available system merge fields, refer to the Cuspy Developer Documentation.

Custom Merge Fields

When using a BYOD template, you can define your own merge fields that correspond to column headers in your uploaded CSV data file. This allows you to include any custom data — such as financial figures, fund performance, or personalised messages — in your generated documents.

Custom merge fields follow the same syntax as system merge fields:

<<[YourColumnName]>>

For example, if your CSV has a column called NetReturn, the merge field in your template would be:

<<[NetReturn]>>

Building Your Template

Step-by-Step

1. Open Microsoft Word (or any compatible word processor) and design your document layout as you normally would — add your logo, branding, fonts, and structure.

2. Identify the fields you need. Refer to the System Merge Fields list in the Developer Documentation for available data points.

3. Insert merge field tags directly into the document text at the appropriate positions. Ensure the tag syntax is exact — including the double angle brackets << >> and square brackets [ ].

4. For repeating sections such as transaction tables, structure the table rows using the foreach pattern described in Merge Field Syntax Reference.

5. For conditional content, wrap optional sections with if / endif blocks.

6. Save your document as a .docx file.

Custom Fonts and Embedding

Custom Fonts License

Fonts Requirements

To ensure fonts embed correctly, use static font files (e.g. Font-Regular.ttf, Font-Bold.ttf) rather than variable font files (e.g. Font-Variable.ttf, Font[wght].ttf).

Variable fonts contain multiple weights in a single file using interpolated axes. Many PDF generation, document processing, and printing pipelines don't fully support this — which can cause incorrect rendering, missing weights, or fallback to a system font.

Static fonts are a separate file per weight, making them reliably embeddable across all systems.

Please read further details about static fonts vs variable fonts.

Embedded Fonts

If your template uses custom fonts, you must embed them in the Word document before uploading. Without embedded fonts, Cuspy's PDF generation engine may substitute them with a default fallback font, which can affect your document's appearance and layout.

To embed fonts in Microsoft Word, go to File > Options > Save and enable Embed fonts in the file.

If you notice unexpected or incorrect fonts rendering in the PDF, this is typically caused by either the required static font files not being installed on the machine used to author the Word document, or the fonts not being properly embedded in the document itself.

Design Tips

• Keep merge field tags within the same text run where possible. Avoid splitting a tag across multiple formatting runs in Word, as this can cause parsing errors.

• Avoid placing tags inside text boxes or shapes — use standard paragraph or table cell content instead.

• If you apply bold or italic formatting to a merge field tag, apply it consistently to the entire tag including the << >> brackets.

• Always generate a preview document after making any changes to the template to verify the output before live generation.

Common Mistakes to Avoid

Uploading and Managing Templates

Please refer Manage Document Templates

Editing an Existing Template

It is recommended to start with the system default template as a base, so you can familiarise yourself with the syntax and layout before customising.

To update a template, download the existing .docx file, make your changes in Word, and re-upload it. You can then select the updated template before generating documents.

Deleting a Template

Templates that are no longer needed can be deleted to keep your list tidy. Once deleted, they will no longer be available for selection during document preparation. Any previously generated documents are NOT affected, as each retains its own copy of the original template at the time of generation.

Testing your Template

Always test your template before using it in a live document generation task. Cuspy provides a preview generation feature that produces a sample PDF using real data from your organisation, without distributing any documents to investors.

How to Generate a Preview

1. Create a document generation task and select your template.

2. Configure the document criteria as required.

3. Click Generate Preview.

4. Review the output PDF carefully — check field values, layout, formatting, and any repeating sections.

5. If any fields appear blank or incorrectly formatted, review your template tags and re-upload.

Further Reference

For more advanced template configuration, including the full list of available system merge fields and advanced syntax options, refer to the Cuspy Developer Documentation:

https://developer.cuspy.app/document-generation