Notifier Templates Configuration

Added by Irina Megorskaya, last edited by Ekaterina Ivanova on May 07, 2008  (view change)
You are viewing documentation of TeamCity 3.x, which is not the most recent released version of TeamCity. Please refer to the listing to choose another version.
Documentation Index

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:

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.

The <subject/> element for email notifier supports all patterns that can be used within <body/> element for the specified event type.
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>

Labels