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.
Please note: This is currently only 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.
This page can be reached from Settings - Other configurations - 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.
Notification template: This section contains two radio buttons where you can choose between using the standard default template, or to use the custom template shown in the bottom section.
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:
VisionFlow 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. VisionFlow 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(statement) ..... #end : This is a Velocity if-statement. The text in between will only show if the statement is true. You can also use #elseif and #else.
- Example: #if(...) AAA #elseif (...) BBB #else CCCC #end
- #foreach (a in b) ... #end This is a Velocity repeat statement where a is an element in an array or list b.
- $msg.get("email.viewTheIssue") : This example references the messagehelper method to return the text value for the key 'email.viewTheIssue'. All existing visible text in the system is keyed to different resource keys. Note that you can only reference keys for existing text resources. You cannot make up your own keys ,like "some.bogus.text.here".
- $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.
- $variable vs $!variable : If a variable is referenced including the exclamation mark, it will not be shown if it is blank/null. Otherwise the variable name will be printed.
- if a variable is null, then $variable will print "$variable" while $!variable will print "" (i.e. nothing)
How do I include all issue custom fields in my email template:
By adding the following code snippet you can add all your custom fields on your issue on to the notification:
#foreach($projectIssueCustomField in $projectIssueCustomFields)
#set ($currentCompanyCustomFieldValue = $projectIssue.getCompanyCustomFieldValue($projectIssueCustomField.customFieldIndex))
$projectIssueCustomField.displayName : $!currentCompanyCustomFieldValue
How do I include all user custom fields in my email template:
Use the format $!creatorCustomFields.textField1
Use the format $!creatorCustomFields.textField2
Use the format $!creatorCustomFields.textField3
And so on...
Validation of notifications templates
If you make invalid changes to a notification template it may not work and email notifications may fail.
To limit the risk of the notification breaking there is a validation of the template when you save it. If you try to save an invalid template you will get the error: "Notification template contains invalid template code. Please adjust the template and try to save it again."
If this happens you must adjust the template and fix the velocity code to be able to save the template.
One of the most common causes for this is that there are code constructions missing an #end tag.
(Note that this error message can also show when sending/replying to an email that contains faulty template code, - or - something that the system interprets as code, such as something with a hash mark.)