View, run, or email a work item query

Azure Boards | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

To find work items assigned to you or your team, run a query. A number of work item queries are predefined with your process. Also, members of your team may have created shared queries that you can view and run. Oftentimes, it's easier to define a new query by building on the query definition that's already available to you.

Prerequisites

By default, all project members and users with Stakeholder access can view and run all shared queries. You can change the permissions set for a shared query folder or shared query. For details, see Set query permissions.

  • You must connect to a project. If you don't have a project yet, create one.
  • To view, run, or email a query, you must be granted Stakeholder access or higher. For details, see About access levels.
  • To add and save a query under Shared queries, you must be granted Basic access or higher. Also, you must have your Contribute permission set to Allow for the folder you want to add the query to. By default, the Contributors group doesn't have this permission.

Note

Users with Stakeholder access for a public project have full access to query features just like users with Basic access. For details, see About access levels.

  • You must connect to a project. If you don't have a project yet, create one.
  • To view, run, or email a query, you must be granted Stakeholder access or higher. For details, see .
  • To add and save a query under Shared queries, you must be granted Basic access or higher. Also, you must have your Contribute permission set to Allow for the folder you want to add the query to. By default, the Contributors group doesn't have this permission.

Open Queries

From your web browser, (1) check that you have selected the right project, (2) choose Boards>Queries, and then (3) choose All.

Open Boards>Queries, vertical nav

If it is your first time opening Work, the page opens to Favorites which lists all queries you have favorited. Otherwise, you can choose All to view all queries you've defined and shared queries defined for the project.

Tip

Queries you or your team have favorited show up on the Favorites page. Queries you have favorited along with other objects also appear on your Project page. To learn more, see Set personal or team favorites.

From your web browser, open Boards>Queries.

Web portal, choose Boards>Queries

Run a query

To run any query, expand a folder and choose the title of the query. The view opens to display the query Results.

Tip

The Queries page, as with other web portal pages, remembers the view you last navigated to and returns you to that view.

  1. Choose All to open the page where you can view all queries you've defined or that are shared within your project.

    Web portal, choose Boards>Queries>All page

  2. Choose My Queries as needed.

    • To view all work items assigned to you, choose Assigned to me. This query uses the @Me macro to list all work items assigned to you.
    • To view all work items you are following, choose Followed work items. This query uses the @Follows macro (ID in @Follows) to list all work items you've elected to follow. To learn more, see Follow a work item or pull request.
  3. Choose Shared Queries to expand the folder and access queries saved as shared queries.

  4. Choose a folder within a breadcrumb to open a query folder.

    queries breadcrumb example

Tips for working with the directory-focused Queries pages

The Queries page now contains a directory-focused view which you can filter to find specific queries of interest. Previously, the Queries page presented the queries folders, query editor, and query results all within the same view.

With this change, some functionality has been added and some has changed. Here are some tips to find the work items of interest:

Where can I find work assigned to me or work that I'm following?

Open Queries>All. Under the My Queries section are two fully customizable queries: Assigned to me and Followed work items.

Where can I find recent work item activity?

  • Open Boards>Work Items and select the Recently updated view. See View and add work items.

  • You can also use the macros — @Me, @Follows, MyRecentActivity, @RecentMentions, @RecentProjectActivity — to create custom queries that can filter for work items assigned to you, that you are following, and so on. To learn more about these macros, see Query macros and variables.

How do I quickly navigate to queries I view frequently?

  • Favorite those queries and other artifacts that you view frequently. Choose the  star icon to favorite a query.

  • Favorited queries ( favorited icon) are listed in the Queries>Favorites page. Also, you can select one from the queries selector, as shown in the following image.

    queries selector
    Or, you can select from any of your favorited items by choosing the  inbox icon and choose Favorites.

    queries selector

How do I quickly navigate to queries within the same query folder?

When viewing a query, you can use the queries breadcrumb selector ( the breadcrumb icon changes to  a context menu selector) to view the queries defined within the folder. To open the queries folder, choose the folder name.

queries breadcrumb example

Can I run several queries at the same time?

Yes. Simply open a query in a new browser tab to run several queries at the same time.

How can I best use queries to monitor progress on a project or team?

View, rename, or delete a query

From either the Favorites or All page, choose the  actions icon of a query to run, edit, rename, or delete the query.

New query experience, Favorites page, query context menu

For shared queries, you can also choose to perform one of these tasks:

  • Add to team queries: Select the team to add the query as a team favorite
  • Security...: to set permissions for the query. To learn more, see Set query permissions.
  • Add to dashboard: Adds a Query tile widget to the team dashboard you select. To learn more, see Add widgets to a dashboard.

Choose the  context menu icon of a query to edit, rename, or delete the query.

Web portal, Boards>Queries, Open Shared queries, Active Bugs

Tasks you can perform from the Favorites or All pages

You can perform most tasks for viewing and running queries from each of the queries list pages as indicated in the following table. Only queries you save under My Queries and have favorited show up under My Favorites. Only queries saved under Shared Queries can be favorited by a team.

Task Favorites All
View all favorited queries, yours or a team you belong to Checkmark
View all your queries or shared queries for the current project Checkmark
Run a query, open the context menu for a query Checkmark Checkmark
Expand or collapse container folders or query folders Checkmark Checkmark
Filter the list of queries Checkmark Checkmark
Favorite a query: Click Favorite Checkmark
Unfavorite a query: Click Un-favorite Checkmark Checkmark
Add a new query: Click plus sign Checkmark Checkmark

For details on adding new queries, see Create managed queries with the query editor.

Filter the list of queries

Enter a keyword into the filter box to filter the set of queries displayed on either the Favorites or All pages.

List of all queries in the project filtered by WIT IQ keyword criteria

Email query items or share a query URL

From the Query Editor or Results view, you can email a formatted list of query items or copy the query URL.

Choose the  actions icon to open the menu and select from the options listed, Email query or Copy query URL.

Web portal, Query Editor/Results, Open Actions menu, Choose Email query or Copy query URL
You can only send the email to individual address for a project member that is recognized by the system. Adding a team group or security group to the to line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed work items.

Note

To email a formatted list to people who aren't project members, you'll need to use the Copy as HTML option described in Copy a list of work items.

Choose Copy query URL. To email query items, see Copy a list of work items.

Web portal, Query Editor/Results, Copy query URL

Note

With Email query, the system will email the formatted list to those teammates you select. To email a formatted list to people not part of the project, you'll need to use the Copy as HTML option described in Copy a list of work items. For on-premises TFS, all email actions require an SMTP server to be configured. If you don't have an SMTP server configured, you can work around this by using Copy as HTML.

Try this next