Breyta

Deila með

Query by assignment or workflow changes in Azure Boards

  • Grein

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

The states in the workflow support tracking work status as it moves from a new state to a closed or done state. Query fields support tracking the status of work as it moves from one column or swimlane to another on the 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 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.

Query Editor filter for reactivated items.

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

Tip

Not all fields are valid for all work item types. Jump to Workflow and query fields for the set of fields you can include in queries and which work item types 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 board fields provided later in this article.

Data type

Supported operators and macros

Boolean 1

= , <> , =[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) 2

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

Use the In and Not In operators to filter for or exclude two or more pick list 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.

Date and time pattern

The date and time pattern you enter for DateTime fields should match that which you select through your profile. To view or change your selection, see Set user preferences.

Screenshot that shows the Date Pattern dropdown options on the Time and Locale pane. Screenshot that shows the Time Pattern dropdown options on the Time and Locale pane.

Screenshot that shows the Time and Locale pane with Date pattern and Time pattern fields.

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 the 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.

Screenshot of Query Editor, Filter based on assignment to a 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
  • Microsoft Entra ID 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.

Screenshot of Query Editor, filter State Change Date and State fields.

Query changes to a board

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

You can list items based on the team area path, and if they are in a specific custom 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 goodness to queries, and more

Screenshot of Query Editor, filter on board Column and Board Lane fields.

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

Items that were ever in the "In Review" column

Board Column Was Ever In Review

Important

Work items that appear on more than one team's board can yield results that don't meet your expectations because each team can customize its board columns and swimlanes. The values assigned to 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. For more information, see Add, review, and update work items in Azure Boards.

Workflow and 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 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 to an In Progress category state.

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 to an In Progress category state.

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

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 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 4

Requirement Category 5

Board Column Done

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

Reference name=System.BoardColumnDone
Data type=Boolean

Requirement Category 4

Requirement Category 5

Board Lane

The current 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 4

Requirement Category 5

Closed By 1, 2

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

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

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.

Reference name=System.Reason
Data type=String

All (except Test Case and Shared Steps)

Resolved By 1, 2

Resolved By 1, 2, 3

The name of the team member who changed the status of a work item to a Resolved category state.

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

Resolved Date 1, 2

The date and time when the work item was changed to an In Resolved category state.

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

Resolved Reason 3

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

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 Customize the workflow for a process.

To modify the workflow states, see the following articles:

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

Note

  1. See Date and Identity fields.
  2. By default, the server synchronizes system-defined person-name or Identity-based fields with Active Directory or Microsoft Entra ID. 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 Active Directory or Microsoft Entra ID or by adding accounts to existing or custom groups defined from the collection setting Security page. See set up Active Directory or Microsoft Entra ID.
  3. See Activated By/Date and Resolved By/Date fields.
  4. The Requirement Category applies to all work item types that appear on the product backlog and board, and may include those 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.

  1. See Date and Identity fields.

  2. By default, the server synchronizes system-defined person-name or Identity-based fields with Active Directory or Microsoft Entra ID. 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 Active Directory or Microsoft Entra ID or by adding accounts to existing or custom groups defined from the collection setting Security page. See set up Active Directory or Microsoft Entra ID.

    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 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 entering 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 the <span class=@mention tool in Discussion showing people picker." />

For organizations that manage their users and groups using Microsoft Entra ID 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.

To limit the scope of identities available for selection to just those users added to the project, you can do so using the Project-Scoped Users group. For more information, see Manage your organization, Limit identity search and selection.

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.

Date and time pattern

The date and time pattern you enter for DateTime fields should match that which you select through your profile. To view or change your selection, see Set user preferences.

Screenshot that shows the Date Pattern dropdown options on the Time and Locale pane. Screenshot that shows the Time Pattern dropdown options on the Time and Locale pane.

Screenshot that shows the Time and Locale pane with Date pattern and Time pattern fields.

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>

Activated By/Date and Resolved By/Date fields

The system updates these fields—Activated By, Activated Date, Resolved By, and Resolved Date—when a change occurs based on corresponding workflow category states. When the workflow state changes to an In Progress state category, Activated By and Activated Date are updated. When the workflow state changes to a Resolved state category, Resolved By and Resolved Date are updated.

To learn more how workflow states map to state categories, see How workflow states and state categories are used in Backlogs and Boards.

Note

The logic governing the fields described here applies to Azure DevOps Services, Azure DevOps Server 2020.1 update, and later versions.

Because these fields reference the workflow state categories, custom workflow states that you add are referenced when updating the fields. To learn more about customization, see Customize the workflow for a process.

Additional notes:

  • The fields get updated anytime a work item moves from any category state other than that being set. For example, if you update a work item from New to Fixed, the Resolved By/Resolved Date fields are updated. However, if you update from Fixed and Ready for Testing—which are in the same category state—the Resolved By/Resolved Date fields aren't updated.
  • When you transition backwards, such as going from a Resolved to an Active state, the system clears the values for Resolved By/Resolved Date fields. If you got from Active to New, the system clears the values for Activated By/Activated Date fields.
  • Don't manually change the values for these fields. They are system fields that are governed by system rules. Any value you attempt to set gets over written.

REST API

To programmatically interact with queries, see one of these REST API resources: