Overview

A project build subscription allows you to be notified of build results for one or more projects.

Configuration

Projects

Select the projects that you wish to subscribe to. To subscribe to all projects, including new projects, do not select any projects.

Condition

The subscription condition can be used to filter out notifications that are not interesting to you. The conditions are all based on flexible boolean expressions. For convenience, common types of conditions can be selected without configuring the expression itself. For full control, select the custom option and edit the expression directly. Each type of condition is described in the sections below.

all builds

The simplest condition, which evaluates to true for all builds. You will be notified of every build result.

selected builds

A list of commonly-used conditions that you can select from. If a build result meets any of the selected conditions, you will be notified of the build. Note that options mentioning changed builds refer to source code changes.

repeated unsuccessful builds

This option allows you to be notified only after a run of consecutive unsuccessful builds. This can be useful when you do not want to be notified of hiccups, but need to be warned when something serious may be wrong. To configure this option, enter the a positive number and select units of either "builds" or "days". If you select "builds", you will be notified when that number of builds has failed in a row. If you select "days", you will be notified when the build has been unsuccessful for that number of days. In both cases you will only be notified once in one string of unsuccessful builds, even if builds continue to fail.

Choosing A Template This condition type combines well with the "HTML project overview email" template. That template gives a brief overview of the health of the project in question.

custom condition expression

This option allows you to enter an arbitrary boolean condition expression. See Condition Expressions below for details on the expression language.

Template

Select the template to use to render the notifications. For more information, refer to Subscription Templates.

Condition Expressions

A condition is a boolean expression made up of boolean values (e.g. changed, failure), boolean operators (e.g. and, or) and comparison expressions. A comparison expression is in turn made up of integer values (e.g. unsuccssful.count.days, 5) and integer operators (e.g. <, ==). A condition must evaluate to true for a notification to be sent. The boolean expression syntax is described in simplified form below:

expression = <boolean> (<boolean operator> <boolean>)*
boolean    = <comparison> | <boolean value>
comparison = <integer value> <integer operator> <integer value>

Available boolean values are described in the table below:

Boolean operators are used to combine these values into complex expressions. The operators are summarised in the table below. Note that operators are shown in order of increasing precedence.

Operators with higher precedence (lower in the table) bind more tightly, e.g. "a and b or c" is equivalent to "(a and b) or c".

Detecting Unsuccessful Builds To detect unsuccessful builds it is best to use the condition "not success", as this will be true whether the build fails or encounters an error.

Additionally, integer values are available for comparisons. These values are summarised in the table below:

Integers must be formed into comparisons to evaluate to a boolean. The available integer operators are given below. Note that only one operator can be used in a comparison, so there is no precedence:

Sometimes it is useful to detect when a condition has changed from one build to the next. For this reason, the values (both boolean and integer) act like functions that evaluate given a build result. By default, they are given the build result that has just been completed. To evaluate a value for the previous build (of the same build specification), append "(previous)" to the value, for example "unsuccessful.count.days(previous)".

The available primitive conditions are used to test properties of the build result, such as if the build succeeded, if it was changed by you, or if it's status is different to the previous build. The full list of primitive conditions is summarised in the table below:

As of 1.2.46, String values are also available for comparisons. These values are summarised in the table below:

String values should be used in the same was as integer values, and can only be compared to other string values.

Examples

all builds

Use a constant expression:

true

builds broken by you

Builds that you may have broken will be unsuccessful and will have changes by you:

not success and changed.by.me

unsuccessful builds and the first successful build after an unsuccessful run

Detect unsuccessful builds with "not success". The first success can be captured by "state.change", as the build must have changed from unsuccessful to successful:

not success or state.change

broken for 3 or more days

Use a simple comparison:

unsuccessful.count.days >= 3

broken for 3 days, notify once only

The preceding example is a bit simplistic in that you will receive no notification for days, then a flood of notifications if the build continues to be unsuccessful on the third and subsequnet days. To be notified once only, we need to detect when the 3 day threshold is crossed in a run of unsusccesful builds:

unsuccessful.count.days(previous) < 3 and unsuccessful.count.days >= 3

sucessful builds for the nightly build specification

build.specification.name == nightly and successful