Notification Templates
Notification Templates provide you with tools to customize email and Jabber notifications to suit your user communication requirements. You can edit the default Freemarker-based templates: add your own subject, change the language, and tailor the message text.
The default notification templates present key components of each message in a format that is easy to scan in a message preview. Most recipients don't even need to open an email notification to stay up to date. The components in the email headers are also optimized so users can filter their inbox and collect YouTrack notifications in dedicated folders.
That said, the email client that you use in your organization might not present this information in a friendly way. To modify the format of your email messages, customize your notification templates.
Customizable templates are available in the page in YouTrack.
The Notification Templates page displays a list of templates. Each item in the list can be expanded to view and edit the template components. Template components are actual Freemarker .ftl files that are used as "building blocks" for messages.
Notification Schemes
YouTrack supports two different notification schemes — two algorithms which define the number of notifications sent by youTrack and the content of each message.
Scheme | Description |
|---|---|
Digest | One notification is sent about all all simultaneous changes in an issue. |
Granular | Separate notification is sent about changes of each type (issue created, tagged, commented, voted, unresolved, and updated). For example, even if a user changes two issue fields and simultaneously comment this change, two notification are sent: one about updated fields and another one about the comment. |
What are Simultaneous Changes in the Digest Scheme?
When the Digest scheme is enabled, issue changes for a single notification are collected as follows:
While a user makes changes to an issue until the first pause of 1 minutes in his actions.
While a user updates an issue until another user interrupts, and start to make changes to the same issue.
That is, if John Doe updates issue TS-1, and his colleague, let's say Jane Doe, distracts him so he doesn't do anything with the issue within a minute, then the notification will be sent about any changes he made to TS-1 before the distraction.
The similar situation is when John Doe is updating the issue TS-1 and someone (his rival, probably) starts to update the TS-1 at the same time. As soon as another user's changes are registered, the notification about changes made by John Doe until that moment are sent.
Edit Notifications and Template Components
Notification templates are available for notifications sent by email and Jabber. To update template for a specific protocol, just make changes in the corresponding branch of the notification template "tree": expand either or , respectively.
Prerequisite Knowledge
In majority of use cases, you you only need to edit the template text. If you want to tailor the notification and modify its appearance, you should be familiar with Freemarker syntax.
To edit a notification template:
Expand the item in the Notifications list.
Open a template component (an <component_name>.ftl file)
Make the desired changes.
The following controls are available for editing notification templates:
Control | Description |
|---|---|
Available Variables | Lists the variables that can be used in this template. For more information, see Custom Notifications Language Reference. |
Save changes | Saves the current changes. |
Undo | Reverts the most recent change. |
Redo | Restores the most recently reverted change. |
Reset to default | Discards all current and previously saved changes and restores the default notification. |
Preview and Test Changes
To view how your changes affect a template or a template component, select an issue in the Issue selected for preview dropdown list. When you select a notification from the list, a preview that contains data from the selected issue is shown in the Details sidebar.
Along with the preview that shows changes in the browser window, you can also see your changes in your email or jabber client. Select the Email or Jabber branch of a template and click the Send test email or Send test Jabber button in the toolbar.