Query by date or current iteration

Last Update: 4/4/2017

Team Services | TFS 2017 | TFS 2015 | TFS 2013

Two query macros help you find work items based on when changes occurred or if they belong to the current sprint. To list work items based on when they were created, closed, resolved, or changed state─use @Today or specify dates. For queries that list work items based on their assignment to a team's current sprint, use @CurrentIteration.

For example, you can find work items that were modified in the last 3 days with the following query.

Editor query filter based on recent changes

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

Query for items based on when changes occurred

You can filter for work items by the date on which they were changed or for a specific time period. If you limit the scope of your query, it can help with performance by only returning those results that fit the date range that you want to include.

Filter for

Include these query clauses

Items created in the last 30 days

Created Date _ >= _ @Today-30

Items modified on a specific date

Changed Date _ = _ 7/14/2014

Items resolved today

Resolved Date _ = _ @Today

Items closed within a specified time period

           State _ = _ Done

And _ Closed Date _ > _ 7/1/2014

And _ Closed Date _ <= _ 7/21/2014

Items whose status was updated within the last week

State Changed Date _ <= _ @Today-7

Items closed in the current sprint

           State _ = _ Done

And _ Iteration Path _ = _ @CurrentIteration

Not all fields are valid for all work item types (WITs). Jump to date fields for the set of fields you can include in queries and which WITs they apply to.

Enter dates in the format accepted by your computer's operating system.

Query for items based on belonging to a team's current iteration

If your team follows Scrum processes, you schedule work to be completed in sprints. You can track the progress of requirements, bugs, and other work to be completed in the current sprint using the @CurrentIteration macro.

Prior to creating or updating a query to use the @CurrentIteration macro, make sure you select your team. The @CurrentIteration macro references the current team selected in the web portal.

Query filter using the @CurrentIteration macro

You can't use the @CurrentIteration macro from some clients, features, or REST APIs.

Date fields

You can use date fields to filter your queries. Some of these fields are populated with information as a work item progresses from one state to another. Several of these fields do not appear on the work item form, but they are tracked for those WITs listed in the following table.

Field name Description Work item type

Activated Date 1

The date and time when the work item was created or when its status was changed from closed, completed, or done to a new or active state.

Reference name=Microsoft.VSTS.Common.ActivatedDate, Data type=DateTime

All

Change Date

The date and time when a work item was modified.

Reference name=System.ChangedDate, Data type=DateTime

All

Closed Date 1

The date and time when a work item was closed.

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

All

Created Date

The date and time when a work item was created.

Reference name=System.CreatedDate, Data type=DateTime

All

Due Date

The forecasted due date for an issue to be resolved.

Reference name=Microsoft.VSTS.Scheduling.DueDate, Data type=DateTime

Issue (Agile)

Finish Date 2

The date and time when the schedule indicates that the task will be completed.

Reference name=Microsoft.VSTS.Scheduling.FinishDate, Data type=DateTime

Task, Bug

Resolved Date 1

The date and time when the work item was moved into a Resolved state.

Reference name=Microsoft.VSTS.Common.ResolvedDate, Data type=DateTime

Bug (Agile, CMMI)

Start Date 2

The date and time when the schedule indicates that the task will start.

Reference name=Microsoft.VSTS.Scheduling.StartDate, Data type=DateTime

Task, Bug

State Change Date

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

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

All

Target Date

The date by which a feature should be completed.

Reference name=Microsoft.VSTS.Scheduling.TargetDate, Data type=DateTime

Feature

Notes:

  1. For these fields to be defined for a WIT, they must be included in the WORKFLOW section of the WIT definition. For example, this syntax is included within the FIELDS definition when transitioning to a Resolved state:

     <FIELD refname="Microsoft.VSTS.Common.ResolvedDate />  
        <SERVERDEFAULT from="clock"  />  
     </FIELD >  
    
  2. Start and Finish Date fields are calculated if you create a project plan in Microsoft Project and then synchronize that plan with tasks that are stored in TFS or Team Services. These fields do not appear on the work item form, but they are calculated for those backlog items and tasks that are linked to backlog items. You can view their read-only values in results from a query or from Microsoft Excel or Project. For more information, see Create your backlog and tasks using Project.

To query for items based on text entered in the History field, see History and auditing.

Switch team view

You switch to a different team from the team project/team menu.

Switch teams from the team project - team menu

Client restrictions on the use of @CurrentIteration macro

You can use the @CurrentIteration macro in a query from the following clients:

  • Web portal that connects to VSTS

  • Web portal that connects to an on-premises TFS 2015 RC

  • Visual Studio 2015 RC or Team Explorer 2015 RC connected to TFS 2015 RC or VSTS.

An error occurs if you open a query that contains the @CurrentIteration macro in earlier versions of Visual Studio, or from Excel or Project. Also, the macro cannot be used when copying or cloning test suites and test cases, defining alerts, or with VSTS REST APIs.