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: Basic Concepts/config/email-config.xml
Jabber: Basic Concepts/config/jabber-config.xml
System Tray Notifier: Basic Concepts/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 that contains notifier-specific templates with notification messages
events that contains 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 events. For now supported notification 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 id "Ant" a template with id "build_successful_ant_tpl" will be used (if it exists). For all other build configurations default template will be used (referenced here by id "build_successful_tpl").
Substitution patterns
Each notification event supports it's own set of substitution patterns.
"build_started" event patterns:
{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" event types patterns:
{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" patterns:
{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
Note: <subject/> element for email notifier supports all patterns that can be used within <body/> for the specified event type.
Note: additionally {EDIT_NOTIFICATIONS_LINK} pattern is supported. This pattern is replaced with the link to the user's notification configuration 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!