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.

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.

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.

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

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.

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

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.

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.

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.