Query structure

A query consists of one or more conditions that must be met by each work item in the result set.

Note: Most of the examples in this topic are for the Eclipse client. The user interface for the query editor in the Eclipse and web clients is very similar.

You can combine and nest conditions by surrounding them with AND and OR elements. 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 concept.

Example 1: Setting the Status attribute condition to is New OR is Reopened

Example of setting the Status attribute condition to "is New OR is Reopened"

Note: In Example 1, the Status attribute values are associated with specific workflows, for example, New for the Task, Defect, Impediment, and Retrospective workflows; Reopened for the Defect Workflow.

Example 2: Setting the Status attribute condition to is not New AND is not Reopened

Example of setting the Status attribute condition to "is not New AND is not Reopened"

You can also specify multiple values for attributes of a simple type like a string or numbers by using a comma-separated list.

Example 3: Setting the ID attribute condition to is 53 OR 110 OR 129 OR 216

Example of setting the ID attribute condition to "is 53 OR 110 OR 129 OR 216"

If you do not select or enter a value for an attribute condition, the query engine ignores the condition. An empty condition is the equivalent of matching all possible values of the attribute.

Variables

Most value sets are configurable and can change over time, meaning that your queries might become stale. Variables represent a value or value set that can change over time or adapt to the context in which a query is run. For these reasons, variables offer a way to create queries that stay valid over time and can be shared among users.

In the user interface, variables are represented as check boxes that are located above the value area in the query editor sections. Example 4 shows the Unresolved and Resolved variables for the Status attribute.

Example 4: The Unresolved and Resolved variables for the Status attribute

Example of the Unresolved and Resolved variables for the Status attribute

You can use variables like any other value. If variables are combined with other variables or values, the same semantics apply as described. In the previous example, if you select the Unresolved variable and the Deferred value, it means that the Status attribute condition is "Unresolved OR Deferred" for the is operator.

Table 1 describes some commonly used attributes and associated variables.

Table 1. Attributes and associated variables
Attribute	Variables	Description
Status	Unresolved	When you define a workflow, each state can be assigned to one of three groups: open, in progress, or closed. The Unresolved variable selects all states that belong to the open and in progress groups at the time the query is run.
Status	Resolved	When you define a workflow, each state can be assigned to one of three groups: open, in progress, or closed. The Resolved variable selects all states that belong to the closed group at the time the query is run.
Users	Current User	The Current User variable selects the authenticated user at the time the query is run.
Filed Against	Related to Current User	A category belongs to a project or one or more team areas. The Filed Against variable selects all categories that are associated with a team area that the authenticated user belongs to at the time the query is run. This variable can be thought of as my team areas.
Planned For	Current Iteration	When you use the is operator with the Current Iteration variable, the query selects the first iterations that have the release scheduled flag set when a search is performed up the hierarchy starting at all leaf iterations that are set as current in the project area. The current iteration corresponds to the iterations that are shown as current in the work item editor. When you use the is part of operator with the Current Iteration variable, the query uses the selected iteration as the root and includes all of its children in the project area.
Creation Date		Click Relative date to specify a point in time or a time range that corresponds to the time the query is run. When you use the after (including) or before (including) operator, the variable returns the time that the query is run plus the offset. For example, Creation Date after 2 days ago means Created within the last 48 hours.
Timestamps		For the is and is not operators, the point in time is calculated as described for the Planned For attribute, but the variable returns a time range that includes that point in time and uses the time unit that you select. For example, if today is 3 November 2015, the query conditions that are listed next have the following meanings. Creation Date is 2 days ago means Created on 1 November. Creation Date is 1 month ago means Created from 1 October to 31 October or Created last month. Due Date is 1 year from now means Due between 1 January 2016 and 31 December 2016. Note: There is no time zone correction for the client when you run the following query: The day starts and ends at midnight server time.

Parameter variables

Parameter variables are a special type of variable feature that makes queries more flexible by promoting reuse across contexts and users. A parameter variable is a condition that allows users to choose its values each time they run the query, which enables reusing a query in different contexts. For example, queries with changing user groups, date ranges, work item relationships, and severities can be consolidated by using parameter variables. When a condition in a query is known to change across query calls, it is advantageous to define it as a parameter variable.

For example, a query that finds All stories that are resolved by $user that contain certain $text prompts for a IBM® Engineering Workflow Management user and some text input before the query runs.

Example 5: Running a parameterized query on the Resolved By and Full Text attributes

Example of running a parameterized query on the Resolved By and Full Text attributes

You do not need to provide values for all parameter variables. If you do not provide a condition value, the condition is ignored and the query runs without it, just like queries that you run from the query editor.

Parameterized queries are useful in the following example scenarios:

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 widget work items by $Severity, $Priority, and $Type...

Engineering Workflow Management appends an ellipsis (...) after the names of parameterized queries in the user interface to indicate that you need to provide further input before the query runs.

Note: You are able to create a query that includes empty fields: for example, text fields without content can be included in your query.

The Unassigned value

Some work item attributes can be empty or have an Unassigned value that is not part of the attribute's configurable value set. The Unassigned check box, which is in the variables area for an attribute, enables querying for this empty value. You can find examples of the Unassigned value in the Owned By and Planned For attributes. By selecting the Unassigned value, you can create a query for work items with no owners set or that are not planned for an iteration.

Example 6: The Unassigned value in the Owned By and Planned For attributes

Example of the Unassigned value in the Owned By attribute

Example of the Unassigned value in the Planned For attribute

Attribute groups (Eclipse client only)

You can use attribute group controls to specify a condition for a set of attributes of the same type without having to add them individually and select the same values for each of them. Attribute groups exist for User and Timestamp attributes. You join the individual attribute conditions by using OR.

Example 7: An attribute group for the User attribute

Example of an attribute group for the User attribute

In the example, the User attribute condition is set to find work items that are created by, modified by, owned by, OR resolved by the current authenticated user.