Advanced User’s Guide to Querying Work Items in Rational Team Concert
Note:This article was migrated to and is now maintained in IBM Knowledge Center. To access the current information for your version, complete these steps:- Open the Collaborative Lifecycle Management documentation collection.
- In the navigation panel, click the version of the product that you use, for example, Rational Collaborative Lifecycle Management Solution 6.0.1.
- In the help, locate the “Creating queries” section for your client by using either the Search function or the navigation pane. Example:
- For the Eclipse client, click Rational Team Concert > Managing change and releases > Tracking work by using work items > Working in the Eclipse client > Finding work items > Creating queries.
- For the web client, click Rational Team Concert > Managing change and releases > Tracking work by using work items > Working in the web client > Creating queries.
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
- Variables
- Parameter Variables
- The ‘Unassigned’ Value
- Attribute Groups
- Custom Attribute Queries
- Link Queries
- Creating Structured Queries
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:
Multiple values can also be specified for attributes of a simple type like string or numbers by using a comma-separated list:
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.
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.
| 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.
|
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.
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.
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 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.
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.
Example 2
Find all unresolved defects.
Example 3
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”.
Example 4
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.
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.
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.
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.
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.
Example 6
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.
Example 8
Find all fixed work items that are not included in a build.
Example 9
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.
Copyright © 2012 IBM Corporation