Including Merge Fields in Email Templates and Signatures

You can include Merge Fields in an Email Template or Email Signatures to bring in content from Xero Practice Manager and from FYI. For an overview of how Merge Fields are used, refer to Overview of Templates, Signatures and Merge Fields for Emails.

Merge Fields are added to the content of the Email Template or Signature to include, for example, the client's First Name, Last Name and to add information about the email author, the Author's Name or Phone number. These examples are added as the Merge Fields such as {{ FirstName }} {{ LastName }} {{ PostalAddress }} {{ AuthorName }} {{ AuthorPhone }}. Merge Fields are added to the content of the Email Template or Signature need to be added in a specific format. The Merge Field has the correct character for the opening and closing curly brackets and it has a space after the opening curly brackets and before the closing curly brackets.

This article contains the following sections:

Merge Fields Groups in the Email Editor
Adding Merge Fields to an Email Template or Signature
Adding the Body Merge Field to Signatures
Setting up an Email Template to Send via OneDrive
Setting up an Email Template to Send Shared Folder Links
Conditional Merge Fields
Merge Fields for Custom Fields that are Maintained in FYI - Beta

Merge Fields Groups in the Email Editor

At the bottom of the Email Editor for the Template or Signature, the Merge Fields are grouped into categories (for example, FYI, OTHER, XERO LEDGER, CORPORATE AFFAIRS, XPM, XERO TAX).

Expand the group by clicking the arrow for the group and locate the Merge Field want to include.

You can also enter a keyword to filter the Merge Fields. For example, if you enter "Client" as the Filter merge fields, this will filter only those Merge Fields that include "Client".

The following is a summary of the Merge Fields and the groups.

FYI Group - Information from Xero Practice Manager

For example the client's First Name, Last Name as well as information such as the client's Manager is retrieved from Xero Practice Manager for the primary contact of the client, as displayed on the Client - Summary tab (refer to Client Summary).
These examples are added as the Merge Field codes {{ FirstName }}, {{ LastName }}, {{ Manager }}.

OTHER group - User Roles and Qualifications from FYI and Other FYI Merge Fields

For example, the Author's Name and Author's Phone, or the Owner's Name or Owner's Phone.
These examples are added as {{ AuthorName }}, {{ AuthorPhone }}, {{ OwnerName }}, {{ OwnerPhone }}.
If user information such as the direct or mobile phone number of the author or owner needs to be added or updated, this needs to be done in the Staff profile within Xero Practice Manager and then synced to FYI.

If you have added Roles to your users and Qualifications to the User Profiles (refer to Managing Users) these can be included in the Email Templates or Signature for the Author of the document that is created. These examples are added as, {{ AuthorRole }} {{ AuthorQualifications }}.

The OTHER group also holds other Merge Fields used within FYI such as Attachment Links, Created Date, Original Filename, Reference Number, Shared Folder Link and Upload Folder Link.

Author and Owner Merge Fields

When Emails are created from a Template and Signature that use certain Merge Fields, such as those that relate to Author (Author Name, Author Role Author Phone), these are only applied when the final sender of the email has been determined and these do not display when editing the email in FYI.

The Author Merge Fields relate to the 'sender' of the email.
The Owner Merge Fields take the information relating to the person who originally created the email.

If an email is edited and sent by someone after it is initially created, the Owner information does not change, but the Author information will change to reflect the user who sent the email.

OTHER Group - Reference Number from FYI

To include the unique FYI reference number, add the Reference Number Merge Field.
This adds the code {{ ReferenceNumber }}. Refer to Unique Document Reference Number.

OTHER Group - Other Information from FYI

You can add Merge Fields for include other information such as the Created Date and Original File.

XERO LEDGER Group - Information from Xero Ledger

Merge Fields for Period From, Period To and Year from Xero Ledger can be added.

XPM Group - Custom Fields

If you have set up Custom Fields in your Xero Practice Manager, these are in the XPM group and you can include Merge Fields for these in Email Templates and Signatures.

If the Custom Field includes any spaces, these are replaced in the Merge Field in FYI with an underscore (_). If the Custom Field includes any full stops or any special characters (such as , or &) these are removed in the Merge Field in FYI.

XERO TAX Group - Tax Merge Fields

The Tax Merge Fields are used in the FYI pre-configured processes for Tax Assessments processes which are triggered by Tax Returns and Assessments from Xero Tax (refer to Xero Tax Return AutoFile (Australia Only)). If these Tax Merge Fields are used in any other processes (such as Custom Processes) or if a template with the Tax Merge Fields is used when creating a new email, they will retrieve the data from the most recent Tax Return or Assessment. Refer also to Including Advanced Tax-Related Merge Fields in Email Templates.

FORMATTING Group

For information purposes, the FORMATTING group gives a variety of formatters that can be added to Merge Fields to modify their appearance. Refer also to Formatting and Fonts in Email Templates and Signatures.

Adding Merge Fields to an Email Template or Signature

To include any of the Merge Fields:

Position the cursor in the location in the Email Template or Signature where you want the information to appear.
Then click to open the group of Merge Fields at the bottom of the Email Editor.
Click on the required Merge Field (for example, Salutation).

The correct code for the merge field is added for you in the body of the Email Template.

Merge Fields are added in the same way to the Email Signature for example for the Author Name, Author Phone, information from FYI - for example, the Role of the Author and a unique Reference Number for the FYI document.

Refer also to Including Advanced Tax-Related Merge Fields in Email Templates.

Adding the Body Merge Field to Signatures

The Body Merge Field can optionally be added to Email Signatures as a placeholder for where the contents of a template will be included.

Note: The Body Content Merge Field is in the Other group in the Merge Fields and is only included if the template has already been marked as Signature.

You can apply styling to the Body Merge Field to set the style (such as fonts and paragraph spacing) for the body of the email. You can also use the Body Merge Field to apply a salutation to all emails that is consistent across the practice (such as always having this as Dear …, or Hi …). By including the salutation in the Signature, and then adding the Body Merge Field below this as the placeholder, the email is set up with the consistent salutation at the top of the email and the formatting ready for the email content to be entered by the users.

When an email is created with only the Signature and no template is selected, this sets up the correct styling for the email content.

Note: When applying certain styling such as fonts, this needs to be applied to the whole Signature. Use Ctrl+a to first select all the content of the Signature.
When an email is created with a template that does have styling, this overrides any styling set for the Body Merge Field.

Note: There are certain styling settings on the Body Merge Field that may affect a template depending on how your templates have been set up. Before adding it to any Signatures available practice-wide or to individual users, it is recommended that you set up a Signature assigned for your own use first and check the effect it has on the styling used in your templates.

Due to the way in which styling is applied to HTML, you may find that using certain keys (such as a backspace) you may lose the style. If this happens, you can usually restore the styling by clicking elsewhere in the content area of the Email Editor.

Setting up an Email Template to Send via OneDrive

When sending documents by OneDrive, if the user will be selecting a template (refer to Sharing Documents via OneDrive) these template(s) used for sending via OneDrive must include the merge field for Attachment Links {{ AttachmentLinks }}. This Merge Field controls where FYI will insert the OneDrive links that are created for the documents. When creating the template, select Attachment Links from the OTHER group in the Merge Fields.

If this Merge Field is not included in the template, the link will not open.

Note: Ensure you use the {{ AttachmentLinks }} Merge Field.
Do not use the {{ ShareFolderLink | web_link }} and {{ UploadFolderLink | web_link }} as these are used when sharing folders via Collaborate and the ShareFolderLink and UploadFolderLink Merge Fields are not designed to work in an Automation or if the Template is selected when an email is created directly.

Setting up an Email Template to Send Shared Folder Links

The Merge Fields Share Folder Link and Update Folder Link are used when setting up a template to inform a client that they have been given access to the OneDrive shared folders. These include links to the client's Share Folder and Upload Folder in the email. Refer to Setting up the Shared Folders Email Template and Assigning Share Settings Access.

Note: The {{ ShareFolderLink | web_link }} and {{ UploadFolderLink | web_link }} Merge Fields are used when sharing folders via Collaborate. They are not designed to work in an Automation or if the Template is selected when an email is created directly.

Conditional Merge Fields

Email Templates and Signatures support conditional merge fields.

For example, if you wanted to use a Custom Merge Field "Preferred_Name" if this was available, otherwise use the Merge Field "Salutation". For this example (of the Custom Field "Preferred_Name" and the merge field "Salutation), you would add these Merge Fields to the Template or Signatures in FYI and then add the conditions as in the following example.

{% if XPM_custom_Preferred_Name <> '' %} {{ XPM_custom_Preferred_Name}} {% else %} {{ Salutation}} {% endif %}

Replace "XPM_custom_Preferred_Name" or "Salutation" in the example above as relevant to use different Custom Fields or Merge Fields.

Refer to the Shopify help article https://shopify.github.io/liquid/basics/operators/ for information on Liquid Template Language operators.

Merge Fields for Custom Fields that are Maintained in FYI - Beta

The function to manage Client and Job Custom Fields in FYI is a Beta function and not yet available for general release.

Custom Fields and User Custom Fields that have been added in FYI are included with any other Custom Fields in the Email Editor for the Template or Signature, in the XPM group.

Important note: Currently, when selecting a Merge Field that has been added in FYI, you need to manually change the prefix of XPM to fyi. This will be corrected in the near future.

They need to be added to the Template or Signature as in the following example for the User Custom Field Bookkeeper.

When creating an email using a Template or Signature that includes a User Custom Field, if you have selected Draft in FYI, you can check how the User Custom Field will populate in the email when sent using the Preview using the Preview button in the Email Editor. Refer to Previewing the Draft in FYI Email in Creating an Email in FYI.

Articles in this section

Merge Fields Groups in the Email Editor

FYI Group - Information from Xero Practice Manager