Customize area and iteration paths

Last Update: 11/29/2016

Team Services | TFS 2017 | TFS 2015 | Previous versions

Area paths allow you to group work items by team, product, or feature area. And iteration paths allow you to group work into sprints, milestones, or other event-specific or time-related period.

Newly created team projects contain a single, root area that corresponds to the team project name. Whereas, new team projects typically specific a predefined set of iterations to help you get started tracking your work.

The iterations you see depend on the process you used to create your team project. Here we show the defaults defined for the Scrum process. No dates are set. You set dates to correspond to your sprint or release schedules.


The images you see from your web portal may differ from the images you see in this topic. These differences result from updates made to Team Services or your on-premises TFS, options that you or your admin have enabled, and which process was chosen when creating your team project—Agile, Scrum, or CMMI. However, the basic functionality available to you remains the same unless explicitly mentioned. For an overview of changes in the navigation experience and working within the user and administration contexts, see Work in the web portal.

Default iterations, Scrum process Default areas

Agile tools that rely on areas or iterations

Several Agile tools reference the team's default area path, iteration path, and activated sprints to automatically filter the set of work items they display. Here's a quick summary of these tools:

Many of these tools are built from system queries that reference the team area path. For example, a team’s default area path filters the work items that appear on a team’s backlog. Also, work items that you create using an Agile tool auto-assign the areas and iterations based on team defaults.

You can view these queries by choosing the Create query link that appears on these tools’ pages. (Note that you can’t change the underlying query.) Lastly, you can set security permissions to control who has access to create, modify, or manage test plans and test suites under an area.

Team defaults referenced by backlogs and boards

Note: Some features are available only from Team Services or TFS 2017 or later versions. For details, see Set team defaults.

When you define a team, you define the team's:

  • Selected area path(s)
  • Default area path
  • Selected iteration path(s)
  • Backlog iteration path
  • Default iteration path

All Agile tools reference the area path(s) defined for a team. For example, one team might handle all work assigned to Customer Profile and Shopping Cart, while another team only manages work assigned to the Email area path. Also, the set of work items that appear on a backlog or board depend on the current State of a work item or it's parent-child status.

In addition, several tools reference the team's default iteration and selected iteration paths or sprints. For example, when you add new work items from a backlog or board view, or from a team dashboard, the system assigns the team's default area path and default iteration path to these work items.

Agile tool Area path
(see note 1)
Iteration path State
Portfolio or product backlogs Selected area path(s) Equal to or under team’s backlog iteration path Active (corresponds to a Proposed or InProgress state category, see notes 2, 3)
Kanban boards (see note 4) Selected area path(s) Equal to or under team’s backlog iteration path Any state (see notes 3, 5)
Sprint backlogs (see note 4) Selected area path(s) Team’s selected iteration paths Any state (see notes 3, 5)
Task boards (see note 4) Selected area path(s) Team’s selected iteration paths Any state (see notes 3, 5)
New work item widget Default area path Default iteration path n/a


  1. Agile tools filter items based on the team's selected area path(s). Teams can choose whether to include or exclude items assigned to subarea paths.
  2. Work items whose State equals Closed, Done, or Removed (corresponding to a Completed category state) don't appear on portfolio and product backlogs.
  3. You can add custom workflow states and assign them to one of three state categories. The state categories determine which work items appear on backlog and board views.
  4. Kanban boards, sprint backlogs, and task boards only show the last node in a hierarchy, called the leaf node. For example, if you link items within a hierarchy that is four levels deep, only the items at the fourth level appear on the Kanban board, sprint backlog, and task board. To learn more, see parent-child links between items.
  5. Work items whose State equals Removed don't appear on boards.

Add an area

  1. From the web portal, open the admin page for the team project.

    Note: For an overview of the administration context and the new navigation experience supported in Team Services, see Work in the web portal.

    Open the project administration page

    To manage areas and iterations you need to be a project administrator or have the Create child nodes permission for an area path. If you aren’t a project administrator, get added as one or have someone provide you with explicit permissions to Edit project-level information.

    If you want to add area paths to support teams, you can do that when you add teams to your team project.

    Certain restrictions apply on names of areas.

Add area paths (Team Services)

  1. Open the Work, Areas page for the team project context.

    If you haven't added any areas or teams, you'll see that only one area is defined.

    Areas, defaults defined for team project
  2. Add a new child node to the area you have selected.

    TFS 15, Areas, Create a new area node

Add area paths (TFS 2017)

  1. Open the Work, Areas page for the team project context.

    If you haven't added any areas or teams, you'll see that only one area is defined.

    Areas, defaults defined for team project
  2. Add a new child node to the area you have selected.

    TFS 15, Areas, Create a new area node

Add area paths (TFS 2015)

  1. Open the Areas tab.

    Open the areas page defined for team project

    From the areas page, you can set the default area path used to filter the backlog. The default area path is also used when new work items a user creates new work items.

  2. Add a new child node to the area you have selected.

    Create a new area node

Add an iteration and set iteration dates

From the Iterations page, you can add and select the iterations that will be active for your team. You add iterations in the same way you add areas. For more information about working within a sprint cadence, see Define sprints.

Schedule sprints (Team Services)

  1. Open the Work, Iterations page for the team project context.

    For Scrum-based team projects, you’ll see these set of sprints.

    Work, Iterations page, Team Services platform

    If you need to select another team project, go to the Overview page for the collection (click the DefaultCollection link).

  2. Schedule the start and end dates for each sprint your teams will use. Click Set dates or choose to edit the iteration from the Actions icon actions menu for the sprint.

    Edit iteration, schedule start date, Team Services platform
  3. When you're finished, you have a set of sprints scheduled - like this:

    Work, Iterations page, scheduled set of sprints, Team Services platform

    Your next step is to activate the sprints each team will use.

Schedule sprints (TFS 2015)

  1. Open the Iterations tab for the team project context.

    For Scrum-based team projects, you’ll see these set of sprints.

    Example Iterations for a Team

    You can change the name, location within the tree hierarchy, or set dates for any sprint. Simply open it (double-click or press Enter key) and specify the info you want.

  2. Schedule the start and end dates for those sprints you plan to use.

    Define start and end dates for a sprint

    After you set the start and end dates for one iteration, the calendar tool automatically attempts to set the next set of dates, based on the same iteration length you specified for the first. For example, if you set a three week sprint for Sprint 1, then when you select the start date for Sprint 2, the calendar tool automatically determines the start and end dates based on the next three weeks. You can accept or change these dates.

  3. To add another sprint, select New child and name it what you want. Here, we call it Sprint 7.

    Iterations, defaults defined for Agile

    Your next step is to activate the sprints each team will use.

Set permissions to restrict access to work items

Permissions placed on an area paths allows you to permit or restrict access to edit or modify work items, test cases, or test plans assigned to those areas. You can restrict access to users or groups. You can also set permissions for who can add or modify areas or iterations for the team project.

  1. Open the Security dialog for the node you want to manage.

    Open the security dialog

  2. Select the group or team member, and then change the permission settings. For example, for the Disallow Access Group, deny the ability to view, modify, or edit work items in the FabrikamFiber area path.

    Permissions for an area node

    If the group or team member doesn’t appear in the list, you can Add it.

You can specify two explicit authorization states for permissions: Deny and Allow. In addition, permissions can exist in one of three additional states.

Permission Authorization
Allow Explicitly grants users to perform the task associated with the specific permission. For users to access a task, the associated permission must be set to Allow or Inherited allow.
Deny Explicitly prevents users from performing the task associated with the specific permission. Deny takes precedence over Allow.
For exceptions to these rules, see Permissions reference
Inherited allow/Inherited deny Allows or denies a user to perform the task associated with the permission based on the permission set for a group to which the user belongs.
Not set Implicitly prevents users from performing the action associated with the permission.
Because the permission is neither explicitly set to Deny nor explicitly set to Allow, authorization for that permission can be inherited from other groups of which the user or group is a member.
By default, most permissions are not set to either Deny or Allow, the permissions are left Not set.

For additional ways to restrict modifications to work items, see Restrict who can create or modify a work item.

Test management permissions

Area permissions for web-based test case management and test execution control access to the following actions.

The Manage test suites permission enables users to:

  • Create and modify test suites
  • Add or remove test cases to/from test suites
  • Change test configurations associated with test suites
  • Modify the suite hierarchy by moving a test suite

The Manage test plans permission enables users to:

  • Create and modify test plans
  • Add or remove test suites to or from test plans
  • Change test plan properties such as build and test settings

Additional test management permissions are assigned at the team project level and include the ability to create, delete, and view test runs, and manage test configurations and environments. See Project, object, and test-level permissions.

As you can see, areas and iterations play a major role in supporting Agile tools and managing work items. You can learn more about working with these fields from these topics:

Required permissions

To create or modify areas or iterations, you must either be a member of the Project Administrators group, or your Create and order child nodes, Delete this node, and Edit this node permissions must be set to Allow for the area or iteration node that you want to modify.

Chart progress by area or iteration

You can quickly generate queries to view the progress for those areas and iterations. As an example, you can visualize progress of work items assigned to sprints as shown in the following stacked bar chart.

Stacked bar chart by area

Rename or delete an area or iteration node

When you rename an area or an iteration, or move the node within the tree hierarchy, the system will automatically update the work items and queries that reference the existing path or paths.

When you delete an area or an iteration node, the system automatically updates the existing work items with the node that you enter at the deletion prompt.

Classification field reference

These fields appear on the forms for all WITs.

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=True.

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

Naming restrictions

The Area Path and Iteration Path fields, data type=TreePath, consist of multiple node items which are separated by the backslash (\) character. We recommend that you minimize the names of nodes, and make sure that you conform to the following e restrictions when adding child nodes:

Restriction type Restriction
Node length Must not contain more than 255 characters
Special characters for nodes Must not contain Unicode control characters
Must not contain any of the following characters: \ / $ ? * : " & > < # % + ,
Must not contain characters that the local file system prohibits.
Reserved names Must contain more than a period (.) or two periods (..)
Must not be a system-reserved name such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, or AUX
Path length Must contain fewer than 4,000 Unicode characters
Path hierarchy depth Must be fewer than 14 levels deep

Supported field rules (TFS)

You can specify only a small subset of rules, such as HELPTEXT and READONLY to System.XXX fields.

Export tree structures

You can’t export the structure of tree paths for one team project to use with another team project.

Team field versus team area path

If your organization has several teams that work from a common backlog and across many product areas, you might want to change how teams are configured. By adding a custom field to represent teams in your organization, you can reconfigure the agile planning tools and pages to support your teams and decouple assignment to teams and area paths.


How do I structure teams, areas, and iterations to support hierarchical teams or scale agility within an enterprise?

Although there is no concept of sub-teams, you can create teams whose area paths are under another team, which effectively creates a hierarchy of teams. To learn more, see Add another team.

Also, these topics can walk you through the steps for configuring teams, area paths, and iterations to support portfolio management or enterprise organizations: Portfolio management and Implement Scaled Agile Framework to support epics, release trains, and multiple backlogs.

What kind and how many areas should a team define?

You add areas to support your team's trace-ability and security requirements. Use areas to represent logical or physical components, and then create child areas to represent specific features.

Add areas when you have these requirements:

  • Filter queries based on a product or feature area
  • Organize or group work items by team or sub-teams
  • Restrict access to work items based on their area.

Each team can create a hierarchy of areas under which the team can organize their backlog items, user stories, requirements, tasks, and bugs.

Avoid creating an area structure that is too complex. You can create areas to partition permissions on work items, but complex trees require significant overhead for permission management. You might find that it is too much work to duplicate the structure and permissions in other team projects.

What kind and how many iterations should a team define?

You define as many child iterations as you need to reflect your project lifecycle. These paths represent a series of events, such as sprints, pre-beta and beta deliverables, and other release milestones. Teams typically leave work items assigned to the team's default iteration if they are not yet scheduled for work or for a release.

Add iterations to support these requirements:

  • Define sprints your Scrum teams use to plan and execute their sprints
  • Set up more complex multi-release and sprint cycles
  • Filter queries based on sprints, milestones, or cycle time for your project
  • Support future work that you’re not ready to assign to a target release cycle.

In the following example, Backlog, Beta 1, Beta 2, Release 1.0, and Release 2.0 are defined for the MyApplication team project.

Flat iteration hierarchy

As you create the backlog of product features and tasks, you can start to assign them to the milestones by which you expect the team to finish the features and tasks. As your needs change, you can add events under each major milestone that reflect how your team schedules and manages its work.

As the following example shows, the Beta 1 iteration now contains three child nodes, one for each sprint in the Beta 1 time period.

Hierarchical Iteration Hierarchy

Iterations do not enforce any rules. For example, you can assign a task to an iteration but not close or complete it during that iteration. At the end of an iteration, you should find all work items that remain active or have not been closed for that iteration and take appropriate action. You can, for example, move them to a different iteration or return them to the backlog.