Overview
Subscription templates are used to render build results into messages that can be sent to contact points, such as email addresses. Various templates are provided with pulse™ that provide the most commonly-sought information. However, it is also possible to provide your own templates for rendering build results.
FreeMarker
Subscription tempaltes are written using FreeMarker
, an excellent templating engine that has particularly good debugging support. It is assumed you are familiar with FreeMarker. If not, online documentation is available.
Template Location
Directory Structure
User-defined templates are contained within you pulse™ data directory, where they will persist across upgrades. All subscription templates may be found under:
Templates are further divided into two subdirectories, personal-builds and project-builds, for personal and regular project builds respectively. If you browse to these directories, you should see an example template there already, with ".example" appended to the template name so that it is not picked up by pulse™.
File Naming
Pulse will pick up any files in the template directories that have names ending with ".ftl", and assume they represent subscription templates. These files are the FreeMarker templates used to render a build result. An additional file of the same name, but with a ".properties" extension instead of ".ftl" is supported to provide additional metadata about the template. This file is in java properties format, and currently two keys are supported:
| Key |
Description |
Default |
| display |
The display name for the template, used in the pulse™ interface. |
The template filename without the ".ftl" extension. |
| type |
The MIME type of the template output. |
text/plain |
Subject Templates
You can also customise the subject of a notification email using a subject template. This is a FreeMarker template with the same name as the primary template plus a "-subject" suffix, for example "plain-text-email-subject.ftl". The subject template has access to the same data model as the primary template. It should consist of a single line only, but otherwise is fully customisable.
An Example
The easiest way to understand how this works is to look at the example "custom-text-email" template. If you remove the ".example" postfix from the template file name, pulse™ will recognise the template and add it to the list of options when configuring subscriptions. Take a look inside the template to get a feel for how it works. You may also want to use the built-in templates (under $PULSE_HOME/versions/<build number>/system/templates/notifications/) for inspiration.
Authoring Templates
To write your subscription templates, you need access to the build result information. This is provided in various ways, from low level access to the Java objects in the FreeMarker data model to higher level macros for outputting commonly-used fragments.
The Data Model
When rendering a build result, pulse™ populates the FreeMarker data model with the following objects:
| Name |
Description |
| baseUrl |
The base URL for the pulse™ server. |
| project |
The project that was built. |
| status |
A simple string status for the build, either "healthy" or "broken". |
| result |
The build result object, see below for how to extract information. |
| changelists |
A list of changelist objects: the new changes in the build. See the buildChanges macro. |
| model |
The build result object, see below for how to extract information. |
| lastSuccess |
If the build was unsuccessful, the last successful build of the same specificaiton. |
| unsuccessfulBuilds |
If the build was unsuccessful, the number of consecutive unsuccessful builds. |
| unsuccessfulDays |
If the build was unsuccessful, the number of consecutive days of unsuccessful builds. |
| errorLevel |
A constant value used as an argument for build messages macros. |
| warningLevel |
A constant value used as an argument for build messages macros. |
Note that using macros (see below) is the preferred way to access the data model, as it provides more insulation from changes in new versions of pulse™.
Simple Properties
Some simple build properties may be accessed directly from the build result object, including:
| Property |
Description |
| result.project.name |
The name of the project built. |
| result.number |
The build number (or id). |
| result.state.prettyString |
A human-readable version of the build status. |
| result.reason.summary |
The reason for the build. |
Methods
The following methods are available:
| Method |
Parameters |
Description |
Example |
| buildLink |
The build result. |
Returns the URL for the build view for the build. |
${buildLink(result)} |
Macros
Various FreeMarker macros are available to walk the data model and output useful information.
buildStages
Description
Outputs the build stage results line by line.
Parameters
| Name |
Description |
| result |
The build result. |
Usage
[@buildStages result=result/]
buildChanges
Description
Outputs the changes in the build as a brief bulleted list.
Parameters
None.
Usage
[@buildChanges/]
buildMessages
Description
Outputs the build features of a given level as a flat list with context information.
Parameters
| Name |
Description |
| level |
The message level (errorLevel or warningLevel). |
| result |
The build result. |
Usage
[@buildMessages level=errorLevel result=result/]
buildTestSummary
Description
Outputs a one-line summary of the build test results.
Parameters
| Name |
Description |
| result |
The build result. |
Usage
[@buildTestSummary result=result/]
