Query for Bugs, Tasks, or Other Work Items

  • Article

You can use query tools to track and update work items and generate reports. To track the status of a work item or the progress of an iteration or release, you can run one of the predefined queries. You can also use the Query Editor in Team Web Access (TWA) and Team Explorer to define filter criteria, and then use Query Results to get either a flat list or nested view of work items.

The easiest way to get started is to run one of the predefined queries.

Choose the Work Items page, expand the Shared Queries node, and choose the query. The illustration to the right shows the shared queries provided with the Visual Studio Scrum process template.

To learn more about shared queries provided with the default process templates for Team Foundation Server, see Shared Queries (Scrum), Shared Queries (Agile), and Shared Queries (CMMI).
Shared queries (Visual Studio Scrum)

Visual Studio Shared Queries (TWA)

As the following illustration shows, in addition to the search box, you can create a query by using one of three query types. After you have your list of work items, you can open or copy an item, link items, bulk modify items, export lists to Excel or Project, and more.

Query tools

Query tools (Team Web Access)

In this topic

  • Select the right query tool for the task

  • Use queries to perform bulk modifications

  • Add columns and sort the results view

  • Save, share, and email queries

Requirements

  • To view a query, you must be a member of the Readers group or have the View work items in this node permission set to Allow for the team project that the attached query references.

  • To create, save, or modify a query, you must be a member of the Contributors group or have the Edit work items in this node permission set to Allow.

  • To save a query as a shared query, you must be a member of the Project Administrators group or you must have the required permissions set. Other restrictions might apply.

    For more information, see Organize and Set Permissions on Work Item Queries and Change permission levels.

Note

When query results contain a work item that you do not have required permissions to view, the cells of that work item are blank, and all you can see is the work item ID and the title cell which indicates <<no access>>.

Select the right query tool for the task

You can find work items using the search box or the Query Editor. The following table summarizes the filter criteria you can use based on the tool you select, as well as the additional tasks you can perform. For simple searches, use the search box or Flat List query. To view a single-level of linked work items, use the Work Items and Direct Links query. And, to view multiple levels of hierarchical relationships among work items, use the Tree of Work Items query. You can easily switch from one query type to another. Note that some functions will vary when you view the query results in Team Web Access or in Team Explorer.

Search box

Flat Query Flat List (Default)

Direct Links Query Work Items and Direct Links

Tree Query Tree of Work Items

Use to quickly find a work item by ID, keyword, phrase, or assignment.

See Find Work Items by ID and by Using the Search Box.

Use to find work items that you want to link to other work items, export work items to Office Excel and Office Project for bulk updates to column fields, or generate a report about a set of work items.

See Work with a flat list (default) query.

Use to find work items and their dependencies.

See Work with linked dependencies (Direct Links).

Use to find and modify work items linked in a nested hierarchy.

See Work with linked hierarchies (Tree of Work Items).

Filter by:

  • ID.

  • Full-text search by Title, Description, or Repro Steps.

  • Shortcuts: A:, C:, S; and T for Assigned To, Created By, State, and Work Item Type.

  • Operators: =, :, and – specify the operations Equals, Contains, and Not.

  • Variables: @Me, @Today.

Filter by:

  • Single set of filters with simple or grouped query clauses.

  • One or more IDs.

  • Within or across projects.

  • Full-text search by Title, Description, Repro Steps, or History.

  • Equal to or under an area or iteration path.

  • Compare work item fields.

  • If a field ever contained a value.

  • Full complement of operators.

  • Variables: @Me, @Today, @Project, [Any].

Filter by:

  • Flat list criteria plus dependent link filters.

  • Filter by any link type.

  • Top-down filter criteria.

Filter by:

  • Flat list criteria plus hierarchical link filters.

  • Filter by hierarchical link types only.

  • Top-down or bottom-up filter criteria.

Supports these tasks for selected work item(s):

  • Open work items.

  • Open found results as a query.

Opens the work item automatically when searching by ID.

Supports these tasks for selected work item(s):

  • Link to a new or existing work item.

TWA only:

Team Explorer only:

Supports these tasks for selected work item(s):

  • All tasks supported by the flat list query except for creating status and trend reports in Excel.

  • Expand and collapse leaf nodes.

Note

When you export work items, only those work items defined for a single team project are exported and as a flat list.

Supports these tasks for selected work item(s):

  • All tasks supported by the flat list query and direct links query, except for creating status and trend reports in Excel.

  • Expand and collapse leaf nodes.

Team Explorer only:

  • Drag and drop work items to create, move, or copy link relationships within the Query Results view.

  • Export to Excel or Project, and modify links within Excel or Project.

Supports these additional tasks:

  • Open list as a query.

Supports these additional tasks for a selected work item:

  • Open a work item.

  • Create a clone of a work item. (TWA only)

  • Create a copy of a work item.

Supports these additional tasks for a selected work item:

  • All tasks supported by the flat list query.

Supports these additional tasks for a selected work item:

  • All tasks supported by the flat list query.

As the following illustration shows, constructing a query can often be an iterative process, where you refine your filter criteria and refresh the query results as you go. All work item queries consist of one or more query clauses. Each clause is comprised of a field, an operator, and a value. You create and modify queries by adding, removing, modifying, and grouping as many clauses and fields as you need to generate the filtered set of work items that you want. For more information, see Query Fields, Operators, Values, and Variables and Specify Query Filter Criteria.

Finding a list of work items

Task sequence for finding work items

The following two illustrations show the functions you can select from the Query Results view using the shortcut menu in Team Web Access or in Team Explorer. You can choose most of these functions when you have multiple work items selected.

Shortcut menu for query results (Team Web Access)

Team Web Access Work Item Shortcut Menu
Shortcut menu for query results (Team Explorer)

Team Explorer Work Item Shortcut Menu

Use queries to perform bulk modifications

You can quickly modify several fields for multiple work items using the shortcut menu for selected work items in Team Web Access. As the following illustration shows, you Step 1 select the work items, Step 2 choose Edit selected work item(s) from the shortcut menu, and Step 3 choose the fields and values that you want to modify. See Bulk modify work items

Bulk modify in Team Web Access

Bulk modify (Team Web Access)

Another option for making bulk edits is to export a query to Excel or to Project, modify values, and then publish your changes back to Team Foundation Server. Using the features of Excel and Project, you can perform bulk updates to column fields, augment a task break-down structure, upload additional work items to your team project, or generate an Excel report based on a work item query. Also, you can use Project to manage tasks and project schedules. See Bulk add or modify work items with Excel and Create your schedule, backlog, and tasks using Microsoft Project.

Add columns and sort the results view

You can add column fields and change the sort order of the query results list so that they are grouped in meaningful ways. Choose Column Options Column Options to add or remove fields. Choose the Sorting tab to choose the order of fields to use to sort the results. For additional information, see Add, Remove, Reorder, and Sort Columns.

The following illustration shows the column options used to display the Product Backlog query, with the addition of the Changed Date, State, and Business Value fields. With these additions, you can learn when changes were made to backlog items and stay focused on those items that have the highest priority.

Example query column options

You can change the query results view to display as a vertical stack, side-by-side view, or results-only view.

In Team Web Access, choose the bottom, right, and off links to cycle through these different views. The following illustration shows the Sprint Backlog query in a side-by-side view.

Query results side-by-side view

In Team Explorer, choose the Collapse upper panel or Collapse bottom panel buttons to collapse an upper or lower panel, or choose the Collapse left panel or Collapse right panel buttons to collapse the left or right panel.

Save, share, and email queries

You can create, save, copy, and rename work item queries. You can maintain your own set of queries or share them with other team members. When you save a query as a Shared Query all team members can view it. You can also set permissions on the query to restrict who can view or modify it. See Save, Copy, Rename, and Delete Work Item Queries and Organize and Set Permissions on Work Item Queries.

In addition to shared queries, you can share work items and query results with other team members by emailing a list or posting a link.

You can email a query list using TWA (with Quarterly Update 2 installed) or using Team Explorer.

In TWA, open the query and choose send query as email.

Send query by email (TWA)

To email a list of query results from Team Explorer, open the query and then choose Open in Microsoft Office, Send Query to Microsoft Outlook. For example, as a product owner, you might send the Active Product Backlog query to the team prior to each sprint planning meeting. The list contains links to each work item in the list, which opens the work item in TWA.

Email query results list

To get the link for a work item using Team Explorer, open the work item, open the shortcut menu for the tabbed item, and choose Copy Full Path. The link will open the work item in TWA.

Email a hyperlink for a work item

See Also

Concepts

Track Work and Manage Workflow

Other Resources

Process Guidance and Process Templates for Team Foundation Server