This is where you can adjust the notification templates for the account
Whenever a notification triggers, an email is sent to the specified users/user groups/subscribers to notify them. The appearance and content of this email can be customized to fit your needs.
This is available on an account level, which means that changes in the templates will affect all the projects on the account.
This page is also fairly technical in nature - usually only administrators will need to edit mail templates.
The page can be reached from Settings - Other configurations - Notification templates.
Notification format: Select if you want text or HTML notification templates.
Notification templates: The page contain a template chooser dropdown list in the top section. By choosing a template, the other sections will fill up with data. See the available templates below. Note that a couple of templates are specific for support users.
Notification template: This section contain:
- Two radio buttons where you can choose between using the standard default template, or to use the custom template shown in the bottom section. If you use HTML templates, you can choose to view the standard template as normal, or as HTML code.
- Subject : Anything written here will be put into the email subject.
- Content: This will be put into the body of the email.
Help: This section contains a list of available variables that can be used in the mail template. The list is different depending on the template selected in the dropdown list.
Understanding the template:
VisionProject uses a templating language called Velocity for generating dynamic text content. You can see parts of its syntax in the screenshot - IF and FOREACH statements for instance. Read more about Velocity here: http://velocity.apache.org/engine/devel/user-guide.html. VisionProject also has all its text in resource files, and can retrieve these texts by referring to key values.
A list of some constructions in the template:
- #if ..... #end : This is a Velocity if-statement.
- #foreach (a in b) ... #end This is a Velocity repeat statement
- $msg.get("email.viewTheIssue") : This example references the messagehelper to return the text value for the key 'email.viewTheIssue'. All visible text is keyed to different resource keys.
- $url, $issueKey, $issueTitle et.c.. : These are examples of variables that can be used when designing notification templates. For a list, see the 'Help' panel.
A sample template that has different content depending on the status
#if ($!projectIssue.issueStatus.name == "Completed")
The issue with TicketId: $!projectIssue.issueKey is Completed!
#foreach($notificationContent in $notificationContents)
Adding issue custom fields to your email notification templates
Custom fields can be added by writing $!projectIssue.companyCustomField1, $!projectIssue.CompanyCustomField2 etc. into your email notification templates.
You can see the trailing index number of the field, such as 1, 2, or 2, in the General --> "Settings" --> "Issue configuration" --> "Issue fields" by clicking on the Info ? (question mark).
It is recommended to minimize the use of issue custom fields in notifications, unless they are available in all your Issue Field Configurations (IFC). The reason for this is that if some custom issue fields may blank in some projects/notifications otherwise. If you have different issue fields in different projects you would then have to use some kind of if-else logic to show the right field otherwise, such as:
#if("$!projectName" == "MyProjectName")
#elseif("$!projectName" == "AnotherProjectName")
NOte: This matches against the name of the projects. Be sure to use the full name of the project, including capitalisation.
(This will use the customfield2 for the project MyProjectName, and customfield4 for the project AnotherProjectName, and show nothing for other projects)
This is useful when you have the same customfield, but the two different projects use different issue field configurations. (The mapping of custom fields in each configuration is different, thus the different numbers,).
Adding custom notification templates
It is also possible to create and use new custom notification templates, you do this by clicking "Add custom template" in the page above.
This shows a table of custom templates. You can create a new template from scratch or edit the content of an already existing template.
The custom notification templates that you create can then be used in your issue rules, in the General --> Settings --> Issue configuration --> Issue rules --> Notifications tab, by selecting the template to be used from the list.
Note: Please observe that the custom notification templates in this page can currently only be sent out to regular/normal users, not support users (or contacts)!