Merge Fields Overview

Merge Fields allow practices to dynamically insert data into Templates and Automations to streamline processes and personalise jobs, emails, documents and more.

For example, Merge Fields can be used to:

Use Client or Job fields when creating emails, documents, tasks, and more.
Inherit Client Custom Fields directly onto a Create Job step.
Apply key job details from the original job when rolling over new jobs.
Using an existing date Custom Field as the due date of a Task, or start date or due date of a Job.
Add additional details and context to Comments.
Add data from integrated platforms, for example Companies House, BGL, or NowInfinity.

Note: Rate limiting may occur when you have exhausted all available synchronisation requests to Xero Practice Manager. Practices will need to consider how the use of Merge Fields tie into existing processes that utilise synchronisation between XPM and FYI. Refer to Xero Practice Manager Rate Limiting.

Using Merge Fields

Merge Fields are available where the below icon is displayed:

For detailed instructions on using Merge Fields, refer to the following articles:

Merge Field Sections

The Merge Field selection window will be displayed with Merge Fields grouped together into different sections. The following is a summary of each section.

The Sections displayed will depend on whether you are creating an Email, Document, Automation, or Template. Some Sections and Fields will also only be displayed if your practice is integrated with another platform, for example, BGL or NowInfinity.

Merge Field Section	Details
General	General information, for example the current date, or the date at the end of the month when the email is created.
Practice	Information specific to your practice, including your Name and Legal Name, and if using New Collaborate, the Collaborate Site Link to the SharePoint site. The Share Folder Link and the Upload Folder Link (in the Client section) should be added to the template that is used to send the email from the Sharing Settings in Client - Collaborate. Refer to Sharing the Share Folder and Upload Folder with Clients and Setting up Collaborate Email Templates.
Automation Initiator	The details of the user who manually triggered the automation. The user's details are maintained in the Staff Profile within the practice management software and synchronised to FYI. 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 your practice management software and then synced to FYI.
Client	Fields specific to the client, including Client Custom Fields. For practices integrated with a Practice Management solution, these details are retrieved from your practice management software for the Primary contact of the client, as displayed on the Client - Summary tab (refer to Client Summary). For practices using New Collaborate, this section includes the "Upload Folder Link" merge field, to insert the website URL to the client's Upload Folder on SharePoint. The Share Folder Link and the Upload Folder Link (in the Client section) should be added to the template that is used to send the email from the Sharing Settings in Client - Collaborate. Refer to Sharing the Share Folder and Upload Folder with Clients and Setting up Collaborate Email Templates.
Client Manager	The details of the user selected as the client's Manager, as displayed on the Client - Summary tab (refer to Client Summary).
Client Partner	The details of the user selected as the client's Partner, as displayed on the Client - Summary tab (refer to Client Summary).
Job	Fields relevant to the Job, including Job Custom Fields.
Job Manager	The details of the user selected as the Job Manager, as displayed on the Job - Summary tab (refer to Job Summary).
Job Partner	The details of the user selected as the Job Partner, as displayed on the Job - Summary tab (refer to Job Summary).
Document	Includes details about the email and attachments, for example the Created Date, and Reference Number (from FYI). For practices using New Collaborate, the Attachment Link Merge Field must be added to any templates used when sharing a document via Collaborate and sending a document as Co-edit with the client. This is added as {{ AttachmentLinks }} to the Template, Refer also to *Sharing Documents with Clients and External Users* and Co-Editing a Document with a Client. Note: The Attachment link will be generated for the email address(es) you choose in FYI when drafting the email. If the email is sent to Outlook and additional recipients are added, these additional recipients will not be able to access the link as it will be generated for the original recipient(s) in FYI.
Document Author	The sender of the email, not the user who created the email. These Merge Fields are only applied when the final sender of the email has been determined, and not displayed when editing the email in FYI. The Author’s details are maintained in the Staff Profile within the practice management software and synchronised to FYI. 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 your practice management software 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 }}. Note: The AuthorPhone and AuthorMobile fields are maintained directly in Xero Practice Manager, and synchronised to FYI.
Document Owner	The creator of the email, not the user that sent the email. For other documents, for example Word or Excel, this will be the user that created the document. Note: If an email is edited and sent by another user after it is initially created, the Owner information will not change. The Owner's details are maintained in the Staff Profile within the practice management software and synchronised to FYI. 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 your practice management software and then synced to FYI.
Tax	The Tax Merge Fields are used in the FYI pre-configured processes for Tax Assessments processes which are triggered by Tax Returns from Xero Tax (refer to Xero Tax Return AutoFile (Australia Only)). When creating a new email, the data from the most recent Tax Return or Assessment is used. Tax Merge Fields are not available to use for Activity Statements. Tax Merge Fields can also be used in automation steps. These will display as Client Tax Merge Fields. Refer to Including Merge Fields in Automations.
Corporate Affairs	Displays the Year Merge Field for documents displayed on the Client - Corporate Affairs tab (ASIC annual statements automatically imported from a third-party system such as BGL CAS 360 or NowInfinity). Refer to Client Corporate Affairs.
Xero Ledger	Merge Fields for Period From, Period To and Year from Xero Ledger can be added.
Other	This section is only displayed if the Signature option is ticked in the Filing section of the Email drawer. The Body Content Merge Field can optionally be added to Email Signatures as a placeholder for where the contents of a template will be included. Refer to Adding the Body Merge Field to Signatures below.
BGL	Available to practices integrated with BGL. Refer to Import from BGL.
Companies House	Available to practices integrated with Companies House. This section includes fields populated during the import. Refer to Import from Companies House.
NowInfinity	Available to practices integrated with NowInfinity. Refer to Import from NowInfinity.
Step	This section is only displayed when adding additional steps to Automations. The Merge Fields available to select are dependent on the previous steps in the process. Refer to Including Merge Fields in Automations.
Trigger	This section is only displayed when creating Automations. The Trigger Merge Field sections available depend on the Filter view, previous steps in the process, your practice integrations and your FYI subscription plan. Refer to Including Merge Fields in Automations.
Formatting	Displays variety of formats that can be added to Merge Fields to modify their appearance or perform a calculation. For more advanced formatting options, refer to Formatting Merge Fields.

Note: There is a known issue where the values are not currently populated for the Merge Fields for Manager Phone, Manager Mobile, Partner Phone and Partner Mobile.

Custom Fields

Custom Fields can be used in Merge Fields, in addition to standard FYI fields. Custom Merge Fields will be located in the relevant sections in the Merge Field window.

For example, a Custom Field configured to apply to both Clients and Jobs will be available to select from both the Client and the Job sections. The Client Merge Field will display the data configured in the Client - Custom Fields tab, while the Job Merge Field will display data from the Job - Custom Fields tab.

Note: Custom Merge Fields using Xero Practice Manager data will only retrieve data from the Client, and not the Job.

To insert Merge Fields into Word or Excel documents, you will need to first obtain the Merge Field name from within FYI, before inserting it into the document following the instructions for the document type.

To find the Merge Field name in FYI:

Open Knowledge - Templates, from the Create Template drop-down select Email.
In the Merge Fields section of the Email Template, click to select a Merge Field you want to include in your document. The Merge Field is added to the body of the Email Template.
Select and copy the code for the Merge Field (Ctrl+c).
Enter the Merge Field following the instructions for the document type. Refer to the articles below:

Using Formats and Calculations with Merge Fields

When using Merge Fields, in addition to displaying content from within the platform, you can also display the content in a particular format, or perform calculations.

To do this, you can insert "formatters" after the Merge Field, which performs the calculations or instructions for how the field should be displayed.

When adding the formatters, the pipe character ( | ) is added by typing the Shift + Backslash (\) key. Ensure that the spaces are added correctly before and after the curly brackets e.g. {{ now }}.

In the example below, the formula determines the start of the quarter based on calculated date next month.

Merge Fields Validation Check

As Merge fields are added, the formatting will be reviewed and a green tick will be displayed underneath. If the format is incorrect, for example, a curly bracket missing, an error will be displayed underneath.

The Validation Check will also be displayed when viewing Templates and Automation Steps using Merge Fields, without needing to open the Merge Field selection window.

For example, when creating an Email Template, the Validation Check will be displayed as follows.

Automations and Job Templates will display an error in the drawer when saving changes to the step or template.

Task Template fields will be validated after clicking into another field.

Examples of using Merge Fields

Note: For practices on the FYI Pro plan, you may see additional fields such as selecting the Job Type in the Create Job step which are relevant to the Elite plan only.

Create Job

Client Views can be used with a custom automation process to create a Job. Refer to Custom Processes using Views and Summary Notifications.

The Create Job process is the same as creating a job using the + button (refer to Create Job in FYI), except that instead of manually selecting a client, the job is created for the clients from the Client View Filter selected in the Automation Process.

Notes:

If using a Job View for the process, Job details will be available in Merge Fields.
For practice integrated with Xero Practice Manager:
- If you select a Template with a Description in the Create Job, the Description from the Template will not be added to the Job that is created. If relevant, you can add the Description directly in the Create Job step.
- The Job Number will be applied when the Job is synced to Xero Practice Manager.
Users cannot use the {{ JobName }} merge field in the Create Job step. If creating the job from a Job View, it will add the triggering jobs name as this value. To add the Job Name as a merge field, users can use an Update Job step as a following step. Refer to Update Job.

Selecting the Client

You can create the Job for the "Current Client" (the Client that triggered the Process) or you can select a specific Client by searching in the Client field.

2496 Process Create Job Select Client.gif

Adding a Job Name

When creating a Job with a Process Step, you can use the Merge Fields to add key details to the Job Name such as Client Name.

In the below image, the Merge Field for Trigger Client Name has been used. This will populate the Client Name and append it to the Job Name.

Job Cabinet

If your practice has Job Cabinet Security enabled in your Practice Settings you can select a Cabinet to assign to the Job. Refer to Managing Practice Settings for Jobs.

If Job Cabinet Security is not enabled in your Practice Settings, the Cabinet field is not displayed in the Create Job Step.

Setting the Start Date or Due Date

When creating a Job with a Process Step, the current behaviour is to set the Start Date or Due Date as the "Current Date", "Month End", or select a specific date. Selecting "Select a Date" displays a pop-up calendar.

In addition to the above options, users can use Merge Fields to select a Date Custom Field to specify the start and due dates. If your Automation is using a Job View, both Client and Trigger Job Date Custom Fields are able to be selected.

In the example below, the client's Lodgement Date custom field is selected as the Due Date when the job is created.

Setting Job Partner and Manager

When setting the Job Partner and Job Manager on a Job, you can use Merge Fields to select the Client Partner and Client Manager as the Job Partner and Job Manager.

The example below is where the Client Manager is pulled from the Client Summary tab when the job is created.

Setting Job Custom Fields

When a Job Custom Field has been selected in the step, this shows as the field name and you are prompted to enter the value to set it to or can select a Merge Field. If you select the Merge Field icon, you can set the value from another custom field.

The example below is where Office is pulled from the Client Custom Field when the job is created.

Setting a Job Custom Field that is a Date

When updating a Job Custom Field that is a Date, this is set as the "Current Date". When clicked, the Merge Field displayed is an advanced formatting rule to retrieve the current date.

For example, the Work Commenced Date can be set to the current date on the Job record as a result of a status being set.

Users can expand their options and use Merge Fields to choose "End of Month" or a Date Custom Field.

Create Jobs using Job Rollover

When creating the same job each year, for example, End of Financial Year Jobs, you can automatically apply the same values as the job from the prior year e.g. the Partner.

This function is only available if the Process Filter Type has been set to a Job View Filter.

For example:

Create a View in the Jobs list of the Jobs for the current year. These are the jobs that will be recreated.
Select the Trigger option in the job fields (found in the Merge Fields selection window) to copy the values from the trigger Jobs to the new Jobs. Refer to Setting up the Create Job Step with Values from the Trigger Job(s) below.
Update any Job Fields that are different for the new job. For example, the Job State would likely be set to "Planned" as the new job has not yet commenced.
Note: If you include the year in the name of your Jobs, you would also need to enter the required Name for all the new Jobs instead of using the value from the trigger Jobs.

You can also use this feature to add a final Create Job step at the end of your Automation Process for Compliance. When the current Job goes to a "Completed" State, the next step can be set up to create a new job for the next financial year.

Setting up the Create Job Step with Values from the Trigger Job(s)

Depending on the Job field, there are different ways in which you can set up the Create Job to use values from the Trigger Job(s).

The values for the Create Job fields for Template, State, Cabinet, Category, Start Date, Due Date, Assigned User (Pro Plan), Manager and Partner include the option in the drop-down "Trigger ... ", for example, select "Trigger State" to copy from the previous job.

The values from the Trigger Job for Create Job fields for Name, Budget and Description can be selected using Merge Fields.

The example below is where Budget Hours, Budget Amount and Description are selected from the Merge Field icon and are pulled from the Trigger Job when the new job is created.

The values from the Trigger Job for the Create Job fields for Custom Fields include an option "Trigger ..." along with the Merge Field icon to select the value from:

You can select the Trigger Office to add the value for Office from the triggering Job when the job is created.
Or, you can select the Merge Field icon and select the Trigger Office from the Client Custom Field when the job is created.

Trigger Template only applies to Jobs created in FYI (Elite Plan).

For Template, using the option Trigger Template will only copy the relevant Template if the triggering Job was created in FYI and not Xero Practice Manager.

For Assigned User, when using Trigger Assigned User, if there are multiple Assigned Users in the triggering Job, currently only the first user will be copied to the new Job.

Update Job

When a Custom Process is filtered on a Jobs view, or on a Documents view and a Job is assigned to the relevant document(s) in the view, you can use Update Job in an Automation Process.

In the Action for Update Job, you select the Job State, Manager or Partner to be set by the process. The Manager or Partner can be set to a specific person in your user list or the Client Partner or Manager. Any of these can be set as "‘Unchanged’ if the State, Manager or Partner are not going to be changed by the process.

The Update Job step can also be used to update one or more Job Custom Fields.

Updating the Current Job or a Specific Job

The Update Job step can be set to update the Current Job (the Job that triggered the automation or a Job created from another step). You can alternatively select a specific Job to update by searching in the Job field.

The values for the Update Job fields for Name, Budget, Start Date and Due Date can be selected using Merge Fields.

When creating a Job with a Process Step, you can use the Merge Field icon to add key details to the Job Name such as Client Name.

For practices integrated with Xero Practice Manager only, the Update Job Step can also be used to update the Name, Budget, Start Date and Due Date.

Note: If your practice has enabled Workflow Jobs, the Name cannot be updated for Workflow Jobs, only for Billing Jobs (refer to the section Workflow Jobs).

Setting the Start Date or Due Date

When updating a Job with a Process Step, the current behaviour is to set the Start Date or Due Date as the "Current Date", "Month End", or select a specific date. Selecting "Select a Date" displays a pop-up calendar.

In the example below, the client's Lodgement Date custom field is selected as the Due Date when the job is updated.

Job Cabinet

If your practice has Job Cabinet Security enabled in your Practice Settings you can select a Cabinet to assign to the Job. Refer to Managing Practice Settings for Jobs.

If Job Cabinet Security is not enabled in your Practice Settings, the Cabinet field is not displayed in the Create Job Step.

Setting Job Custom Fields

The example below is where Office is pulled from the Client Custom Field when the job is created.

Once a Custom Field has been selected, it will be removed from the drop-down list as it is already part of the Step.
You can add additional Custom Fields to be updated by the step. Select the additional Custom Field(s) and add the value to set for each.

Setting a Job Custom Field that is a Date

When updating a Job Custom Field that is a Date, this is set as the "Current Date". An example of this would be updating the Work Commenced Date on the Job record as a result of a status being set.

Users can expand their options and use Merge Fields to choose "End of Month" or a Date Custom Field.

For practices integrated with GreatSoft, the Start Date and Due Date do not display. Budget currently displays but will be hidden in the near future.

Update Client

The Update Client step can be used to update Client Custom Fields.

When a Client Custom Field has been selected from Select Custom Field in the step, the Custom Field will be added directly above. If you wish to apply the value from another Custom Field, select the Merge Field icon and choose the Custom Field for the value to be used.

For example, you can automatically update the Client Custom User Role "accountant" to align with the Job Custom User Role Assignment, ensuring the allocated Accountant is the same in both the job and client workspaces.

Once a Custom Field has been selected, it will be removed from the drop-down list as it is already part of the Step.

Repeat the steps for any additional Custom Fields to be added.

Updating a Client Custom Fields that is a Date

Date custom fields are set automatically to "Current Date" but can be updated to select "Month End" or the value of a Date Custom Field.

For example, a custom process can be created to update the Engagement Date on the client record when the client signs the engagement letter. A view can be used to detect the engagement letter has been signed, and then update a Custom Field such as "Last valid engagement date" in the client record, set to the current date.

Another example could be to record the last date that a partner made contact with a client, triggered when a Phone Call or Meeting interaction is created in FYI. Refer to Internal Reminder to Contact Client.

This process step is not suitable for historical Custom Field dates, such as date of birth.

Create Task

You can use the Create Task step to create a Task and assign it to the relevant user, for example the Job Manager or Partner, or even the user that triggered a manual automation.

Task Template - select a Template if required. The example above shows a task created from a task template to pre-populate the default values for the Task, such as Assignee, Date date, Task Categories and Task Details.

Note: Advanced Task Fields, for example, Priority, Job Category, or Work Type, can only be populated using the selected Task Template. You will not be able to update these fields in the Automation Step.

Subject - enter a brief name for the task. Users can use Merge Fields to add key Client and/or Job details by clicking the icon and selecting the relevant fields. This displays in the lists in FYI.

Assignee - can be set as a specific person in your user list. The Assignee can also be set as "Manager" or "Partner", irrespective of the View being used, to assign the task to the relative client or job manager or partner. If using Custom User Roles, these can be selected using a Merge Field, refer to Managing Mappings. For manual automations, to assign the task to the user that triggered the automation, select User from the Automation Initiator section.

Click the Merge Field icon to select a role.

For a process that is run for a Client, the Manager or Partner is taken from the Client Details.
For a process that is run in the context of a Job, the Manager or Partner is taken from the Job Details.
If there is no Partner/Manager assigned to the client or job, the Assignee is set as "Unassigned".
Custom Fields used for Assigned User Roles can be found by expanding the Trigger Job section.
For manual automations, to assign the task to the user that triggered the automation, select User from the Automation Initiator section.

In the example below, three Custom Fields are displayed for Accountant, Administration, and Bookkeeper.

Due Date - select when the task needs to be completed as the number of days. You can select a number of days, or click the Merge Fields to select "End of Month" or the date from a Date Custom Field.

You can also set this as 0 (zero) days to make the task due immediately.

Status - this defaults to "Not started". The Status can be changed to "In Progress", so when the task is created, nothing needs to be actioned on it.

Cabinet - if Task Security is set in your Practice Settings, a Cabinet can be selected to add Cabinet security to the task. Refer to Managing Tasks.

Blocking - when creating a task, you can set Blocking as "On" so that the process stops until a Task created in the automation process is set as "Completed". This could be used, for example, for a Task created in the process to ensure that an email, word or any other document created in the previous step(s) has been checked before any other actions in the process are done. When the Task is set as "Completed", the process could then be set up to continue and send the checked email or send an email with a checked document attached.

AutoComplete - This is generally not relevant when the Task has not been created for an email or document by the process, or for an Alter Document step in a process. Refer to AutoComplete Tasks.

Details - type the brief details of the task including any Client and Job merge fields using Merge Fields. The assignee can easily display the email or document to see what the task relates to by including the Attachments Links Merge Field.

Features