The template determines what an engagement letter says. Creating the engagement supplies the values that populate the template, not the letter’s standing language.
What a template controls
A template defines the letter’s structure, standard language, and placeholder variables. Selecting an Engagement Template determines the service scope and terms the client reads.
What the engagement supplies
The engagement record supplies values such as the client, dates, Partner, Manager, and template-specific fields. Aiwyn resolves the template’s placeholders and dynamic content against those values to generate the letter.
Why templates are managed centrally
Templates are maintained in Settings → Document Templates. Engagements created from the same template inherit consistent language. If a fee, clause, placeholder variable, or dynamic content appears incorrect, update the template so unsent drafts and future letters use the correction.
Templates are versioned. You can return to a previous version if needed.
Letters already generated
Changing a template updates unsent letters that are still in Draft and applies to letters generated in the future. It does not update letters that have already been sent.
Dynamic letter templates: how the wording is decided
Firms' engagement letter templates are dynamic letter templates (DLT). A dynamic template is assembled from reusable blocks and snippets, and the data on the engagement decides which wording each of them shows. In the letter editor, the Highlight dynamic content toggle shows you which parts of the letter were decided this way. Consent documents do not support dynamic content.
Blocks, snippets and variants
- A block is a paragraph-level piece of content: an introduction, a scope-of-services section, a fee schedule, terms and conditions, a signature area. Blocks are built once in Settings → Document Templates → Content and reused across any number of letter templates. A block can be locked, and a block can contain other blocks.
- A snippet is a small piece of inline wording inside a sentence, such as "company" or "organization" depending on the client's entity type. Snippets live inside blocks.
- Both blocks and snippets can carry variants. A variant is one version of the content with a condition, called an expression, attached to it. A block or snippet can have as many variants as the firm needs. When Aiwyn generates a letter it evaluates each variant's expression against the engagement's data and shows the variant whose condition is met; a variant whose condition is not met is hidden. If no variant matches, the block or snippet shows nothing.
- Expressions are built from placeholders. The same placeholder variables that merge values into the letter — client type, client state, project name and project type, service line, engagement partner, price, prepayment, dates — are the fields an engagement admin tests in a variant's condition, together with any custom fields your firm has mapped from its practice management system. Conditions are built in a visual condition builder (field, operator, value, with AND/OR groups) or written directly as a JSONata expression.
- Nesting rules. A block can contain blocks, snippets and variants. A snippet can contain variants and placeholders but not another snippet, and a block cannot be placed inside a snippet.
- Text that sits directly on the template outside any block is flat text. It reads the same on every letter unless a preparer edits it.
Examples of what drives a variant
- Client type is Individual → show the individual paragraph; client type is Trust → show the trust paragraph; anything else → show the entity paragraph.
- Project name contains 1120 but not 1120S → show the corporation wording.
- Project type (a custom field) equals Bookkeeping on any project on the letter → add the bookkeeping clause.
- Project name contains EBP → show the employee-benefit-plan introduction instead of the standard audit introduction.
- Project price is greater than zero → show the fee table, with one row per client and project; otherwise show the list of returns with no prices.
What this means for the person sending the letter
- The letter you open is already tailored. The paragraphs you see were chosen by the client, contacts and projects you selected on the engagement details page, not by anyone editing the letter. That is the point of a dynamic template: most letters need no customization at all.
- If the wrong paragraph is showing, the cause is almost always the data. A block is reading a client type, project name, project type or custom field that is wrong or missing in your practice management system. Correct the record there rather than editing the letter; the draft picks up the change within a few minutes without being recreated. If you have permission to edit the template, select Edit on the block to see the expression it is evaluating.
- Use Highlight dynamic content to see what is dynamic. With the toggle on, placeholders are highlighted and each dynamic block shows a thick blue left border and a dynamic icon. Turn it off to read the flat letter the way the client will.
- A one-off change is made by flattening. Select the block and choose Flatten. The block's current wording becomes flat text on this letter only, placeholders inside it keep merging, the template is untouched, and the block's variants no longer apply to this letter. Any engagement user can flatten; only users with template permissions see Edit on a block.
- Editing the block itself changes every letter that uses it. The editor warns you how many engagements use the block. That is the template-maintenance path, not the way to fix one client's letter.
- Renewals regenerate from the template. A renewed letter is built from the current template against this year's data. Flattened or overridden wording on last year's letter does not carry across.
Consent documents
A consent document captures a letter signer’s agreement or disagreement with a consent statement, such as a 7216 consent. It presents two radio buttons: Agree and Deny. Consent documents do not support dynamic content.
When an engagement letter is sent with a consent document and the signer grants consent, a Consented badge appears next to the Executed badge on the main Engagement page. Consented is a badge, not a separate lifecycle status.
Permissions for managing templates
Creating or editing a document template requires these permissions:
- Manage document templates
- View documents
- View the Documents module
Creating or editing consent documents also requires Manage document template consent contents.
Placeholder variable reference
For the complete list of placeholder variables, see Document template fields and Engagement placeholder variables.