A dynamic letter template can only vary its wording on data it can see. Standard fields carry most of what a tax letter needs. Audit, assurance and advisory letters usually need distinctions that no practice management system stores as standard, and those have to be created as custom fields before a template can express them. This page explains what custom fields do in a letter, why some letters need many of them, and what your firm has to supply.
What a custom field does in a letter
A custom field is a field your firm adds to a client, contact or project record in the practice management system and maps into Aiwyn during implementation. Once mapped it behaves like any other placeholder:
- It can be merged into the letter, for example the name of a supplemental schedule.
- It can be tested by a variant's condition, for example show the supplemental-schedules paragraph when the field is true, or show the limited-scope paragraph when the scope field equals Limited.
Client and contact custom fields are available at the letter level, both for merge tags and conditions. Project custom fields are available inside the projects on the letter, so a condition can ask whether any project on the letter has a given value.
Why tax letters rarely need them and audit letters usually do
A tax letter's variations line up with data firms already keep: the client's type decides individual, trust or entity wording, and the project name or type decides which return the paragraph describes. Client type and project name drive the great majority of tax letter variants.
An audit letter varies on things that live in the engagement team's heads or in a scoping sheet: full or limited scope, whether supplemental information is reported on, which non-attest services are included, who is charged with governance, whether the plan is an employee benefit plan. None of those are standard fields. Each one that is meant to change the wording has to become a custom field, be populated on every client or project it applies to, and be mapped to Aiwyn. Firms that have done this have consolidated ten or more audit letter templates into one dynamic template, but the work is in the fields, not in the template, and it takes time.
What your firm supplies
| Step | Who | What it involves |
|---|---|---|
| Identify the variations | Your engagement admin with the service line | Compare the existing letters line by line and list every place the wording differs and why. Each "why" is a candidate field. |
| Decide where each field lives | Your firm | On the client record for things true of the client, on the project for things true of the engagement. Supported field types are String, Number and Boolean. Decide the values: true/false, a short list, or free text. |
| Create and populate the fields | Your firm, in the practice management system | The field has to exist and be filled in before a letter can use it. A field that exists but is empty renders blank and makes every variant that tests it false. |
| Record the mapping | Your engagement admin with Aiwyn | A single list of each field's name, where it lives in the practice management system, its possible values and an example, so the mapping can be done in one pass rather than field by field. |
| Map the fields into Aiwyn | Aiwyn Implementation, from the list | Aiwyn Implementation maps the field from the practice management system to a corresponding custom field in Aiwyn. The firm cannot enable project custom fields without Aiwyn Implementation. |
| Build and test the variants | Your engagement admin | One variant per value, tested with real clients and projects that carry each value. |
Two patterns that reduce the number of fields
- A menu you reduce. Put every optional paragraph on the letter and let the preparer delete the ones that do not apply, rather than creating a field for each. Simpler to build, more for the preparer to do on every letter.
- A numbered list. For a long list of optional services, hold a single list field whose values are numbers, and give the block one variant per number. One field drives many paragraphs.
When the data lives somewhere else
If the facts that drive a letter are kept outside the practice management system, they still have to reach Aiwyn as fields. If this is contracted, Aiwyn Implementation can work with data managed outside the practice management system, such as data in a warehouse. This may require a special addendum to the firm's contract with Aiwyn. Contact your Customer Success Manager or Aiwyn Support to begin the process with Aiwyn Implementation.
What this means for a preparer
If a custom-field-driven paragraph is wrong on a letter, the value on the client or project is wrong or empty. Correct it in the practice management system and the draft updates within a few minutes. See Troubleshoot a letter showing the wrong paragraph.
Related
- How dynamic letter templates work
- How your practice management system drives engagement defaults
- Document template fields and Engagement placeholder variables
- Manage blocks, snippets and variants in a letter template