Filter Trigger - CruiseControl.NET

The Filter Trigger allows you to prevent builds from occurring at certain times or on certain days (such as when your source control repository is undergoing backup). It is used to decorate an existing trigger. For example, if you have set up a Interval Trigger to cause a new build every 5 minutes, you can use the Filter Trigger to create a window during which the build will not run.

The filter will exclude modifications that occur between the start time and the end time on the days specified. If the start time is greater than the end time then the filtered time will span across midnight. For example, if the start time is 23:00 and the end time is 3:00 then builds will be suppressed from 23:00-23:59 and 0:00-3:00 on the days specified.

Nested trigger syntax is different

As shown below, the configuration of the nested trigger is not the same as when using that trigger outside a filter trigger. When using the <filterTrigger> element, the inner trigger must be specified with the <trigger> element. You could not use the <intervalTrigger> trigger element in this example.

Example

NOTE: Like all triggers, the filterTrigger must be enclosed within a triggers element in the appropriate Project Configuration Block

<filterTrigger startTime="23:30" endTime="23:45">
    <trigger type="intervalTrigger" seconds="60" />
    <weekDays>
        <weekDay>Sunday</weekDay>
    </weekDays>
</filterTrigger>

This trigger suppresses builds if any modifications are made between 23:30 and 23:45 on Sunday nights.

Configuration Elements:

Node	Description	Type	Required	Default
startTime	The start of the filter window. Builds will not occur after this time and before the end time.	string	false	00:00:00
endTime	The end of the filter window. Builds will not occur before this time and after the start time.	string	false	23:59:59
weekDays	The week days on which the filter should be applied (eg. Monday, Tuesday). By default, all days of the week are set. The filter will have no effect on other days	elements	false	Monday-Sunday
buildCondition	The condition that will be returned if a build is requested during the filter window. The default value is NoBuild indicating that no build will be performed. Legal values are IfModificationExists, ForceBuild, NoBuild.	string	false	NoBuild

NOTE: Times should be specified in hh:mm or hh:mm:ss 24 hour format (i.e., ranging from 00:00:00 to 23:59:59).

Nested Filter Triggers:

Sometimes you would like to suppress builds that occur either between certain times or on certain days or in multiple combinations of dates and times. To acheive this, you can nest multiple filter triggers. For example, the following xml configures a trigger to filter builds between 7pm and 7am on weekdays and at any time on Saturdays and Sundays.

<filterTrigger startTime="19:00" endTime="07:00">
    <trigger type="filterTrigger" startTime="0:00" endTime="23:59:59">
        <trigger type="intervalTrigger" name="continuous" seconds="900" buildCondition="ForceBuild"/>
        <weekDays>
            <weekDay>Saturday</weekDay>
            <weekDay>Sunday</weekDay>
        </weekDays>
    </trigger>
</filterTrigger>

With contributions from: Oane Stienstra