Merge Fields

Merge fields are a great way for you to personalise messages sent to the end-user. For example, you may wish to address each user by name when sending a group e-mail or simply save yourself the time when writing a canned response!


How Does It Work?

Merge fields make use of the template engine Twig, allowing you to define complex logic when constructing messages that may be sent to the end-user. It is currently possible to use merge fields in the following areas of the help desk:

Our e-mails templates are the perfect starting point to see how we've constructed content-rich e-mails. Below is a simple example of how you may define a merge field:

    Dear {{ user.formatted_name }},

When sent to Joe Bloggs <[email protected]> would be replaced by:

    Dear Joe Bloggs,

Available Merge Fields

To view a list of available merge fields in a given section, click the last icon in the editor. Below is an example of loading the merge fields while editing an email template.

Merge Fields Button

This will open a popup with a full list of available fields, and clicking on the merge field will insert it directly in to the editor. There will usually be a preview or test button which can be used to verify the contents, however note that this usually makes use of test data.

Merge Fields Popup

What's Allowed?

For security reasons merge fields are ran inside a sandbox which only permits specific functionality. The allowed functionality has been detailed below:


Name Example

                    {% if == 'GB' %}
                        We've sent you a welcome pack in the post.
                    {% endif %}

This only shows the text if the user's country is United Kingdom.


                    {% if user.confirmed %}
                        Thank you for confirming you account with us.
                    {% else %}
                        You haven't confirmed your account yet.
                    {% endif %}

This will show a different line if the user's account is confirmed.


                    <h1>Your Groups</h1>
                        {% for group in users.groups %}
                            <li>{{ }}</li>
                        {% endfor %}

This will list all the user's groups.


Name Example

                    {{ [1, 2, 3]|join(', ') }}

This would return "1, 2, 3"


Object Method Example
Collection reverse()

                    {% for message in ticket.messages.reverse() %}

This will reverse all ticket messages so it shows the latest message first.


                    {% for message in ticket.messages.take(5) %}

This will only take the first 5 ticket messages from the whole collection.


The application page includes a list of available merge fields, these are the properties that can be accessed and used, all other properties are not allowed.


Definition Description
formatDate($time, $dateOnly = false) Convert a unix timestamp to a human readable date/time string based on the system configuration.
route() Convert a named route into a URL.
get_logo() Get an absolute path or direct URL to the frontend logo image.
floor() Round fractions down to the next lowest integer.
is_gt($x, $y) Check whether x is greater than y. Use this instead of $x > $y
is_lt($x, $y) Check whether x is less than y. Use this instead of $x < $y

Extending Functionality

Merge fields within SupportPal are governed by a strict security policy; this restricts what is possible and helps to keep your help desk secure.

New Functions

If you would like to make use of a PHP function within merge fields you will first need to define it within the twigbridge.php configuration and then also permit it in the mail security policy.

New Filters, Tags, Methods and Properties

It's possible to add other twig functionality to the mail security policy, this includes: filters, tags, methods and properties. There is no need to define these within the twigbridge configuration, simply permit them in the mail security policy.