Notifier Templates Configuration
Last modified: 20 April 2023In 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.xmlJabber:
<TeamCity data directory> /config/jabber-config.xmlSystem Tray Notifier:
<TeamCity data directory> /config/win32-config.xml
tip
The server automatically reloads a template from the corresponding file, if it detects that this file is changed on disk.
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.
note
The <subject/> element for email notifier supports all patterns that can be used within
<body/>element for the specified event type.
tip
Additionally the {EDIT_NOTIFICATIONS_LINK} pattern is supported. This pattern is replaced with the link to the user's notification configuration page.
"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>Thanks for your feedback!