Merge Fields must be added in a specific format to ensure the data is displayed correctly. In addition, you can also customise the output to display the data in a particular format, or perform calculations.
Merge Field Formats
Types of Brackets
Depending on where the merge fields are being used, the merge fields will need to be inserted using either angled brackets, or curly brackets.
- Angled brackets - « (merge field) »
- Curly brackets - {{ (merge field) }}
Ensure there is a space between the brackets and the merge field.
Where a specific bracket type is required, the articles in FYI will display the Merge Field with the appropriate brackets.
Note: In a spreadsheet, the Merge Fields are inserted using the Excel Merge Names feature and will be displayed without any brackets at all. Ensure you follow the instructions in the article Including Merge Names in Excel Templates to ensure the merge fields function correctly.
Quotation Marks
When entering in advanced formulas for Merge Fields, you may need to enter quotation marks as part of the formula.
For example:
- {{"now" | date: "%d %B %Y"}}
It’s important to note that these formulas use the quotation mark found on the keyboard, and not a Unicode symbol. If the correct quotation marks are not used, it can cause an error or unexpected behaviour in FYI.
Hold shift and press the quotation key on the keyboard to enter this character.
Custom Merge Fields in FYI
If you have set up Custom Fields in your practice management software, UDFs in GreatSoft, or added Custom Fields directly in FYI, you can include Custom Merge Fields in your Automations.
Custom Fields can be used, for example, to distinguish the client type (such as A, B or C grade clients) to record additional address or contact information, or for other indicators. Custom Fields display in the Client - Custom Fields and Job - Custom Fields tabs in FYI.
If Custom Field Grouping has been enabled, the Custom Fields tab will be displayed similar to below. Refer to Grouping Custom Fields
Custom Fields generally follow the format of "(Applies To)_custom_(fieldname)", for example "Client_custom_ClientLevel".
To ensure the field names are inserted correctly, the following rules must be followed:
-
Prefix the Custom Field name with "(Applies To)_custom_"
- The Applies To section is configured for Custom Fields within Practice Settings. For example, a Custom Field may have "Applies To" selected for both Client and Job, but when retrieving the data, to select the Job Custom Field, the Merge Field would be prefixed with "Job_". This must match one of the following:
- Client - prefix of "Client_" e.g. Client_custom_ClientLevel.
- Job - prefix of "Job_" e.g. Job_custom_Accountant.
- Invoice - prefix of "Invoice_" e.g. Invoice_custom_Office.
- Time and Disbursements - prefix of "TimeEntry_" e.g. TimeEntry_custom_Business_Division.
-
Employee - prefix of "Employee_" e.g. Employee_custom_Team.
- The Field name must exactly match the Custom Field name as it appears in FYI, including the same case. Refer to Managing Custom Fields for instructions on how to find the Custom Field name.
- For Custom Field names with spaces, replace the space with an underscore (_).
- Remove special characters from Custom Field names like full stops (.) or any other special characters (such as , or &).
For example, if the following Custom Fields have been enabled for a Client, the Merge Fields would be created as follows:
| Custom Field Name | Example Merge Field Name |
| Types | Client_custom_Types |
| Skype Call | Client_custom_Skype_Call |
| z2.1 Name | Client_custom_z21_Name |
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 Formatting and Calculations
Advanced formatting can be used with Merge Fields entered directly into FYI.
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, as in the examples.
Dates
| 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. If using Merge Field formatting in a Date field, you must use a format with a day, month and year e.g. "%d %b %y". 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" }} To display the timezone, add %z at the end. For example, "%d %b %y %z" would display 31 Mar 23 +1000 |
|
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:
|
|
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). |
Numbers
| Format | Details |
|
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) |
Calculations
| Format | Details |
|
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 }} |
|
Rounding {{ (field) | round }} |
Rounds a number to the nearest whole number. Formatting options:
|
|
Maximum and Minimum {{ (field) | at_least: (number) }} |
Limits numbers to a maximum or minimum range. Formatting options:
|
Formatting
| Format | Details |
|
Conditional Merge Fields {% if custom_Preferred_Name <> '' %} {{ custom_Preferred_Name }} {% else %} {{ Salutation }} {% endif %} |
Used to display a particular field if conditions are met, otherwise display a different field. For example, you can use a conditional merge field if you wanted to use a Custom Merge Field "Preferred_Name" if this was available, otherwise use the Merge Field "Salutation". In this example, you would add these Merge Fields to the Template or Signatures in FYI and then add the conditions as in the example to the left. Replace "custom_Preferred_Name" or "Salutation" in the example as relevant to use different Custom Fields or Merge Fields. |
Text
| Format | Details |
|
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”. |
|
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. |
Combining Merge Field Formatting
When used together, you could create an advanced Merge Field like:
- {{ "now" | add_interval: "1 month" | start_of: "quarter" | date: "%d %B %y" }}
If today's date was the 18th of May 2023, it would:
- Add a month (18th June 2023).
- Determine the start date of that quarter (1st April 2023).
- Format the date (01 April 23).
Microsoft Word Formatting
Today's Date
There are two ways to add 'today's date' to a document via an FYI template or stationery. Use whichever is appropriate if you want the date updated when a document is reopened, or if you want to retain the original creation date.
-
FYI CreatedDate Merge Field
Using the FYI CreatedDate Merge Field adds the current 'today's date' when a document is created from the template/stationery and this original creation date is retained whenever the document is opened or downloaded. This process is covered further below.
-
Office Date field
Using the Date field will add 'today's date' when the document is created from the template/stationery, but it will reset the date to the current date whenever the document is opened or downloaded. Refer to the Microsoft article Insert today's date in a Word document.
Formatting the CreatedDate Merge Field
You can add a switch to the Merge Field to format the date. This allows you to set it to display, for example, as 5 Feb 2021, as 5 February 2021, Friday, 5 February 2021, etc.
- Edit the Word Template or Stationery using the desktop version of Word.
- Right-click over the CreatedDate merge field.
- From the Word pop-up menu, select Toggle Field Codes.
The Merge Fields displays as a code in your Word document and shows as follows:
{MERGEFIELD CreatedDate }
or as
{MERGEFIELD CreatedDate \* MERGEFORMAT} - Add the formatting switch using the examples below.
Ensure there is a space after the word CreatedDate, after the opening bracket { and before the closing bracket }.
If \* MERGEFORMAT is shown, the switch should replace this.
| Merge Field Code |
Displayed Result (for a date 5th February 2021) |
| { MERGEFIELD CreatedDate \@ “dddd, d MMMM yyyy” } | Friday, 5 February 2021 |
| { MERGEFIELD CreatedDate \@ “ddd, d MMMM yyyy” } | Fri, 5 February 2021 |
| { MERGEFIELD CreatedDate \@ “d MMM yyyy” } | 5 Feb 21 |
| { MERGEFIELD CreatedDate \@ “MMM d yyyy” } | Feb 5 21 |
| { MERGEFIELD CreatedDate \@ “dd/MM/yy” } | 05/02/21 |
Note: In the Word formatting, m is used for minutes in a date/time field. Use M (capital M) for month.
Office Date Field
To include the Office "Date" Field:
- From the Word ribbon menu select Insert - Quick Parts - Field
- In the list of Field names, select the field "Date".
- Select the format required.
- Click OK to add the field.
Conditional Merge Fields
Word supports conditional merge fields.
Note: The following example shows a Custom Field with the prefix custom_
For example, you can use a conditional merge field if you wanted to use a Custom Merge Field "Preferred_Name" if this was available, or if not use the Merge Field "Salutation".
| Microsoft Word Conditional Merge Field | Description |
| { IF { MERGEFIELD custom_Preferred_Name } = "" { MERGEFIELD Salutation }{ MERGEFIELD custom_Preferred_Name } \* MERGEFORMAT} | If the Merge Field “Preferred Name” is available use that, but if not, use the Merge Field “Salutation”. |
| { IF { MERGEFIELD BusinessStructure \* MERGEFORMAT } = "Individual" "{ MERGEFIELD Addressee \* MERGEFORMAT }" "{ MERGEFIELD Addressee \* MERGEFORMAT } { MERGEFIELD ClientName \* MERGEFORMAT }" } |
If the Business Structure is an individual then use the Addressee field. For all other Business Structures, display the Addressee Field (Primary Contact’s details) and then the Client Name (Company Name). |
| { IF { MERGEFIELD PostalAddress } = "" "{ MERGEFIELD StreetAddress }" "{ MERGEFIELD PostalAddress }" } |
If the Postal Address is not populated then use the Street Address instead. |
Note: You need to right-click and use the Word function Toggle Field Codes to see the conditions. When Field codes are not enabled, the example above would show as Dear «XPM_Preferred_Name»
Replace "custom_Client_Level" in the example above as relevant to use different Custom Fields or Merge Fields.
Refer to Microsoft Word help for more information on using conditional merge fields.
Microsoft Excel Formatting
Today's Date
You can add 'today's date' to a spreadsheet using the FYI Merge Field Current Date or via an Excel template using the Excel TODAY function.
- Add the FYI Created Date Merge Field.
Using the FYI CreatedDate Merge Field, adds the current date when a document created from the template. This original creation date is retained whenever the document is opened or downloaded.
- Excel TODAY function.
Using the Excel =TODAY() function will add 'today's date' when the spreadsheet is created from the template, but it will reset the date to the current date whenever the spreadsheet is opened or downloaded.