Library
Advanced User's Guide to Querying Work Items
Summary
This article covers both versions 1.0.x and 2.0.x.
Rational Team Concert supports different ways to find work items. This document focuses on the Query Editor and intends to shed some light on the lesser known features of creating structured queries. It also discusses current limitations and gives some examples of frequently used queries.
Topics: Anatomy of a Query, Variables, The 'Unassigned' Value, Attribute Groups, Custom Attribute Queries, Link Queries, Examples
Anatomy of a Query
A query consists of one or more conditions that must be met by each work item in the result set. Conditions can be combined and nested using AND and OR elements that surround them. Each condition references a work item attribute, an operator and one or more values. The meaning of multiple selected values depends on the operator: For 'positive' operators like is, the meaning is OR. For 'negative' operators like is not, the meaning is AND. The following two examples illustrate this:
Status of the work item is 'New' or 'Triaged' or 'Reopened'
Status of the work item is not 'New' and not 'Triaged' and not 'Reopened'
Multiple values can also be specified for attributes of a simple type like string or numbers by separating the values using a comma:
The ID of a work item is 55 or 110 or 143 or 211
If no value is selected or no value is entered, the condition is being ignored when the query executes.
Variables
Most value sets are configurable and may change over time. This can render your queries stale after a while. Variables represent a value (or a value set) that changes over time or adapts to the context in which the query is being run. They are hence a way to create longer lived queries that stay valid over time or that can be shared with other users to return different results in their context.
Variables can be used like any other value. If combined with other variables or values, the same semantics apply as described above: If "Current User" and "John Doe" are selected, this means "Current User" OR "John Doe" for the "is" operator.
In the UI, variables are represented as check boxes located above the value area in the query editor sections:
| Attribute | Variable | Description |
|---|---|---|
| Status | Unresolved | When defining a workflow, each state can be assigned to one of three groups: open, closed or inprogress. The Unresolved variable selects all states that belong to the open and inprogress groups at the time of execution. |
| Status | Resolved | When defining a workflow, each state can be assigned to one of three groups: open, closed, inprogress. The Resolved variable selects all states that belong to the closed group at the time of execution. |
| Users | Current User | The Current User variable selects the authenticated user at the time of execution. |
| Filed Against | Related to Current User | A category belongs to one or more team areas. This variable selects all categories that are associated with a team area that the authenticated user belongs to at the time of execution. This variable can roughly be thought of as My Team Areas. |
| Planned For | Current Iteration | Starting at all leaf iterations that are set as current in the project area, the Current Iteration variable selects the first ones that have the release scheduled flag set when going up the hierarchy. This corresponds to the iterations that are shown as current in the Work Item Editor. |
| Timestamps | By choosing Relative Date, the control for time stamps allows to specify a point in time or a time range that relates to the time of execution:
For the after and before operators, the variable returns the time of execution plus the offset.
For the is and is not operators, the point is time is calculated as above, but the variable returns a time range that encompasses that point in time using the chosen time unit.
|
The 'Unassigned' Value
Some work item attributes can be empty or have an 'Unassigned' value that is not part of their configurable value set. The check box 'Unassigned', located in the Variables area, allows to query for this empty value. A good example is the Tags or Estimate attribute: Using the 'Unassigned' value, you can create a query for work items that have no tags set or that are not estimated yet.
Attribute Groups
Attribute Group controls allow to conveniently specify a condition for a set of attributes of the same type without having to add them individually and to select the same values for each of them. Attribute Groups exist for user and timestamp attributes. The individual attribute conditions are joined using OR.
The above example means: "Work items which are created or modified or owned or resolved by the authenticated user".
Custom Attribute Queries
Basically, custom attributes are no different from other attributes when it comes to querying them using the Query Editor. There is a limitation in 1.0.x and a special operator that deserve special attention, however.
The 'exists' Operator
In contrast to the built-in attributes that every work item has, custom attributes may be missing. The 'exists' operator allows to query for work items that have a certain custom attribute set. It can also be used when the custom attribute value itself is not queryable. This is the case for large string custom attributes. A typical example would be a query for all work items of a specific iteration that have a 'Build Note' custom attribute.
Limitations in 1.0.x (lifted in 2.0)
- Conditions on two different custom attributes can currently not be joined using AND. Queries that do so will not return any results. An example: "CustomA is X and CustomB is y" will not return any results.
Link Queries
Technically, links to other artifacts are not attributes on a work item. Links are rather separate items that join two artifacts. This has some impact on their queryability. In the Query Editor, links are treated like any other attribute. You can select the link attribute itself to query for its mere existence, or you can specify a condition on one of its target's attributes. Some examples of link queries are available in the Examples section.
Limitations in 1.0.x (lifted in 2.0)
- A query that contains a link condition will only query on the set of work items that are referenced by any link. This means that a query like "Duplicates exist OR Status is Unresolved" will return work items that have a Duplicates plus any unresolved work items that have any link.
- Multiple link conditions of different types cannot be joined using AND. This means that you cannot create a query like "Blocks > Team Area is X AND Related > Team Area is Y". Joining multiple link conditions of the same type using AND is supported, however.
- The grouping modes in the Team Central query sections are currently not supported for link queries.
Link Query Results
If you are not only interested in the work items that fulfill the link conditions, but also in the link targets themselves, you can enable the links mode in the Work Items view using Relationships... in the view's menu. This allows you to see the referenced work items directly in the tree without having to open a work item first. Currently, only references to other work items are shown.
Examples
Example 1: Find all unresolved work items in your team area that block other teams.
Example 2: Find all unresolved work items in your team area that are planned for the current iteration and depend on another unresolved work item.
Example 3: Find all work items that are planned for the current iteration and have a custom attribute named 'Build Note'.
Example 4: Find all high priority or high severity work items that were created by people outside your organization and are still unresolved.
Example 5: Find all work items in your team area that were fixed during the current iteration and need verification.
Example 6: Find all work items that have an attachment whose size exceeds 10 MB.
Example 7: Find all work items that you created which were resolved as duplicates but are still unresolved. Note: This query works only for direct duplicates. Longer duplicate chains are not considered.
Example 8 (new in 2.0): Find all fixed work items that are not included in a build.
Example 9 (new in 2.0): Find all stories without children.
References
This topic is also discussed:
Yes
No
