Overview
Subscriptions to project build results may be coupled with a flexible custom condition. This condition is a powerful way to filter out build results that are of no interest to you.
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:
Available boolean values are described in the table below:
| Value |
Description |
| true |
Always evaluates to true. |
| false |
Always evaluates to false. |
| success |
True iff the build succeeded. |
| failure |
True iff the build failed (does not include errors). |
| error |
True iff the build encountered an error. |
| changed |
True iff the build includes a change since the previous build of the same project. |
| changed.by.me |
True iff the build includes a change by you since the previous build of the same project. |
| changed.by.me.since.success |
True iff any of the builds after the last successful build, up to and including this build, includes a change by you. |
| state.change |
True iff the build result differs from the result of the previous build. |
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.
| Operator |
Usage |
Description |
| or |
a "or" b |
Evaluates to true if either a or b is true. |
| and |
a "and" b |
Evaluates to true if both a and b are true. |
| not |
"not" a |
Evaluates to true if a is false. |
| grouping |
"(" a ")" |
Used to override precedence, e.g. "a and (b or c)". |
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:
| Value |
Description |
| [0-9]+ |
An integer literal. |
| unsuccessful.count.builds |
The number of consecutive unsuccessful builds. |
| unsuccessful.count.days |
The number of consecutive days that the build has been unsuccessful. |
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:
| Operator |
Description |
| < |
Less than. |
| <= |
Less than or equal to. |
| != |
Not equal to. |
| == |
Equal to. |
| >= |
Greater than or equal to. |
| > |
Greater than. |
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, append "(previous)" to the value, for example "unsuccessful.count.days(previous)".
Examples
all builds
Use a constant expression:
builds broken by you
Builds that you may have broken will be unsuccessful and will have changes by you:
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:
broken for 3 or more days
Use a simple comparison:
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:
