Query by area or iteration path
VSTS | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013
The Area Path and Iteration Path are two fields that appear on the work tracking form for all work item types. You define them for a project—area paths and iteration paths —and then select the ones you want to associate with a team.
To better understand how to work with area and iteration paths, see About area and iteration paths (aka sprints).
Supported operators and macros
When creating queries and specifying the Area Path and Iteration Path fields, you can use the following operators:
|Operator||Use when you want to...|
|=||Specify one specific area or iteration path|
|<>||Filter out one, specific area or iteration path.|
|In||Filter for a set of area or iteration paths.|
|Not In||Exclude items that are assigned to a set of area or iteration paths.|
|Under||Specify all paths under a select area or iteration path.|
|Not Under||Exclude items assigned under a specific area or iteration path.|
In addition to these operators, you can use the following macros when you select the Iteration Path. For examples, see Query by date or current iteration.
|Macro||Use when you want to...|
|@CurrentIteration||Specify the current iteration associated with the selected team context.|
|@CurrentIteration +/- n||Filter items based on assignment to a sliding window of sprints associated with the selected team context.|
|@TeamAreas||Filter items based on area path(s) assigned to a specific team.|
Feature availability: The @CurrentIteration macro is supported for VSTS and TFS 2015 and later versions. The @CurrentIteration +/- n and @TeamAreas macros are supported for VSTS.
Query for items assigned under several areas
You can specify to filter for work items assigned to several area paths by using the In operator as shown in the following example.
Or, you can use the Node Name and In to get the same results.
Query for items based on a keyword contained within several area paths
Using the Node Name field, you can filter on work items assigned to area paths based on a keyword using the Contains operator. The Node Name specifies the leaf node of an Area Path, which corresponds to the last node in the tree hierarchy.
In this example, the filter will return any work items assigned to an area path whose leaf node contains the word "Azure".
Query for items based on the leaf node of the area path
Another way to filter items based on the area path is to use the Node Name. The Node Name corresponds to the last node within the area path.
Query for items based on the area path assigned to a team
Use the @TeamAreas macro to quickly find items assigned to the area paths assigned to a specific team. Specify the = operator. The Query Editor automatically prompts for you to enter the name of the team. You can add it by typing the name of the team and choosing the team value that appears in the search filter criteria.
Classification field reference
|Field name||Description||Reference name|
|Area Path||Groups work items into product feature or team areas. The area must be a valid node in the project hierarchy.||System.AreaPath|
|Iteration Path||Groups work items by named sprints or time periods. The iteration must be a valid node in the project hierarchy.||System.IterationPath|
For each field, data path=
TreePath, reportable type=
Dimension, index attribute=
If you define a path name that is longer than 256 characters, you will not be able to specify it in Microsoft Project. To avoid this problem, define path names of no more than 10 characters, and do not nest nodes more than 14 levels deep.
You can't apply most field rules to the System.AreaPath and System.IterationPath fields. To learn more, see Apply a field rule.
The following fields do not appear on work item forms but are tracked for each work item type. These fields provide a numeric value for each classification value that is defined for a project. You can use these fields to filter queries and create reports.
|Field name||Description||Reference name||Data type|
|Area ID||The unique ID of the area to which this work item is assigned.||System.AreaId||Integer|
|Iteration ID||The unique ID of the iteration to which this work item is assigned.||System.IterationId||Integer|
|Node Name||The name of the leaf node of an area path. For example, if the area path is Project\A1\B2\C3, the node name is C3.||System.NodeName||String|
The default reportable type is none. Area ID and Iteration ID are indexed, Node Name is not. To learn more about field attributes, see Work item data type reference.
- Add another team
- Set team defaults
- Customize iteration paths
- Customize area paths
- Manage team assets
- Set permissions and access for work tracking
Supported field rules
For the Hosted XML and On-premises XML process models, you can apply rules to fields. However, for system fields (System.XXX), such as the Area Path and Iteration Path, you can specify only a small subset of rules, such as
READONLY to fields.
REST API and SDK resources
To programmatically interact with queries, see one of these REST API resources:
Or, for TFS 2015 and earlier versions, Query for Bugs, Tasks, and Other Work Items.