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 text above.
See also the Issue Tracker Customisation Guide for more details.
There are also a few miscellaneous templates used for specific tasks.
Table 8.1. Message 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. |
summary_report |
Used for the scheduled summary report, dispatched via a scheduled cron task. ~Intended mainly for issue administrators to provide an overview of recent activity. If not present the summary report uses a predefined format. |
overdue_report |
Used by the scheduled overdue con tasks to keep issue assignees informed of issues that have exceeded the defined activity periods. If the template is not present then the task uses its own internal format. |
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 8.2. Message 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. |
REPORT |
A special tag used by the scheduled report tasks: summary and overdue reports. Note this tag is in upper case to differentiate it from the other field tags. |
![[Note]](/media/com_docimport/admonition/note.png) | Note |
|---|---|
|
All fields should be specified in lower case, with the exception of the Custom field tags and the REPORT tag. 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.
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 message 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.
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 message template with different projects, for which different custom fields may apply.
| 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 8.3. Message 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. |