Best Practices and Use Cases

This chapter collects complete use cases for typical tasks as well as tips, conventions and known obstacles in template creation. The reference pages describe each document function on its own. The use cases show how the building blocks work together.

Use cases

Each example leads from the data source to the place in the document and contains every configuration in full, ready to copy.

Use case	Data source	Building blocks
Letter with a recipient from an address data source	User, address data source	Forms (Object, DataProvider), Fields, Bind field
Case number from the business application in the header	Third-party system via Connect	Data, Fields, Placeholder Mapping, Placeholder Definition, Global Translations
Participant list as a table	User	Forms (ObjectCollection), Fields (WordTableRows), Bind field
Sharing global configuration and overriding it per template	User	Global Configurations, Forms (GlobalElements), Fields (GlobalFields, Modifications)

How to design templates for Microsoft 365 Copilot is described on the page Microsoft 365 Copilot.

Structure of an example

Every example follows the same structure: starting point and result, the building blocks involved with a link to the reference, the data flow, the configuration step by step with the reason for every non-obvious step, testing without a production system, variants and pitfalls.

The examples use neutral names: systems by their role («business application», «address data source»), English ids, labels set directly in Label. The configurations therefore work without preparation and can be taken over into any Datasource. For multilingual templates, use translate-Label with global translations. Only the case-number example requires such a translation, because its label follows the document language.

Template Hierarchy

• Always use the three-level hierarchy (Style, Layout, Content) for Word templates. Skipping levels leads to additional effort when making corporate identity changes.
• Place all "lowest common denominator" document attributes (logos, headers and footers, margins) in the Layout template, not in individual Content templates.
• Always set the Based on field in the template editor to link a Content template to a Layout template, and a Layout template to a Style template.

Version Control

• For significant template changes, always create a new version rather than editing the published version directly.
• Test changes using the "Test Document" function before publishing them.
• Mark stable test versions as "Draft" before marking them as "Published".

Permissions

• Set permissions thoughtfully: the default is "Authenticated users", which allows all users to see and change the template. Restrict as needed.
• Use organizational unit permissions to restrict templates to specific departments.

Global Configurations and Translations

• Use Global Configurations for any XML configuration that is reused across multiple templates. How global entries work together and how a single template deviates from them is shown in the use case Sharing global configuration and overriding it per template.
• Use Global Translations for all user-visible text that needs to be translated.
• Prefer typed global entries over untyped (classic) entries, because they are validated better and are easier to find.

Tags

• Establish a consistent tagging convention across your organization.
• Use tags to group related templates for easy filtering and for primedocs Connect integrations.

Tips & Tricks

• Use shortcuts: for example, open the styles panel with Ctrl + Alt + Shift + S.
• Keep templates simple: build as simply as possible. Simple templates are faster to create, easier to maintain and more robust.
• Comments in the code: document code in Fields with comments so that it remains comprehensible later on.
• Use profile fields where possible: for sender and organization details, fall back on profile fields rather than hard-coding values in the template.
• Standardize layouts: use as few shared Layout templates as possible rather than maintaining a dedicated layout for each Content template.
• Use Snippets: move recurring content into Snippets rather than duplicating it in every template.
• Keep tables simple: for self-defined table styles, opt for simple structures.

Bound images in header tables

Use In Line with Text for bound images in header tables. For free positioning, place the image inline in a text box and position the text box (see Layout).

Troubleshooting

Typical sources of error when laying out templates and their causes:

Symptom	Possible cause	Solution
Placeholder is not replaced	Field name does not match the PlaceholderMapping	Check the field name and mapping (case sensitivity, exact name)
Style looks different than expected	Style link is missing or has been overridden locally	Check the Based on link to the Style template and reset local formatting
Drop-down content control is empty	Drop-down/building block content controls are bound to the respective template	Do not use drop-down/building block content controls in Snippets (see Implementation variants)

caution

Changes in the Style template affect all Content templates built on it. Proceed with particular caution here and test the effects before releasing a changed Style template.

note

The tips on this page focus on modern primedocs templates (Style/Layout/Content).

Data types at a glance

Where a type comes from, what it delivers in code and how it gets into the Word document. Origin: Forms, Data, Fields, profile, snippets, global translations. Inserting: Bind field, placeholder in the layout.

Type	Origin	Value in JavaScript	Inserting in Word
Text	Forms, Data, Fields, profile	String	plain-text content control («Bind field») or Text placeholder in the layout
Choice	Forms	selected option Value as String, label via $.getChoiceLabel(…)	via a Text field
Date	Forms, Fields	date object (.Value for $.formatDate(…), $.getDateAsText(…) for the formatted text)	date content control or Text placeholder in the layout
YesNo	Forms, Fields	Boolean	not directly (drives logic in Fields, in PowerPoint the visibility via tags)
FormattedText	Data, Fields, global translations, snippets	FormattedText	rich-text content control
WordContent	Data, Fields, snippets	WordContent	rich-text content control, own paragraphs
InlineWordContent	Fields	InlineWordContent, exactly one paragraph	rich-text content control within a paragraph
WordTableRows	Fields	WordTableRows	the content row of a table, copied for every entry
Picture	Fields, profile (e.g. Profile.Org.Logo)	image	picture content control or Picture placeholder in the layout
Object	Forms, Data, Fields	JavaScript object with the schema ids as properties, or null when no entry was created	not directly, output via a field instead
ObjectCollection	Forms, Data, Fields	array of such objects (empty: [])	not directly, output via a field instead, e.g. WordTableRows

Details: Return value of field types, Objects and ObjectCollections in code, Field type per Office application.