Work Item Gate
- Joel Wenzel
The Work Item Validation Gate provides several variations for ensuring that Work Items associated to the Release have met certain criteria before the Pipeline Execution can continue.
Which Work Items are Validated
The Work Item Selector field determines which Work Items are considered during this Gate evaluation. There are 3 selector options available:
Release Work Items - All Work Items ever associated to the Release (these show up under the Work Items section on the Release Definition tab).
Snapshot Work Items - These are the Work Items that were associated during build of the current Release Snapshot. These are generally a subset of the Release Work Items.
Stage Work Items - Stage Work Items are all Work Items that will deploy in the upcoming Stage steps.
The below diagram can help describe the differences between the 3 selectors when considering which Work Items are selected at a Work Item Validation gate in the Blue Test Stage of Snapshot-3.
Selector | Work Items that will be selected | Why? |
|---|---|---|
Release | 1, 2, 3, 4, and 5 (All of them) | Once a work item is built in a release snapshot, it is added to the Release Work Items where it will remain until the project or work item is removed from the Release. |
Snapshot | 4 and 5 | Only the Work Items built on the current snapshot will be considered. |
Stage | 2, 3, 4, and 5 | Work Item 1 had been deployed to the Test Stage in |
Work Item Selector
The option to choose the Work Item selection process was added in version 9.0.0.1. If you are on version 9.0.0.0 the Snapshot selector is used.
Validation Types
The Work Item Validation Gate supports 3 Validation Types:
Match Status Exact
The most common use case for the Work Item Validation Gate is making sure each Work Item is in a certain status. The Match Status Exact validator does exactly that. One or more status can be provided, separated by comma, and as long as all Work Items in the Release match at least one of the provided statuses then the Gate will succeed.
Note that the status matching is case insensitive, so a status of DONE will also match a status of done
Match Status Regex
Similar to the Match Status Exact validator, the Match Status Regex validator ensures that each Work Item is in an appropriate status. However, it matches the status based on the provided regex pattern.
Custom
The final validator is the Custom validator. This validator offers a Groovy Script with an exposed WorkItems variable, this allows more complex validations to be done on each Work Item.
The following script is the default script when choosing the Custom Validator - it can be modified as needed.
// the script should return a map with the format [workItemNumber: true/false]
// the following script is valid and can be modified as needed
def resultMap = [:]
for (def workitem : WorkItems)
{
if ("DONE" == workitem.getStatus())
{
// valid work item
resultMap.put(workitem.getKey(), true)
}
else
{
// invalid work item
resultMap.put(workitem.getKey(), false)
}
}
return resultMapA few noteworthy comments on using the Custom Validator:
It has access to the
WorkItemsvariable. This variable is a list ofWorkItemDetailsobjects which have all of the information about the Work Item pre-populated such as the assignee, status, labels and more.The script should return a map with the format
[workItemNumber: true/false]
Should the custom script not return a status for a particular WorkItem in the WorkItems variable then it will be considered as false (invalid) when processing the results.
Viewing the Results
During Pipeline Execution, the results of the Work Item Validation gate can be seen in the step details:
- style