RegisterLog In to Jazz.net dW

Advanced User's Guide to Querying Work Items in Rational Team Concert

Summary

Querying is a powerful feature of Rational Team Concert that gives users various ways to find work items. This functionality can best be described as a property-based search. This means that finding work items in RTC involves setting constraints on the attributes that define them. The query engine will then return all work items that satisfy these constraints in the requested project.

This document intends to shed some light on the less known features of creating structured queries. For readers interested in a more hands-on approach to writing queries, feel free to jump directly to the last section, Creating Structured Queries.

Topics


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 is Reopened Status of the work item is not New AND is not Reopened
Status of the work item is New OR is Reopened versus is not New AND is not Reopened

Multiple values can also be specified for attributes of a simple type like string or numbers by using a comma-separated list:

The ID of a work item is 55 or 110 or 143 or 211
The ID of a work item is 55 or 110 or 143 or 211

If no value is selected or entered, the query engine ignores the condition. An empty condition is the equivalent of matching on all possible values of the particular attribute.


Variables

Since most value sets are configurable and may change over time, your queries may become 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.

In the UI, variables are represented as check boxes located above the value area in the query editor sections.

Query Variables for the Status Attribute
Query Variables for the Status Attribute

Variables can be used like any other value. If combined with other variables or values, the same semantics apply as described above: If "Unresolved" and "Completed" are selected, this means "Unresolved" OR "Completed" for the "is" operator.

Overview of supported Variables
Attribute Variable Description
Status Unresolved When defining a workflow, each state can be assigned to one of three groups: open, closed or in progress. The Unresolved variable selects all states that belong to the open and in progress groups at the time of execution.
Status Resolved When defining a workflow, each state can be assigned to one of three groups: open, closed, in progress. 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.
  • "Creation Date after 2 days ago" would mean "Created within the last 48 hours".
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.
  • "Creation Date is 2 days ago" would mean "Created on June 1", if today is June 3.
  • "Creation Date is 1 month ago" would mean "Created from May 1 to May 31" or "Created last month", if today is June 3
  • "Due Date is 1 year from now" would mean "Due between Jan 1, 2009 and Dec 31, 2009", if today is June 3, 2008
Note that there is currently no time zone correction for the client executing the query: The day starts and ends at midnight server time.

Parameter Variables

Parameter variables are another powerful feature that makes queries more flexible to change by promoting reuse across contexts and users. A Parameter Variable is a condition that allows users to choose its values every time the query is run and thus enables reuse of the same query in different contexts. For example, almost duplicated queries with changing user groups, date ranges, work item relationships, and/or severities can be consolidated using parameter variables. Whenever a condition in a query is known to change across query calls, it is a good idea to set it as a parameter variable. This enables users to reuse the same query for different purposes, and enables sharing queries among similar user group, such as project managers, developers, and administrators.

For example, a query that finds "All Stories resolved by $user that contain a certain $text" would prompt for an RTC user and some text input before it is run.

Running a parametrized query on Resolved By and Fulltext in the Web UI
Running a parametrized query on Resolved By and Fulltext in the Web UI

Note that a user does not have to provide values for all parameter variables. If no condition value is provided the condition will be ignored and the query is run without it, just as queries run directly from the editor. Some good example cases in which parameterized queries have been useful are shown below:

  • Created by me with $severity and $priority...
  • Resolved by $team in $dateRange...
  • Open SCM work items by $tag...
  • All Resolved By $user...
  • All open Dashboard Viewlet work items by $Severity, $Priority and $Type...

RTC inserts three dots after parametrized query names in the UI as a convention to indicate that further input will be required from the user before the query is executed.


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 Owned By or Planned For attribute; using the 'Unassigned' value, you can create a query for work items that have no owners set or that are not planned for any particular iteration.

A query with the Owned By or Planned For attribute using the 'Unassigned' value

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.

A User Attribute Group
A User Attribute Group

The above example means: "Work items which are created or modified or owned or resolved by the current (authenticated) user".


Custom Attribute Queries

Basically, custom attributes are no different from other attributes when it comes to querying them using the Query Editor. However, in contrast to the built-in attributes that every work item has, custom attributes may be missing (for example, from all items that were created prior to defining the custom attribute). Therefore it becomes especially interesting to query for the existence of that attribute using the exists operator.

This 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 Notes' custom HTML attribute.

Note: It is not possible to query for text in custom attributes as all text-based search is done via the Full Text search option.


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 Creating Structured Queries section.

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. Only references to other work items are shown in the view.

Hierarchical results in the Work Items view
Hierarchical results in the Work Items view

Examples: How To Construct Work Item Queries

In RTC work item queries are property-based searches, i.e., you can find work items by setting constraints on their attributes. While in queries attribute, conditions can be mixed and matched arbitrarily, there is a general pattern that we can follow to produce proper and concise definitions of work item queries. This pattern is based on the categorization of work item attributes into five separate dimensions (Core, Content, People, Temporal, Structure), so that constructing a query becomes equivalent to searching available work items along them

We go through this section by outlining each dimension and follow with example queries that illustrate the proper formulation of query statements in that dimension. To introduce continuity across the different examples, we will give the query statement while marking the dimension on each part of it. Every dimension is noted with a color code which is then used to identify its role in a particular query with an under line of the same color.

Note: The query dimensions are an artificial categorization of work item attributes. It is neither a fixed categorization nor reflected in RTC in a concrete manner. It's more of a set of best practices outlined for the purpose of better explaining the creation of structured queries in this article. These dimensions are also not mutually exclusive, as they can be overlapping in different contexts.

Core Dimension  "What kind of work item?"

Conditions: Type, State, Resolution, Severity, Priority

Often you're looking for a certain kind of work items that can be distinguished from others by their type, state, or severity/priority. For example, you want to find all Story or Track Build items, all Unresolved or Verified items, or items of High or Low importance. That most often a good starting point for more complex queries that add filter the result with additional conditions.

The Core Dimension reflects the main attributes of a work item. Putting constraints on attributes in this dimension helps you formulate what meta information you are looking for.

Example 1

Find all fixed but unverified work items.

Find all fixed but unverified work items

Example 2

Find all unresolved defects.

Find all unresolved defects

Example 3

Find all high priority or high severity work items that are still unresolved.

Find all high priority or high severity work items that are still unresolved

Content Dimension  "What's the work item about?"

Conditions: Id, Summary, Description, Tags, Comments, Duration, Estimate, Custom Attributes

In some cases you don't know much about the work items themselves, but something about their content. In RTC, content in work items is mainly provided in form of text. Various conditions allow for querying textual values, ranging from very specific, e.g., the work item Id to very unspecific, e.g., the full-text condition. A full-text condition will search for work items that contain the text in their summary, description or comments attributes. Note that it uses word stemming techniques and thus may results in less findings compared to using summary, description or comments directly. Also other content attributes, such as tags, estimate, duration and even custom attributes, can provide very selective results in cases where you know these values in existing work items.

The Content Dimension is particularly helpful when you know what content you're looking for in your work items.

Example 2 (cont'd)

Find all unresolved defects that contain the text "test failure".

Find all unresolved defects that contain the text 'test failure'

Example 4

Find all work items that have a custom attribute called Build Notes and whose Due Date is ten days from now.

Find all work items that have a custom attribute called Build Notes and whose Due Date is ten days from now

People Dimension  "Who's in involved? (people, teams)"

Conditions: Filed Against, Team Area, Owner, Creator, Resolver, Modifier, Approvers, Subscribers, Commenters

In situations where you know people or teams that are possibly involved in work items you can query for attributes in the People dimension. They define the relationships of work item with respect to RTC users and teams. Users can for example create, modify, own, or resolve work items (Created By, Modified By, Owned By, Resolved By). Teams can be found by querying for specific conditions using the Team Area and Filed Against attributes.

The People Dimension allows for specifying constraints on any attribute of type Contributor, Team Area or Category and can help to specify who is involved in the work items you're looking for.

Example 1 (cont'd)

Find all fixed but unverified work items of the Work Item team.

Find all fixed but unverified work items of the Work Item team

Example 3 (cont'd)

Find all high priority or high severity work items that were created by people outside your organization and are still unresolved.

Find all high priority or high severity work items that were created by people outside your organization and are still unresolved

Temporal Dimension  "When did events happen to the work item?"

Conditions: Planned For, Approvals, Creation Date, Resolution Date, Due Date, Modification Date

If you know particular events that have happened to your queried work items, you can use attributes from the Temporal Dimension. Most conditions here specify events that happened within a certain range of time or at a certain point in time. However, we also added planning and verification related attributes to this dimension, as planning looks into the future and approvals confirm the past of work items. Putting constraints on any attribute of type Timestamp, Iteration, and Approval can tell you when something happened and can thus be considered a search on the Temporal Dimension.

Example 1 (cont'd)

Find all fixed but unverified work items of the Work Item team that were fixed during the current iteration.

Find all fixed but unverified work items of the Work Item team that were fixed during the current iteration.

Structural Dimension  "In what relationships is the work item?"

Conditions: Related, Children, Blocks, Attachments, Resolves, Mentions, Change Sets, ...

The final dimension is about structural relationships and linkage between work items and with other artifacts. Query conditions in the structural dimension specify how work items related to other work item and artifacts within RTC. Linkage employs link types, such as related, blocks, or tested-by to specify relationships between work items. This can be very useful if you know that Stories are usually parents of tasks. Artifact relationships are defined by artifacts, such as attachments, builds, change sets, etc., exhibit a relationship with the queried work items. You can query very selectively for some work items if you know about such a relationship.

The conditions in the Structural Dimension formulate how are work items related to other work items or artifacts. After finding too many work items with some starting condition, e.g., via the core dimension, structural dimension can help to filter the resulting findings significantly.

Example 2 (cont'd)

Find all unresolved defects of the Work Item team that block other teams.

Find all unresolved defects of the Work Item team that block other teams

Example 5

Find all work items that you created which were resolved as duplicates and whose duplicates are still unresolved.

Note: This query works only for direct duplicates. Longer duplicate chains are not considered.

Find all work items that you created which were resolved as duplicates and whose duplicates are still unresolved

Example 6

Find all defects and enhancements of the Work Item team that depend on another unresolved work item.

Find all defects and enhancements of the Work Item team that depend on another unresolved work item

Example 7

Find all work items that have an attachment of png image type.

Find all work items that have an attachment of png image type

Example 8

Find all fixed work items that are not included in a build.

Find all fixed work items that are not included in a build

Example 9

Find all stories without children.

Find all stories without children

References

This topic is also discussed in Getting Started with Work Items.


About the Authors

The authors are developers in the Tracking and Planning team working on the Work Item component of Rational Team Concert with main contributions to the query engine, work item templates, and the server backend. For additional information about the topic presented in the article add your comments or questions directly in the discussion part, or visit our Jazz.net Forum.


Feedback
Was this information helpful? Yes No 19 people rated this as helpful.