Customizing Notification Templates

Each of the bundled notifiers has a directory 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.

By default, the server checks for changes in the files 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 an error occurs during the template evaluation, TeamCity logs the error details to teamcity-notifications.log. There can be non-critical errors that result in ignoring part of the template or critical errors that result in the inability to send notification at all. Whenever you make changes to the notification templates ensure the notification can still be sent.

This document doesn't describe the FreeMarker template language, so if you need guidance on the FreeMarker syntax, refer to the corresponding template manual.

TeamCity notifiers use templates to evaluate output values (global template variables) which are then retrieved by name. The following output values are supported:

Email Notifier

• subject — subject of the email message to send

• body — plain text of the email message to send

• bodyHtml — (optional) HTML text of the email message to send. It will be included together with plain text part of the message. However, if it is present in the template, it should be customized as well.

• headers — (optional) raw list of additional headers to include into an email. One header per line. For example:

<#global headers>
  X-Priority: 1 (Highest)
  Importance: High
</#global>

IDE Notifications and Windows Tray Notifications

• message — plain text of the message to send

• link — URL of the TeamCity page that contains detailed information about the event

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

<#list build.buildLog.messages[1..] as message><#-- skipping the first message (it is a root node)-->
  <#if message.status == "ERROR" || message.status == "FAILURE" >
    ${message.text}
  </#if>
</#list>

<#-- Uses FreeMarker template syntax, template guide can be found at https://freemarker.org/docs/dgui.html -->

<#import "common.ftl" as common>

<#global subject>[<@common.subjMarker/> FAILED] ${project.name}:${buildType.name} - Build: ${build.buildNumber}</#global>

<#global body>TeamCity build: ${project.name}:${buildType.name} - Build: ${build.buildNumber} failed ${var.buildShortStatusDescription}.
Agent: ${agentName}
Build results: ${link.buildResultsLink}

${var.buildCompilationErrors}${var.buildFailedTestsErrors}${var.buildChanges}

 <#list build.buildLog.messages[1..] as message><#-- skipping the first message (it is a root node)-->
   <#if message.status == "ERROR" || message.status == "FAILURE" >
     ${message.text}
   </#if>
 </#list>

<@common.footer/></#global>

<#global bodyHtml>
<div>
  <div>
    TeamCity build: <i>${project.name}:${buildType.name} - <a href='${link.buildResultsLink}'>Build: ${build.buildNumber}</a></i> failed
    ${var.buildShortStatusDescription}
  </div>
  <@common.build_agent build/>
  <@common.build_comment build/>
  <br>
  <@common.build_changes var.changesBean/>
  <@common.compilation_errors var.compilationBean/>
  <@common.test_errors var.failedTestsBean/>

    <#list build.buildLog.messages[1..] as message><#-- skipping the first message (it is a root node)-->
   <#if message.status == "ERROR" || message.status == "FAILURE" >
     ${message.text}
   </#if>
 </#list>

  <@common.footerHtml/>
</div>
</#global>

<p>Build artifacts:</p>
  <#list build.artifactsDirectory.listFiles() as file>
    <a href="${webLinks.getDownloadArtefactUrl(build.buildTypeExternalId, build.buildId, file.name)}">${file.name}</a> (${file.length()}B)<br/>
  </#list>

<#list build.parametersProvider.all?keys as param>
  ${param} - ${build.parametersProvider.all[param]}
  <br>
</#list>

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.

Here is 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, for example, 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).

<#-- @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" -->

The following properties can be useful to customize the notifications' behavior:

• teamcity.notification.template.update.interval — how often the templates are reread by the system (integer, in seconds, default 60)

• teamcity.notification.includeDebugInfo — include 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 email message (integer, default 10)

• teamcity.notification.maxCompilationDataSize — max size (in bytes) of compilation error data to include in an email message (integer, default 20480)

• teamcity.notification.maxFailedTestNum — max number of failed tests to list in an email message (integer, default 50)

• teamcity.notification.maxFailedTestStacktraces — max number of test stacktraces in an email message (integer, default 5)

• teamcity.notification.maxFailedTestDataSize — max size (in bytes) of failed test output data to include in a single email message (integer, default 10240)