Skip to main content

Manage blocks, snippets and variants in a letter template

Maggie Shipley
Updated

Change the reusable content your firm's letter templates are built from. This guide is for engagement admins with document template permissions; preparers sending letters do not need it.

A block or snippet is shared. Editing one changes every template and every draft letter that uses it. Before you save, read the count of engagements using the block that the editor shows you, and generate a test letter afterwards.

Before you start

  • You need document template editing permissions. Without them the Edit option on a block is not shown in the letter editor and the Content library is inaccessible.
  • Know which field will drive the change. A variant can only test data that exists on the client, contact or project, or in a custom field your firm has mapped. If the field does not exist yet, see Custom fields that drive letter content first.
  • Have a test client whose data exercises each variant you are about to touch.

Find the block or snippet

  1. Go to Settings → Document Templates.
  2. Open Content. Blocks and snippets are listed together and can be searched and filtered by name, type and category.
  3. Open the block or snippet you need. Alternatively, open a draft letter, turn on Highlight dynamic content, select the block on the letter and choose Edit; this opens the same block.

Edit the wording of a variant

  1. Select the variant you want to change. Each variant shows its content and its condition.
  2. Change the text. Insert placeholders from the Insert Variable picker rather than typing them, so the field path and braces are exact.
  3. Save. The change applies to every template using the block and to every draft letter; sent letters do not change.

Add a variant

  1. In the block or snippet, add a new variant.
  2. Write its content.
  3. Build its condition in the condition builder: choose the field, the operator and the value. Add further conditions with Add Condition, and group them with Add Group when you need AND inside OR or the reverse. For logic the builder cannot express, switch the condition to JSONata and write it directly.
  4. Check the other variants' conditions and order. Variants are evaluated in order, and the first matching variant wins, so put the intended variant first when conditions overlap.
  5. Save, then generate a test letter for a client that meets the new condition and one that does not.

Add a snippet to a block

  1. Open the block and place the cursor where the inline wording varies.
  2. Insert the snippet. A snippet can sit inside a block, but a block cannot sit inside a snippet and a snippet cannot contain another snippet.
  3. Save and test.

Nest a block inside a block

Use this when a section has a general part and a more specific part that only some clients need, for example an audit-services block containing a nested employee-benefit-plan block.

  1. Open the outer block and place the cursor where the inner block belongs.
  2. Insert the inner block.
  3. Give the inner block its own variants and conditions; they are evaluated inside the outer block's context.
  4. Save. The editor rejects a nesting that loops back on itself.

Lock a block

  1. Open the block.
  2. Mark it as locked.
  3. Save. A user with the Edit Customized Document permission can still flatten the locked block on an individual letter. To prevent a user from editing a letter—including flattening content within a locked or unlocked block—remove that permission.

Make a one-letter change instead

If the change is for one client only, do not edit the block. Open that letter, select the block and choose Flatten. The wording becomes flat text on that letter alone and the block is untouched. See Edit an unlocked block of a letter.

Check your work

  • Generate a test letter for each case the block handles and read it with Highlight dynamic content on and then off.
  • Confirm the template still contains exactly one primary client signature block placeholder; the editor will not save a template without it.
  • Watch for the editor's null-value warnings: a placeholder with no source value renders blank.

Related

 

Related articles