Query by assignment or workflow changes in Azure Boards

TFS 2017 | TFS 2015 | TFS 2013

The states in the workflow support tracking work status as it moves from a new state to a closed or done state. Kanban query fields support tracking the status of work as it moves from one column or swimlane to another on the Kanban board.

Each workflow consists of a set of states, valid transitions between states, and reasons for transitioning the work item to the selected state. Workflow states and reasons differ among the work item types (WITs) and default processes used to create your project.

Most work items move from a New, Active, or Proposed state to a Done or Closed state. As each work item moves from one state to another, the item might also be reassigned to various members of the team. For example, a tester might create a bug that is assigned to another team member during triage. When the other team member resolves the bug, it's reassigned to the tester who created it.

For example, you can find all work items that were closed but then reactivated. By specifying the Changed Date field, you can focus on reactivations that occurred today, yesterday, or in the last week.

You can also use the Activated By and Activated Date fields, or other workflow fields.

Tip

Not all fields are valid for all WITs. Jump to Workflow and Kanban query fields for the set of fields you can include in queries and which WITs they apply to.

If you're new to creating queries, see Use the query editor to list and manage queries.

Supported operators and macros

Query clauses that specify an Identity or workflow-associated field can use the operators and macros listed in the following table. To learn about the field data type, see Workflow and Kanban board fields provided later in this article.

---

Data type

Supported operators and macros

---

Boolean ¹

= , <> , =[Field] , <>[Field]

---

DateTime

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever
Macros: @Today, @Today +/- n valid with any DateTime field

---

Identity

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever
Macros: @me valid for all Identity fields

---

Single text (String) ²

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever

---

Note

1. The Boolean data type field is supported for TFS 2017 and later versions.
2. The Was Ever operator is only valid for Kanban board columns for Azure DevOps Services at this time.

Use the In and Not In operators to filter for or exclude two or more picklist entries or a delimited set of items. Use the In Group or Not In Group operators to filter for items that belong or don't belong within a category group or security group. For more information, see Query fields, operators, and macros.

Identity-based queries

Use the search box or query editor to quickly find work items based on an assignment made to an Identity field. Also, you can filter for work items based on who changed, resolved, or closed a work item. By specifying a time period, you can scope your query even further, which can help with performance.

Use = to find current assignments, Was Ever to list items based on past assignments, and @Me to scope to your user identity.

Filter for

Include these query clauses

Active items assigned to me

            Assigned To @Me

And State = Active

Closed items that at some point was assigned to me

            Assigned To Was Ever @Me

And State = Closed

Active user stories assigned to my (Web) team

            Work Item Type = User Story

And State = Active

And Assigned To In Group [FabrikamFiber]\Web

Items I've modified in the last 30 days

            Changed By = @Me

And Changed Date >= @Today-30

Unassigned items (leave the Value blank)

            Assigned To = _

Team or group membership queries

To filter on items assigned to someone who belongs to a team or security group, use the In Group operator.

You can use the In Group or Not In Group operators to filter a query based on several values that are members of a group, or that aren't members of a group. Examples of groups you can specify include the following items:

• Teams
• Built-in and custom security groups
• Azure Active Directory and Active Directory security groups
• Work item categories

Queries based on workflow changes

You use the State, Reason, and Resolved Reason fields to query for items based on workflow changes.

Filter for

Include these query clauses

Resolved stories

            Work Item Type = User Story
And State = Resolved

Stories, bugs, and tasks that are new or active

            Work Item Type In User Story,Bug,Task
And State In New,Active

Items removed as they're duplicate

            State= Removed
And Reason = Duplicate

Items failing acceptance tests

Resolved Reason = Acceptance tests fail

Items closed within the last 15 days

            State = Closed
And Closed Date > @Today-15

Workflow changes and identity-based queries

You can quickly find items that you changed, resolved, or closed. You can also find items that were changed by other team members. Several fields—such as the Created By, Changed By, Resolved By, and Closed By—are populated based on changes to the workflow.

Filter for

Include these query clauses

User Stories that I closed

            Work Item Type = User Story
And Closed By = @Me

Items I resolved in the last week

            Resolved By = @Me
And Resolved Date >= Today-7

Query changes in work item state

To list work items that have changed state within a specific date range, you can use the State Change Date field to narrow the search and then add clauses for changes to the State field. An example is shown in the following image.

Query changes to a Kanban board

Using the Kanban query fields—Board Column, Board Column Done, and Board Lane—you can list work items according to their flow status on the Kanban board. And, you can create a status or trend chart based on these queries.

Note

Kanban query fields are available with TFS 2015.1 or later versions.

You can list items based on the team area path, and if they are in a specific custom Kanban column and swimlane. If you rename a column or swimlane, you'll need to update the query filters to reflect the new name. For more ideas, see this blog post: New fields bring Kanban goodness to queries, and more

Note

Queries are now scoped to the current project by default. Check the Query across projects to find work items defined in other projects within the collection.

Filter for

Include these query clauses

---

User Stories in the Code/Doing column

Work Item Type = User Story
And Board Column = Code
And Board Column Done = False

---

Items in the Expedite swimlane

Board Lane = Expedite

---

Items in any swimlane whose label contains "Test"

Board Lane Contains Test

---

Important

Work items that appear on more than one team's Kanban board can yield results that don't meet your expectations because each team can customize its Kanban board columns and swimlanes. The values assigned to Kanban Board Column, Board Column Done, and Board Lane fields might differ from what you expect when another team updates the work item from a different board. To learn more, see Add, review, and update work items in Azure Boards.

Workflow and Kanban board fields

The following fields are useful to filter queries. Some of these fields get updated as a work item progresses from one state to another. Or they're updated as you move a work item in the Kanban board to a different column or swimlane. Several of these fields don't appear on the work item form, but they're tracked for those work item types listed in the following table.

For more information about field attributes, see Work item fields and attributes.

Field name

Description

Work item type

---

Activated By ^{1, 2, 3}

The name of the team member who changed the status of a work item from New to Active or reactivated a work item after it had been closed, completed, or done. Reference name=Microsoft.VSTS.Common.ActivatedBy
Data type=String (Identity)

Bug, Change Request, Epic, Feature, Issue, Product Backlog Item, Requirement, Review, Risk, Shared Step, Task, Test Case, User Story

Activated Date ^{1, 3}

The date and time when the work item was changed from New to Active or reactivated after it had been closed, completed, or done. Reference name=Microsoft.VSTS.Common.ActivatedDate
Data type=DateTime

All

Assigned To  ^2, 3, 4

The name of the team member who currently owns the work item. For more information, see Note 1 on synchronization and person-name fields.

Reference name=System.AssignedTo
Data type=String (Identity)

All

Board Column

The current Kanban board column assignment of the work item, for example: Active, Closed, Committed, Done, or other custom column assignment.

Reference name=System.BoardColumn
Data type=String

Requirement Category ⁵

Board Column Done

The current assignment of the work item to Doing (False) or Done (True) Kanban column. Only assigned when split-columns is enabled for a Kanban board column.

Reference name=System.BoardColumnDone
Data type=Boolean

Requirement Category ⁵

Board Lane

The current Kanban board swimlane assignment of the work item, for example: Default, Expedite, Blocked, or other custom swimlane assignment.

Reference name=System.BoardLane
Data type=String

Requirement Category ⁵

Closed By ^{1, 2, 3}

The name of the team member who set the state to closed, completed, or done.

Reference name=Microsoft.VSTS.Common.ClosedBy
Data type=String (Identity)

All

Closed Date

The date and time when a work item was closed.

Reference name=Microsoft.VSTS.Common.ClosedDate
Data type=DateTime

All

Created By ^{1, 2, 3}

The name of the team member who created the work item.

Reference name=`System.CreatedBy
Data type=String (Identity)

All

Created Date

The date and time when a work item was created.

Reference name=System.CreatedDate
Data type=DateTime

All

Reason ^3, 4

The reason why the work item is in the current state. Each transition from one workflow state to another is associated with a corresponding reason.
For On-premises XML process models, the reason values are defined within the WORKFLOW section of the work item type definition using the REASON element. To modify the defined reasons, see Change the workflow for a work item type. Reference name=System.Reason
Data type=String

All (except Test Case and Shared Steps)

Resolved By ^1, 2, 3

The name of the team member who changed the status of a work item to Resolved or done workflow state. Reference name=Microsoft.VSTS.Common.ResolvedBy, Data type=String (Identity)

All

Resolved Date ^{1, 2}

The date and time when the work item was moved into a Resolved or done workflow state. Reference name=Microsoft.VSTS.Common.ResolvedDate, Data type=DateTime

All

Resolved Reason ³

The reason why a work item was resolved. For example, the user story is code complete or the bug is fixed. This field is read-only and only valid for Agile and CMMI work item types.

Reference name=Microsoft.VSTS.Common.ResolvedReason
Data type=String

All (Agile, CMMI)

Reviewed By

The name of the team member who responded to a code review request and is cataloged in the code review response.

Reference name=Microsoft.VSTS.Common.ReviewedBy
Data type=String (Identity)

Code Review Response

State ^{3, 4}

The current state of the work item. This field allows you to update the status of a work item as it progresses from new or active to a done or closed state.

To modify the workflow states, see Change the workflow for a work item type.
Reference name=System.State
Data type=String

All

State Changed Date

The date and time when the value of the State field changed.

Reference name=Microsoft.VSTS.Common.StateChangeDate
Data type=DateTime

All

1. See Date and Identity fields.

2. By default, the server synchronizes system-defined person-name or Identity-based fields with Active Directory or Azure Active Directory. These fields include: Activated By, Assigned To, Closed By, Created By, and Resolved By. You can grant access to a project by adding security groups that you created in AD or Azure AD or by adding accounts to existing or custom groups defined from the collection setting Security page. See set up Active Directory or Azure Active Directory.

   For on-premises deployments, you can enable or disable synchronization for a person-name field by using the witadmin changefields command-line tool. You can also synchronize custom person-name fields by specifying the syncnamechanges attribute. See Manage work item fields and FIELD (Definition) element reference.

3. Reportable field with attribute set to Dimension. Only valid when the collection is configured to support the On-premises XML model. Reportable data is exported to the data warehouse and can be included in Excel or SQL Server reports. For on-premises Azure DevOps, use the witadmin changefield command to change the reportable attribute for a field.

4. Indexed field. Enabling indexing for a field may increase the performance of finding work items whose queries specify that field. For on-premises Azure DevOps, use the witadmin indexfield command to change the index attribute for a field.

5. The Requirement Category applies to all work item types that appear on the product backlog and Kanban board. The category includes those items added to the Bug Category based on the team setting for Show bugs on boards and backlogs. For more information on work item type categories, see Use categories to group work item types.

Note

Even if you add a board-related field, such as Board Column or Board Lane, to a work item form, you can't modify the field from the form.

People picker

The Assigned To field is supported by the people picker feature. For example, when you choose the Assigned To field from within a work item form, the people picker is activated. As shown in the following image, you simply start typing the name of the user you want to select, and search until you find a match. Users that you've previously selected appear in the list automatically. To select users that you haven't selected previously, enter their entire name or search against the full directory.

For organizations that manage their users and groups using Azure Active Directory (Azure AD) or Active Directory, people pickers provide support for searching all users and groups added to the AD, not just those users and groups added to the project.

Date and identity fields

Several date and identity fields are set based on workflow states or transitions. Some fields, such as Created By and Created Date, are set by the system when a work item is added. Other fields, such as Closed Date and Closed By, are set through the workflow definition of the work item type. Additionally, customized work item types may have other rules defined that influence the date and identity field assignments.

State changes

The following XML syntax example illustrates rules that may be defined for a work item type that govern the values for select fields. Here, the Resolved Date, Resolved By, Closed Date, Closed By, Activated Date, and Activated By fields are set to EMPTY when a State value is set to New. The State value assignments are evaluated first, and then the transition assignments are evaluated next.

   <WORKFLOW>
      <STATES>
        <STATE value="New">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedDate">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedBy">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
              <EMPTY />
            </FIELD>
          </FIELDS>
        </STATE>
        <STATE value="Active">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedDate">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedBy">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
              <EMPTY />
            </FIELD>
          </FIELDS>
        </STATE>
        <STATE value="Resolved">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
              <EMPTY />
            </FIELD>
            <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
              <EMPTY />
            </FIELD>
          </FIELDS>
        </STATE>
        <STATE value="Closed" />
      </STATES>

Activated By and Activated Date transition assignments

When the following transitions occur for a Bug work item, then the following assignments are made to the Activated By and Activated Date fields:

<TRANSITION from="" to="New">
<TRANSITION from="New" to="Active">
<TRANSITION from="New" to="Resolved">
<TRANSITION from="New" to="Closed">
<TRANSITION from="Resolved" to="Active">
<TRANSITION from="Closed" to="Active">

<FIELDS>
   <FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
       <COPY from="currentuser" />
           <VALIDUSER />
           <REQUIRED />
    </FIELD>
    <FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
        <SERVERDEFAULT from="clock" />
   </FIELD>
</FIELDS>

And when the following transitions occur for the Bug work item:

<TRANSITION from="Active" to="New">
<TRANSITION from="Active" to="Closed">
<TRANSITION from="Resolved" to="Closed">

Then the Activated By and Activated Date fields are set to READONLY.

<FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
   <READONLY />
</FIELD>
<FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
   <READONLY />
</FIELD>

Related articles

• How workflow states and state categories are used in Backlogs and Boards
• Query by date or current iteration
• Query quick reference
• Work item fields and attributes
• Query permissions

SDK resources

To programmatically interact with queries, see Query for Bugs, Tasks, and Other Work Items.