Chapter 7. Message Templates

Templates are provided for the sending of messages (notifications) from the component. Generally they are mainly used for email notifications, but there are also some specific SMS templates. The templates are accessed from the back end of the site from the component Message (Email) tab.

Figure 7.1. Message Listing

Message Listing

Email and SMS generation is controlled via the configuration options, and makes use of the message types as show in the figure above. The ‘email type’ (message_type) name is hard coded into the component, but all other settings are configurable by the administrator. The description field as suggested by its name provides a descriptive explanation of the purpose of the email type.

The message type name is important since it has to be unique and is used within the code to initiate the sending of the specific email type. Additional message types are likely to be introduced in latest releases.

Figure 7.2. Message Template Edit (1)

Message Template Edit (1)

The figure above illustrates the top of the ‘message template edit’ screen. The subject field reflects message subject field that is presented in the generated messages. Of more importance is the actual body of the message which is shown in the figure below. The body makes use of HTML codes, as the generated message is in HTML format. Consequently it is possible to make the text as attractive and detailed as is required.

The details of the issue are inserted into the message body by the use of ‘tags’. These tags are substituted into the message body prior to sending.

Figure 7.3. Message Template Edit (2)

Message Template Edit (2)

Tags are entered by using the words identified in the Email Template Tags table below surrounded by braces. The tags must be entered in lowercase letters otherwise they will not be recognised. Tags can be used in the subject field or in the body of the email. There is no limit to the number of tags that can be used and a tag may be used more than once, although this is often not required.

As supplied the message templates are very basic in that they do not contain any form of formating. This does not mean however that they can not be formatted by adding any required CSS that may be required by a site. On our own site we have added some simple CSS rules which are illustrated below for a user notification upon a new issue being created:

<div style="background-color: #e0e0e0; padding: 10px 20px;">
<div style="background-color: #f9f9f9; border-radius: 10px; padding: 5px 10px;">
<div style="height: 50px;">
<h3><img style="float: right;" alt="macrotone" src="/images/macrotone.png" height="72" width="200" />Issue Tracker Issue Notification</h3>
</div>
<p>Thank you for submitting your issue.</p>
<p>You can view or update [requires login] the issue at: [url]</p>
<p><span style="text-decoration: underline;"></span></p>
<p><span style="text-decoration: underline;">ISSUE DETAILS</span></p>
<p>ID: [issue_id]</p>
<p>User: [user_name]</p>
<p>Date: [startdate]</p>
<p>Title: [title]</p>
<p></p>
<p><span style="text-decoration: underline;">DESCRIPTION</span></p>
<p>[description]</p>
</div>
</div>
<p style="font-size: x-small; color: #999;">You are receiving this email message because you (or someone on your behalf) has indicated you are the 
identifier of issue [issue_id] against the [project] project on <em>macrotoneconsulting.co.uk</em>.</p>
<p style="text-align: right; font-size: 7pt; color: #ccc;">Powered by 
<a href="/index.php/Macrotone/issue-tracker-component.html" style="color: #ccf; text-decoration: none;">Macrotone Issue Tracker System</a></p>

The effect of applying the above CSS to the message template is shown below:

Figure 7.4. Sample CSS applied to message template.

Sample CSS applied to message template.

The above is a sample only and the site administrator will wish to modify the template to best suit the needs of the specific site. It does however serve as an example of the very simple changes that can be made to 'improve' the look of the notifications.

Messages and Notifications

A number of templates have been provided to be used for generation of the email and SMS messages which are sent when an issue is opened, closed or updated. An update is considered to be any change where the issue state is not ‘open’, or ‘closed’. These states are defined in the component parameters. This information builds upon the details provided in the User Guide.

There are also a few miscellaneous templates used for specific tasks.

Table 7.1. Email templates.

Name

Notes

ass_close

Used when sending an email message indicating an issue assigned to the email recipient.

ass_new

Used when sending an email message to the issue assignee when an issue is assigned to the email recipient.

ass_update

Used when sending an email message indicating an issue update to the issue assignee.

user_close

Used when sending an email message to the issue assignee when an issue is assigned to the email recipient.

user_new

Used when sending an email message to the issue identifier when the issue is opened.

user_update

Used for sending an email message to the issue raiser when the issue is updated.

admin_close

Used when sending an email message indicating an issue closure to the issue system administrators.

admin_new

Used when sending an email message to the issue administrators when an issue is initially created.

admin_update

Used when sending an email message indicating an issue update to the issue administrators.

sms_close

Used when sending a SMS message when an issue is closed. The same template is used irrespective of recipient due mainly to the limitation of the size of the message that may be send.

sms_new

Used when sending a SMS new message when an issue is initially created. The same template is used irrespective of recipient due mainly to the limitation of the size of the message that may be send.

sms_update

Used when sending a SMS update message to a recipient. The same template is used irrespective of recipient due mainly to the limitation of the size of the message that may be send.

auto_close

Used when sending an email message indicating an issue closed by the auto-close cron system to the issue originator/creator.


The templates make use of substituted values where the details associated with the specific issue referred to in the message. The supplied email templates are larger than those supplied for SMS messages, mainly because SMS messages tend to be shorter and more concise that email messages.

The tags are represented by the string name indicated in the table below surrounded by square braces ‘[]’.

The template once updated with the specific issue values is then amended by adding the header detail and trailing detail as specified in the component options.

Table 7.2. Email template tags usable in generated notification messages.

Name

Source

url

Hard coded in routine. The URL to use for appending to the site name to provide a link to the specific issue.

issue_id

The alias of the issue (issue number).

title

The issue summary (or title) for the issue.

description

The issue description field.

user_name

The name of the user who identified (or raised) the issue, if not specified. If a guest user raised the issue then their details will have been captured and will be used, other wise the user identified as opening the issue will be used.

user_email

The email address of the user who raised the issue. See user_name above.

user_fullname

The full name of the user who raised the issue. See user_name above.

progress

The details of the progress field of the issue.

project

The name of the project to which the issue is attributed.

priority

The priority associated with the issue.

startdate

The date when the issue was identified.

closedate

The date when the issue was closed.

assignee_fullname

The full name of the person who is assigned to work the issue.

assignee_email

The email address of the person assigned to work the issue.

assignee_uname

The username of the person assigned to work the issue.

resolution

The resolution text of the issue.

status

The status of the issue.


[Note]Note

All fields should be specified in lower case. Mixed case is not supported currently.

The notifications have a number of inbuilt rules which prevent emails from being sent in certain circumstances. They are briefly:

  • An assignee email is not generated if the assignee is the one creating the issue.

  • Issue administrators are not sent emails if an issue administrator is creating an issue.

  • If an issue administrator is closing an issue then no issue administrators are not sent an email.

  • If an assignee is closing or updating an issue they are not sent an email.

  • If an issue administrator is updating an issue, then issue administrators are not sent emails.

Use of Custom Field tags

Release 1.6.7 introduced the ability to specify tags such that custom fields can be inserted into out going message notifications.

The mechanism is to place a tag in the email template such as [CFIELDx] where x is the id (number) of the custom field. When discovered the tag in the template is replaced with the 'field name' followed by a colon, a space and then the specified field value. For 'header' custom field types only the custom field name is inserted into the template.

[Note]Note

The tag used for custom fields is in upper case, NOT lower case which is the situation for the general tags. This is deliberate and intended to make them 'stand out' in the template.

Only custom field ids that are part of a group that is associated with the project, for which the issue is associated are valid for insertion into a message template.

If an invalid custom field identifier is specified, as would be the situation were the wrong or an invalid custom field id is used, then the entire custom field tag is removed from the outgoing notification. An informative message is inserted into the component log notifying the system of this situation. By clearing out the invalid tag we ensure that the outgoing message is 'clean'. This also enables the use of the same email template with different projects, for which different custom fields may apply.

[Note]Note

We have chosen to only implement the use of tags in the body section of the message. The limitation on the length of a message header, means that it is unlikely that one would wish to place custom fields into the message header.

See RFC 2822, section 2.1.1 states:

There are two limits that this standard places on the number of characters in a line. Each line of characters MUST be no more than 998 characters, and SHOULD be no more than 78 characters, excluding the CRLF.

Note also that some email systems enforce a lower limit upon the subject length.

Table 7.3. Email template custom field tags - typical output.

Tag

Output example

Notes

CFIELD1

Product Details

This is a sample cf header field. [This is one of the default provided field.]

CFIELD5

Database Type: MySQL

This is a sample cf radio field. [This is one of the default provided field.]

CFIELD6

Database Version: any

This is a sample cf text field. [This is one of the default provided field.]

CFIELD24

DDDDD: 2015-02-19

This is a sample cf date field. We chose a name of DDDD for simplicity.

CFIELD25

EEEE: Second, Third

This is a sample checkbox field - multiple selection. Note we separate values by a comma. We chose a name of EEEE and provided three possible values of which we selected two.

CFIELD10

Output when an invalid field id is provided. Note that this is blank! On our test system this id is not used so we ensured that it was not valid.

CFIELD27

Select: BBBBB

This is a sample cf select field. We chose a name of 'Select', with possible selected values of AAAA, BBBB and CCCC, of which we chose the centre BBBB value.


Go To Top

The Macrotone Consulting Web site would like to use cookies to store information on your computer, to improve our website. Cookies used for the essential operation of the site have already been set. To find out more about the cookies we use and how to delete them, see our Privacy Policy.

I accept cookies from this site.