YouTrack Server 2023.3 Help

Notification Templates

Notification Templates provide you with tools to customize email 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.

You can modify the email messages that are sent by YouTrack by customizing your notification templates. These templates are available from the Notification Templates page, which is accessible from the Notifications tab on the Global Settings page.

Notification templates administration

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.

Simultaneous Changes

YouTrack follows a digest scheme for notifications. This is intended to reduce the amount of notification spam that is generated by the application. Issue changes for a single notification are tracked and collected as follows:

  • Notifications for updates made by a single user paused for one minute. Each change made by this user resets the counter until a full minute has passed. After that, a single notification is generated that contains the entire collection of changes made by this user.

  • If another user applies changes to the same issue, another counter is started. From this point, whichever user goes a full minute without resetting their corresponding counter generates a notification. Any unsent notifications for changes that were applied by other users prior to the event that generates a notification are collected and sent as a separate notification.

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 notifications about changes made by John Doe until that moment are sent.

Edit Notification Templates

Notification templates are available for notifications sent by email. To update template for a specific protocol, open and edit the corresponding file.

Edit notification template

To edit a notification template:

  1. From the Administration menu, select Server Settings > Global Settings.

  2. Select the Notifications tab.

  3. Scroll to the bottom of the page and click the Configure notification templates link.

  4. Locate the message component that you want to modify. For components that are integrated into specific message templates, expand the item in the Notifications list.

  5. Click the name of the template component that you want to edit (a <component_name>.ftl file).

  6. Make the desired changes in the message template editor.

  7. Click the Save changes button in the header.

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 Local Variables.

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 message button in the toolbar.

Local Variables

Local variables can be used but not changed by the user. Local variables are predefined and read-only.

Local Variable

Type

Description

header

string

The header of a notification. Represents a short text which identifies the notification type. The following values are available: Created, Assigned, Updated, Commented, Resolved, Tagged, Voted, and so on. This variable is used in the default email subject template.

from

User

Represents notification sender's details

to

User

Represents notification recipient's details

application.name

string

Evaluates to "YouTrack"

application.version

string

Evaluates to the current version

application.build

string

Evaluates to build number

reason

string

Evaluates to description of the reason a user receives notification. Description form differs in jabber and email notifications.

issue

Issue

Evaluates to an issue, about which the notification is sent.

change

IssueChange

Contains info about changes (issue project, summary, description, custom fields, visibility group, links, attachments) that initiated notification.

comment

Comment

Evaluates to an edited or posted comment, about which notification is sent.

comment_updated

boolean

true - a comment has been edited, false - a new comment has been posted

tag

Tag

Evaluates to an tag, which has been added to or removed from an issue.

untag

boolean

indicator that issue has been tagged/untagged

unvote

boolean

indicates that issue has been voted/unvoted

project

Project

Imported project or project failed to import (id, full name, issues, leader...). Variable is used in the "Import status" notification.

exception

Throwable

Java Throwable object

message

string

text of the message in the "Import status" notification.

Directives

You use FTL tags to call directives. Besides built-in directives like the #list directive, you can define your own directives in Freemarker. For more information, see the User-Defined directives manual.

  • wiki - process embedded text using Wiki syntax and keywords. Directive applies HTML escaping.

    • parameter - no parameters

    • body - text to process

Example:

@wikisolidhtml <#escape x as x?html> ... <@wiki><#noescape>${comment.text}</#noescape></@wiki> ... </#escape x as x?html>
  • diff - render an HTML element that highlights changes applied to text. Deleted and added sections of text are marked with different styles.

    • parameters:

      • oldText - old version of text

      • newText - new version of text

      • insStyle - HTML style of inserted text

      • delStyle - HTML style of deleted text

    • body - no body

Example:

@diffsolidhtml <@diff oldText=change.before.summary newText=change.after.summary insStyle="background-color: #E6FFE6;" delStyle="background-color: #FFE6E6;"/>
  • stacktrace render the html component representing stacktrace of Throwable

    • parameters:

      • throwable - instance of Throwable Java class

    • body - no body

Example:

@stacktracesolidhtml <div><pre><@stacktrace throwable=exception/></pre></div>

Utils

  • When the type assigned to a returned value is list<?>, you can iterate over the result using the #list directive.

Method Summary

static string

getAttachmentUrl (Attachment attachment)

returns the URL for the attachment resource

static string

getAvatarUrl (User user)

returns the URL for the user avatar

static string

getCommentReplyUrl (Comment comment)

returns the URL of a web page with Issue view focused on reply text area

static string

getCommentUrl (Comment comment)

returns the URL of a web page with Issue view focused on comment

static list<ProjectCustomField>

getCustomFields (Issue issue)

returns a list of custom fields of issue

static Issue

getDuplicate (Issue source)

returns issue duplicated by the source issue, if there is no such issue returns null

static string

getEditProjectUrl (Project project)

returns the URL of a web page in Administration where you can edit project

static list<Tag>

getExplicitTags (Issue issue)

returns a list of tags of issue except tag 'Star' visible for notification recipient

static int

getInvisibleAttachmentsCount (Issue issue)

returns the number of issue attachments that are not visible to the notification recipient

static string

getIssuesUrl (Project project)

returns the URL of a web page with the Issues list opened in context of a project

static string

getJiraIntegrationUrl ()

returns the URL of a web page in Administration where you set up Jira integration

static list<Issue>

getLinkedIssues (Issue source, string linkRole)

linkRole the name of the issue link type (for example, Relates, Duplicate)

returns a list of issues linked to the source issue using the specified linkRole

static list<string>

getLinkRoles (Issue source)

returns all possible roles of links of the source issue

static string

getPossessiveName (User you, User from)

returns "you" if you and from is the same user, and from user presentation otherwise

static string

getResolveStatus (Issue issue)

returns "resolved" if issue has been resolved and "" otherwise

static string

getSettingUrl (User user)

return URL of web page with user profile setting focused on the "Filters and Notifications" tab

static string

getStarSrc (Issue issue) return URL of 'Star' tag image resource

static string

getTaggedIssuesUrl (Tag tag)

returns the URL of a web page with the Issues list opened in context of tagged by tag issues

static string

getTrimmedTagName (Tag tag)

return tag name restricted by 25 chars length

static string

getUrl (Issue issue)

returns the URL of a web page with issue

static list<Attachment>

getVisibleAttachments (Issue issue)

return list of issue's attachments visible for notification recipient

static boolean

hasLinks (Issue issue)

returns either issue has any links or not

static string

inUserTimeZone (instant time)

returns a time value in human-readable format converted to the local time zone of the message recipient

static boolean

isFixed (Issue issue)

returns either issue has been fixed or not

Last modified: 22 March 2024