An engagement letter in Aiwyn is generated, not written. Your firm's engagement admins build a letter template once; every letter drawn from it is assembled at the moment it is created, from the client, contacts and projects on the engagement. This page explains what a dynamic letter template is made of and why the letter you open already reads the way it does.
The parts of a template
A dynamic letter template is a sequence of content placed on a page. Some of that content is flat text: wording typed straight onto the template that reads the same on every letter. The rest is made of three reusable elements.
| Element | What it is | Where it is built |
|---|---|---|
| Block | A paragraph-level piece of content: an introduction, a scope-of-services section, a fee schedule, terms and conditions, the signature area. A block is built once and can be inserted into any number of letter templates. It can be locked and can contain other blocks. A user with the Edit Customized Document permission can still flatten a locked block on an individual letter. | Settings → Document Templates → Content |
| Snippet | A small piece of inline wording inside a sentence, such as "company" or "organization" depending on the client's entity type, or "return" or "returns" depending on how many projects are on the letter. A snippet is placed inside a block. | Settings → Document Templates → Content |
| Variant | One version of a block's or snippet's content, with a condition attached. A block or snippet can have as many variants as the firm needs, and the condition decides which one appears on a given letter. | Inside the block or snippet |
Nesting rules
- A block can contain blocks, snippets, variants, placeholders and text.
- A snippet can contain variants, placeholders and text. It cannot contain another snippet, and a block cannot be placed inside a snippet.
- The template editor rejects circular nesting, such as a block that contains itself through another block.
How a variant is chosen
Every variant carries an expression: a condition built from the engagement's data. When Aiwyn generates a letter it evaluates each variant's expression against that engagement and shows the variant whose condition is met. The other variants of the same block or snippet stay hidden. If no variant matches, the block or snippet shows nothing. Aiwyn Implementation usually recommends adding a fallback variant to prevent the block or snippet from appearing blank.
Expressions are built from placeholders, the same variables that merge values into the letter. Anything that can be merged can be tested: the client's type and state, the names of the projects on the letter, the service line, the engagement partner, the price and prepayment, the dates, and any custom fields your firm maps from its practice management system. An engagement admin builds a condition in a visual condition builder by choosing a field, an operator and a value, combining conditions with AND and OR.
Some patterns you will see in almost every firm's templates:
- Client type. One block with three variants: the individual paragraph when the client type is Individual, the trust paragraph when it is Trust, the entity paragraph otherwise.
- Project name. The corporation wording when a project name contains "1120" but not "1120S"; the employee-benefit-plan introduction when a project name contains "EBP".
- A custom field. A bookkeeping clause when any project on the letter has a project type of Bookkeeping; a supplemental-schedules paragraph on an audit letter when a custom field says one is required.
- Price. A fee table, with one row per client and project, when a project on the letter has a price greater than zero; a plain list of returns when nothing is priced.
- Presence of data. The address block only when the client has an address line.
The fee-table example also shows a second thing blocks can do: a block can repeat, producing one row for each project or client on the letter, with its own condition applied to each item.
What this means when you send a letter
The draft you open has already been tailored. Nobody chose its paragraphs; the client and projects you selected on the engagement details page did. That is the point of a dynamic template. Most letters need no customization at all, and a batch of 500 letters from one template will contain individual, trust and corporate paragraphs in whatever mix the clients require.
Three consequences follow.
- A paragraph that reads wrongly is usually data that is wrong. The block is testing a client type, project name, project type or custom field that is wrong or empty in your practice management system. Correct the record there; a draft letter picks up the change within a few minutes without being recreated. Editing the letter hides the symptom and leaves the next letter for that client wrong too.
- You can see what is dynamic. In the letter editor, turn on Highlight dynamic content. Placeholders are highlighted, and each dynamic block shows a thick blue left border and a dynamic icon. Text with no outline is flat text. Turn the toggle off to read the letter the way the client will.
- A genuine one-off change is made by flattening. A user with the Edit Customized Document permission can select any block—even a locked block—and choose Flatten. Its current wording becomes flat text on this letter only, placeholders inside it keep merging, the block's variants no longer apply to this letter, and the template is untouched. To prevent a user from editing a letter, including flattening content within a locked or unlocked block, remove the Edit Customized Document permission. Edit on a block is different: it changes the block in the template and on every letter that uses it, the editor warns how many engagements share it, and it appears only for users with template editing permissions.
What the template cannot do on its own
A variant can only test data that exists. Every variation a firm wants in a letter has to be present as a field somewhere, either a standard field such as client type or project name, or a custom field created in the practice management system and mapped to Aiwyn. Tax letters can usually be driven by client type and project name alone. Audit letters rarely can: full scope versus limited scope, supplemental schedules, non-attest services and the parties charged with governance are seldom standard fields, so each one has to be created as a custom field before a template can express it. See Custom fields that drive letter content.
Renewals and template changes
A renewed letter is generated from the current template against the new year's data, so its paragraphs can differ from last year's without anyone editing anything, and wording that was flattened on last year's letter starts clean. A change an admin makes to a block reaches every draft letter that uses it and every letter generated afterwards; it does not change letters already sent.
Related
- How engagement letter content and type are determined
- Edit an unlocked block of a letter
- Locked sections and who can unlock them
- Custom fields that drive letter content
- Troubleshoot a letter showing the wrong paragraph
- Document template fields and Engagement placeholder variables