SupportPal Docs

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!

Contents

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:

Tags

Name Example
IF 

                    {% if user.country == '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.
ELSE 

                    {% 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.
FOR 

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

This will list all the user's groups.

Filters

Name Example
join 

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

This would return "1, 2, 3"

Methods

Object Method Example
Collection reverse() 

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

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

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

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

Properties

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.

Functions

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.