Universal Merge Fields (UMF) further increase the power of automations, by allowing users to apply details from a client to a job and vice versa using an automation step.
This feature is now available to all practices, refer to Announcing the release of Universal Merge Fields
Use Universal Merge Fields to:
- Inherit Client Custom Fields directly onto a Create Job step.
- Set the Job Partner and Job Manager from Client Partner and Client Manager fields.
- Apply key job details from the original job when rolling over new jobs.
- Use Client or Document fields for a Job Name.
- 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 Universal Merge Fields tie into existing processes that utilise synchronisation between XPM and FYI. Refer to Xero Practice Manager Rate Limiting.
Using Universal Merge Fields
Universal Merge Fields are available in any automation step that displays the below icon.
- Click on the UMF icon alongside the field you wish to insert Universal Merge Fields for.
- The available merge fields will be displayed, grouped by where the data is pulled from.
- Select the relevant heading to expand the available options or use the "Filter merge fields" to search for merge fields by typing in a few characters to display relevant options. For example, type "Name" to search for the {{ TriggerClientName }} merge field.
- Click the UMF you wish to use and it will automatically be inserted on the left-hand side, in the correct format.
- 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.
- Merge Fields can be combined with text, for example, Annual Compliance {{ TriggerClientName }}.
- If the UMF format tick is green, click Save. The UMF displays in the relevant field in the correct format. In the example below, when the Job is created, the name of the Job will be Annual Compliance followed by the Client Name.
- When saving the Automation Step, if an Invalid Merge Field Format error is displayed, review each field for formatting, then click Save. The formatting will be checked, and if valid, the step will be saved.
Note: If Universal Merge Fields are not available within a step, the following warning will display:
Universal 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.
Advanced Merge Fields and Formatting
For more advanced merge fields, you can use formatters and even add text or perform calculations.
When adding the formatters, the pipe character ( | ) is added by typing the Shift + Backslash (\) key. Ensure that the spaces are added correctly as in the examples.
Note: Pasting the formula into an Office app may change the quotation marks to a right-angle quotes character, which causes an error when the formula is used in FYI. If you encounter an error, try replacing the quotation marks using the character ". Hold shift and press the quotation key to enter this character.
Advanced Merge Fields are listed below.
| Format | Details |
|
Current date {{ "now" }} |
Returns the current date and time, and must be combined with date formatting (as discussed in the next row). Your location controls which timezone is used to display the date, either AEST (Australian Eastern Standard Time) or GMT (Greenwich Mean Time). |
|
Format dates {{ "now" | date: "%d %B %Y" }} |
Used to modify how the date is displayed. You can use any combination of the Formatting options, for example, use only the month, or month and year. Formatting options:
Use capitals for the month or the year to display the full month text and year. For example, to include the custom merge field "Job Start Date" from Xero Practice Manager, with the full month and year displayed, the following merge field would be added to the email template: {{ custom_Job_Start_Date | date: "%d %B %Y" }} |
|
Format numbers {{ (field) | comma_group }} |
Used to modify how a number is displayed, to control whether commas are used, or if brackets are used to indicate negative numbers. Formatting options, using 1000 or -1000 as an example:
Filters can be chained, but the grouping filter needs to go before the negative filter in the list, for example: {{ "Merge Field" | comma_group | negative_parens }} to format as (1,000,123.00) |
|
add_interval {{ "now" | add_interval: "1 day" }} |
Calculates a new date by adding/subtracting a specified time period, referred to as an "Interval". This can be used for:
Requirements for using the interval
|
|
start_of {{ "now" | start_of: "quarter" | date: "%d %B %y" }}
|
Change a date to the start of a specified period - month, quarter, or year. For example, if you had a job that was to be created at the start of each month. Requirements for using start_of:
|
|
end_of {{ "now" | end_of: "quarter" | date: "%d %B %y" }} |
Change a date to be the end of a selected period - month, quarter, or year. For example, if you wanted to enter a due date for the end of the month. Requirements for using end_of:
|
|
Constant Date "2023-03-01" |
Used to enter a specific date. This can be combined with the formatters above. For example, entering {{"2023-05-18" | start_of: "year" | date: "%d-%m-%y"}} would result in the date 01-01-23 (the first day of the year, formatted as d-m-y). |
|
url_encode {{ ClientName | url_encode }} |
Converts any URL-unsafe characters to allow merge fields to be used as part of a website address. E.g. the Client Name “Cobb & Co” would become “Cobb+&26+Co”. |
|
Multiplying values {{ (field) | times: (value) }}
|
Multiplies the field by the amount specified. e.g. {{ Trigger_custom_Engagement_Budget | times: 1.03 }} Can be combined with "round" to multiply and round to a whole number e.g. {{ Trigger_custom_Engagement_Budget | times: 1.03 | round }} |
|
Dividing values {{ (field) | divided_by: (value) }} |
Divides the field by the value specified. e.g. e.g. {{ Trigger_custom_Engagement_Budget | divided_by: 1.03 }} Can be combined with "round" to divide and round to a whole number e.g. {{ Trigger_custom_Engagement_Budget | divided_by: 1.03 | round }} |
|
Round {{ (field) | times: 1.03 | round }}
|
Used to round to a whole number e.g. 2.7 would be rounded to 3, 1.2 would be rounded to 1.
|
|
split: {{ AuthorName | split: " " | first }} |
Used to split the data by specified characters, keeping the first part of the data before the split. For example, entering {{ AuthorName | split: " " | first }} will split the name where there are spaces, and keep only the first part of the name. |
When used together, you could create an advanced Merge Field like:
- {{ "now" | add_interval: "1 month" | start_of: "quarter" | date: "%d %B %y" }}
Examples of using Universal Merge Fields
Note: For practices on the 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.
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 Universal 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.
Adding a Job Name
When creating a Job with a Process Step, you can use the Universal Merge Fields to add key details to the Job Name such as Client Name.
In the below image, the UMF 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 Universal 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 Universal 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 UMF. If you select the Universal 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 Universal Merge Fields to choose "End of Month" or a Date Custom Field.
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 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 Universal Merge Fields.
The example below is where Budget Hours, Budget Amount and Description are selected from the UMF 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 UMF 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 UMF 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.
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 Universal Merge Fields.
When creating a Job with a Process Step, you can use the UMF 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 addition to the above options, users can use Universal 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 can be selected.
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
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 UMF. If you select the Universal 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.
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 Universal 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.
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 Universal 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.
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 Universal 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 Universal 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 Universal 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 Universal 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 Universal Merge Fields. The assignee can easily display the email or document to see what the task relates to by including the Attachments Links UMF.