Icon

You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: related to https://youtrack.jetbrains.com/issue/TW-58477

TeamCity users can select the events to be notified about. The default notification messages can be customized globally on a per-server basis. Customizing notifications received via Atom/RSS syndication feeds requires a special approach since the feeds use the "pull" model for receiving notifications instead of "push".

On this page:

Table of Contents
Wiki Markup{hidden-data} This does not relates to customizing notifications\! h2. Supported Notifiers || Notifier || Description || | *Email Notifier* \\ |

Notifications

...

Notifications Lifecycle

TeamCity supports a set of events that can generate user notifications (such as build failures, investigation state changes, etc). On an event occurrence, for each notifier type, TeamCity processes notification settings for all the users to determine which users to notify.

When the set of users is determined, TeamCity fills the notification model (the objects relevant to the notification, such as as "build", investigation data, etc.) and evaluates a notification template that corresponds to the notification event.
The template uses the data model objects to generate the output values (e.g. notification message text). The output values are then used by the notifier to send the message. Each notifier supports a specific set of the output values.

Please note that the template is evaluated once for an event which means that notification properties cannot be adjusted on a per-user basis.

...

Notification Templates Location

Each of the bundled notifier notifiers has a directory under in <TeamCity data directory>/config/_notifications/, which stores FreeMarker (.ftl) templates. There are also .dist files that store the default templates. Each notification type evaluates a template file with a corresponding name. The template files can be modified while the server is running.

Anchor
changesCheck
changesCheck
By default, the server checks for changes in the files each every 60 seconds, but this can be changed by setting the teamcity.notification.template.update.interval internal property to the desired number of seconds.

If there If an error occurs an error during the template evaluation, TeamCity logs the error details into to teamcity-notifications.log. There can be non-critical errors that result in ignoring part of the template or critical errors that result in inability the inability to send notification at all. Whenever you make changes to the notification templates please ensure the notification can still be sent.

Anchor
modifyFreemarker
modifyFreemarker

This document doesn't describe the FreeMarker template language, so if you need a guidance on the FreeMarker syntax, please refer to the corresponding template manual at http://freemarker.org/docs/dgui.html.

...

(i)The Atom/RSS feeds template differs from the others. For the details, please refer to the dedicated section.

Customization Examples

This section provides Freemaker code snippets that can be used for customization of notifications:

...

For the template evaluation, TeamCity provides the default data model that can be used inside the template. The objects exposed in the model are instances of the corresponding classes from TeamCity server-side open API.
The set of available objects model differs for different events.
You can also add your own objects into the model via a plugin. See Extending Notification Templates Model for details.

Anchor
modelExample
modelExample

Here is an an example description of the model (the code can be used in IntelliJ IDEA to edit the template with completion):. Note that not all entities listed below will be available in any template, e.g. all test responsibilities are assigned in the project scope and notifications on test responsibilities can be configured to point to a project where an investigation was assigned (not to a build configuration). 

Code Block
<#-- @ftlvariable name="project" type="jetbrains.buildServer.serverSide.SProject" -->
<#-- @ftlvariable name="buildType" type="jetbrains.buildServer.serverSide.SBuildType" -->
<#-- @ftlvariable name="build" type="jetbrains.buildServer.serverSide.SBuild" -->
<#-- @ftlvariable name="agentName" type="java.lang.String" -->
<#-- @ftlvariable name="buildServer" type="jetbrains.buildServer.serverSide.SBuildServer" -->
<#-- @ftlvariable name="webLinks" type="jetbrains.buildServer.serverSide.WebLinks" -->

<#-- @ftlvariable name="var.buildFailedTestsErrors" type="java.lang.String" -->
<#-- @ftlvariable name="var.buildShortStatusDescription" type="java.lang.String" -->
<#-- @ftlvariable name="var.buildChanges" type="java.lang.String" -->
<#-- @ftlvariable name="var.buildCompilationErrors" type="java.lang.String" -->

<#-- @ftlvariable name="link.editNotificationsLink" type="java.lang.String" -->
<#-- @ftlvariable name="link.buildResultsLink" type="java.lang.String" -->
<#-- @ftlvariable name="link.buildChangesLink" type="java.lang.String" -->
<#-- @ftlvariable name="responsibility" type="jetbrains.buildServer.responsibility.ResponsibilityEntry" -->
<#-- @ftlvariable name="oldResponsibility" type="jetbrains.buildServer.responsibility.ResponsibilityEntry" -->

 

TeamCity Notification Properties

The following properties can be useful to customize the notifications behaviourbehavior:
teamcity.notification.template.update.interval - how often the templates are reread by the system (integer, in seconds, default 60)
teamcity.notification.includeDebugInfo - include debug debugging information into the message in case of template processing errors (boolean, default false)
teamcity.notification.maxChangesNum - max number of changes to list in an e-mail message (integer, default 10)
teamcity.notification.maxCompilationDataSize - max size (in bytes) of compilation error data to include in an e-mail message (integer, default 20480)
teamcity.notification.maxFailedTestNum - max number of failed tests to list in an e-mail message (integer, default 50)
teamcity.notification.maxFailedTestStacktraces - max number of test stacktraces in an e-mail message (integer, default 5)
teamcity.notification.maxFailedTestDataSize - max size (in bytes) of failed test output data to include in a single e-mail message (integer, default 10240)

...

Syndication Feed Template

The template uses a configuration approach different approach to configuration from other notification engines.

The default template is stored in the file: <TeamCity data directory>/config/default-feed-item-template.ftl. This file should never be edited: it is overwritten on every server startup with the default copy. To specify a new template to use, copy the file under the name named feed-item-template.ftl into the same directory. This file can be edited and will not be overwritten. It will be used by the engine if present.

...

You can use several templates on the a single severserver. The template name can be passed as a URL parameter of the feed URL.

...