Notifier Templates Configuration

In this section you can find reference information on the location and syntax of notifier templates, connection with the build events, patterns used to represent important information, and examples:

Notifier Templates

Location

Notifier templates reside in the notifier configuration file:

Email notifier: <TeamCity data directory> /config/email-config.xml
Jabber: <TeamCity data directory> /config/jabber-config.xml
System Tray Notifier: <TeamCity data directory> /config/win32-config.xml
Syndication Feed: <TeamCity data directory> /config/default-feed-item-template.ftl Configuration of Syndication feed template is different from all others. Syndication-Feed-Template.

Syntax notes

Syntax of the notifier configuration files is described in the respective *.dtd files. Notifier configuration file contains two sections:

templates — notifier-specific templates with notification messages
events — the list of events to be notified about, with the references to the associated templates

<templates>

All templates are placed into the <templates> section, for example:

<templates>
  <template id="build_failed_tpl">
    <subject>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} successful {SHORT_STATUS_DESCRIPTION}</subject>
    <body>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} successful {SHORT_STATUS_DESCRIPTION}
Build results: {BUILD_RESULTS_LINK}
    </body>
  </template>
</templates>

Email templates must have <subject/> and <body/> sub-elements.
Jabber templates text should be placed directly into the <template/> tag.
System Tray Notifier templates must have <message/> and <link/> sub elements. The <message/> element contains template of the message and the <link/> element contains a pattern for a link corresponding to the message.

<events>

Templates are attached to the notification events. For now supported events are:

build started (event type build_started)
build successful (event type build_successful)
build failed (event type build_failed)
build is failing (the first error notification, event type build_failing)
responsibility changes (event type responsible_changed)

If an event does not have a template attached, it is ignored, and the users will not receive notifications even if they subscribed to them.

Example of events attachment:

<events>
  <event type="build_failed">
    <ref template="build_failed_tpl" />
  </event>
  <event type="build_successful">
    <ref template="build_successful_tpl" />
  </event>
</events>

It is possible to attach template to a build configuration too:

<event type="build_successful"> <ref template="build_successful_tpl"/> <ref template="build_successful_ant_tpl" build-type="Ant"/> </event>

In this case for the build configuration with the "Ant" id, a template with the "build_successful_ant_tpl" id will be used (if it exists). For all other build configurations default template will be used (referenced here by the "build_successful_tpl" id).

Substitution patterns

Each notification event supports its own set of substitution patterns.

"build_started" event patterns

Pattern	Description
{PROJECT_NAME}	project name
{BUILD_CONFIG_NAME}	build configuration name
{BUILD_NUMBER}	build number
{CHANGES}	list of first 10 changes included in the build
{CHANGES_WITH_FILES}	list of first 10 changes included in the build with changed files
{AGENT_NAME}	agent name where build is running
{AGENT_HOST}	hostname of an agent where build is running
{BUILD_RESULTS_LINK}	link to a build results page
{BUILD_CONFIG_LINK}	link to a build configuration home page

"build_successful", "build_failed" and "build_failing" events patterns

Pattern	Description
{PROJECT_NAME}	project name
{BUILD_CONFIG_NAME}	build configuration name
{BUILD_NUMBER}	build number
{SHORT_STATUS_DESCRIPTION}	short description of current status: number of failed tests, number of passed tests and so on (in braces)
{COMPILATION_ERRORS}	compilation errors block (replaced with empty string if there were no errors)
{FAILED_TESTS_ERRORS}	failed tests errors block (replaced with empty string if there were no errors)
{CHANGES}	list of first 10 changes included in the build
{CHANGES_WITH_FILES}	list of first 10 changes included in the build with changed files
{AGENT_NAME}	agent name where build is running
{AGENT_HOST}	hostname of an agent where build is running
{BUILD_CONFIG_LINK}	link to a build configuration home page
{BUILD_RESULTS_LINK}	link to a build results page
{BUILD_LOG_LINK}	link to a build log page
{BUILD_CHANGES_LINK}	link to a build changes page
{BUILD_ARTIFACTS_LINK}	link to a build artifacts page

"responsible_changed" event patterns

Pattern	Description
{PROJECT_NAME}	project name
{BUILD_CONFIG_NAME}	build configuration name
{RESPONSIBLE}	full name and comment of a person who took responsibility for a build failure
{BUILD_CONFIG_LINK}	link to a build configuration home page

Examples

Email notifier configuration

<!DOCTYPE email SYSTEM 'email-config.dtd'>
<email email-server='mail' email-server-port='25'>
<events>
   <event type='build_started'>
     <ref template='build_started_tpl'/>
   </event>
   <event type='build_failed'>
     <ref template='build_failed_tpl'/>
   </event>
   <event type='build_failing'>
     <ref template='build_failing_tpl'/>
   </event>
   <event type='build_successful'>
     <ref template='build_successful_tpl'/>
   </event>
   <event type='responsible_changed'>
     <ref template='responsible_changed_tpl'/>
   </event>
</events>

<templates>
   <template id='build_started_tpl'>
<subject>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} started.</subject>
<body>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} started.
Build results: {BUILD_RESULTS_LINK}

{CHANGES}

============================================================================
Configure email notifications: {EDIT_NOTIFICATIONS_LINK}
</body>
   </template>
   <template id='build_failing_tpl'>
<subject>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} failing {SHORT_STATUS_DESCRIPTION}</subject>
<body>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} failing {SHORT_STATUS_DESCRIPTION}
Build results: {BUILD_RESULTS_LINK}

{COMPILATION_ERRORS}{FAILED_TESTS_ERRORS}{CHANGES}

============================================================================
Configure email notifications: {EDIT_NOTIFICATIONS_LINK}
</body>
   </template>
   <template id='build_failed_tpl'>
<subject>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} failed {SHORT_STATUS_DESCRIPTION}</subject>
<body>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} failed {SHORT_STATUS_DESCRIPTION}
Build results: {BUILD_RESULTS_LINK}

{COMPILATION_ERRORS}{FAILED_TESTS_ERRORS}{CHANGES}

============================================================================
Configure email notifications: {EDIT_NOTIFICATIONS_LINK}
</body>
   </template>
   <template id='build_successful_tpl'>
<subject>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} successful {SHORT_STATUS_DESCRIPTION}</subject>
<body>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} successful {SHORT_STATUS_DESCRIPTION}
Build results: {BUILD_RESULTS_LINK}

{COMPILATION_ERRORS}{FAILED_TESTS_ERRORS}{CHANGES}

============================================================================
Configure email notifications: {EDIT_NOTIFICATIONS_LINK}
</body>
   </template>
   <template id='responsible_changed_tpl'>
<subject>Responsible for {PROJECT_NAME}::{BUILD_CONFIG_NAME} failure has been changed.</subject>
<body>Responsible for {PROJECT_NAME}::{BUILD_CONFIG_NAME} failure has been changed.
Current responsible: {RESPONSIBLE}

============================================================================
Configure email notifications: {EDIT_NOTIFICATIONS_LINK}
</body>
   </template>
</templates>

</email>

Jabber notifier configuration

<!DOCTYPE jabber SYSTEM "jabber-config.dtd">
<jabber server-host='jabber.some.domain' server-user='user' server-user-password='password'>
<events>
   <event type='build_started'>
     <ref template='build_started_tpl'/>
   </event>
   <event type='build_failed'>
     <ref template='build_failed_tpl'/>
   </event>
   <event type='build_failing'>
     <ref template='build_failing_tpl'/>
   </event>
   <event type='build_successful'>
     <ref template='build_successful_tpl'/>
   </event>
   <event type='responsible_changed'>
     <ref template='responsible_changed_tpl'/>
   </event>
</events>

<templates>
   <template id='build_started_tpl'>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} started.
Build results: {BUILD_RESULTS_LINK}

{CHANGES}

============================================================================
Configure jabber notifications: {EDIT_NOTIFICATIONS_LINK}
   </template>
   <template id='build_failing_tpl'>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} failing {SHORT_STATUS_DESCRIPTION}
Build results: {BUILD_RESULTS_LINK}
{COMPILATION_ERRORS}{FAILED_TESTS_ERRORS}

============================================================================
Configure jabber notifications: {EDIT_NOTIFICATIONS_LINK}
   </template>
   <template id='build_failed_tpl'>Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} failed {SHORT_STATUS_DESCRIPTION}
Build results: {BUILD_RESULTS_LINK}

{COMPILATION_ERRORS}{FAILED_TESTS_ERRORS}

============================================================================
Configure jabber notifications: {EDIT_NOTIFICATIONS_LINK}
   </template>
   <template id='build_successful_tpl'>
Build {PROJECT_NAME}::{BUILD_CONFIG_NAME} {BUILD_NUMBER} successful {SHORT_STATUS_DESCRIPTION}
Build results: {BUILD_RESULTS_LINK}

{COMPILATION_ERRORS}{FAILED_TESTS_ERRORS}

============================================================================
Configure jabber notifications: {EDIT_NOTIFICATIONS_LINK}
   </template>
   <template id='responsible_changed_tpl'>
Responsible for {PROJECT_NAME}::{BUILD_CONFIG_NAME} failure has been changed.
Current responsible: {RESPONSIBLE}

============================================================================
Configure jabber notifications: {EDIT_NOTIFICATIONS_LINK}
   </template>
</templates>
</jabber>

Syndication Feed Template

The template uses 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 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.

The template is a FreeMarker template and can be freely edited.

You can use several templates on the single sever. The template name can be passed as a RSS Feed of the feed URL.

During feed rendering, the template is evaluated to get the feed content. The resultant content is defined by the global variables defined in the temple.

See the defualt template for an example of available input variables and output variables.

Last modified: 20 April 2023