Query by assignment or workflow changes in Azure Boards

Article
10/25/2021

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - 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

The Boolean data type field is supported for TFS 2017 and later versions.
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.

Filter based on assignment to a TFS security group

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.

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 fields

You can use the following fields to filter your queries or build reports. Some of these fields are populated with information as a work item progresses from one state to another. Several of these fields don't appear on the work item form, but they're tracked for those WITs 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

By default, the server synchronizes system-defined person-name fields with Active Directory or Azure Active Directory, if these components are configured. 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.

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.
Reportable field with attribute set to Dimension. Reportable data is exported to the data warehouse and can be included in Excel or SQL Server reports. For on-premises server, use the witadmin changefield command to change the reportable attribute for a field.
Indexed field. Enabling indexing for a field may increase the performance of finding work items whose queries specify that field. For on-premises server, use the witadmin indexfield command to change the index attribute for a field.

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.

Screenshot of people picker

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.

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>

SDK resources

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

Share via

Query by assignment or workflow changes in Azure Boards

Supported operators and macros

Identity-based queries

Team or group membership queries

Queries based on workflow changes

Workflow changes and identity-based queries

Query changes in work item state

Workflow fields

People picker

State changes

Activated By and Activated Date transition assignments

SDK resources

Additional resources

Share via

Query by assignment or workflow changes in Azure Boards

Supported operators and macros

Identity-based queries

Team or group membership queries

Queries based on workflow changes

Workflow changes and identity-based queries

Query changes in work item state

Workflow fields

People picker

State changes

Activated By and Activated Date transition assignments

Related articles

SDK resources

Additional resources