About area and iteration (sprint) paths

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

Area paths allow you to group work items by team, product, or feature area. Iteration paths allow you to group work into sprints, milestones, or other event-specific or time-related period. Both these fields allow you to define a hierarchy of paths.

You define area and iteration paths for a project. Teams can then choose which paths are used to support their backlog and other Agile tools. To understand how Agile tools use area and iteration paths, see Agile tools that rely on areas and iterations.

Note

Area paths and iteration paths are also referred to as Classification Nodes. You can manage them programmatically via the Classification Nodes (REST API) or the Azure DevOps CLI command az boards iteration.

The areas and iterations you see depend on the process you used to create your 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.

Iterations	Areas

Important

Deleting Area Paths or reconfiguring Iteration Paths can cause a loss of data and can't be reverted. For example, burndown or burnup widget charts, sprint burndown, and velocity charts for teams whose Area Paths are changed won't reflect correct data. Historical trend charts reference the Area Path and Iteration Path as defined at a point in the past for each work item. When an Area Path or Iteration Path is deleted, then the historical data for it can't be retrieved.

Define and assign area paths

If you're new to managing projects and teams, the most straight forward sequence for configuring your project and teams is as follows.

1. Determine the number and names of Area Paths that you want to support to categorize your work. At a minimum, add one area path for each team that you define.
2. Determine the number and names of teams you want to support. For guidance, review About teams and Agile tools.
3. Open Project settings > Project configuration and define the area paths to support steps 1 and 2 at the project level. Follow the steps provided later in this article: Open Project Settings, Project configuration and Add area paths.
4. Define the teams you need to support step 2. For guidance, see Add a team, move from one default team to several teams.
5. Open the team configuration and assign the default and additional area path(s) to each team. Follow the steps provided later in this article: Open team settings and Set team default area path(s).
6. Assign the area path of work items to an area path you defined. Use bulk modify to modify several work items at once.

Note

Projects are limited to defining a maximum of 10,000 Area Paths, and assigning a maximum of 300 Area Paths to a single team. To learn more, see Work tracking, process, and project limits.

Also, while you can assign the same Area Path to more than one team, this can cause problems if two teams claim ownership over the same set of work items. To learn more, see About boards and Kanban, Limitations of multi-team Kanban board views.

As needed, you can do the following actions at any time:

• Add additional child nodes
• Rename an area path (except the root area path)
• Move a child node under another node
• Delete a child node
• Rename a team
• Change the area path assignments made to a team

See also, Configure a hierarchy of teams.

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 subteams
• 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's too much work to duplicate the structure and permissions in other projects.

Define and assign iteration paths

Use the following guidance to configure Iteration Paths for your project and teams:

1. First, define the area paths and teams following the guidance provided in Define area paths and assign to a team.
2. Determine the length of the iteration you want to support. Recommended practice is to have all teams use the same sprint cadence.
3. Determine if you want a flat structure or hierarchy of sprints and releases.
4. Open Project settings > Project configuration and define the iteration paths to support steps 2 and 3 at the project level. Follow the steps provided later in this article: Open Project Settings, Project configuration and Add iterations and set iteration dates.
5. Open the team configuration and assign the default, backlog, and additional iteration path(s) to each team. Follow the steps provided later in this article: Open team settings and Set team default iteration path(s).
6. Each team should assign an iteration path to their work items that falls under the Backlog iteration path. Those work items will then show up on their product backlogs and boards. Use bulk modify to modify several work items at once. See also Assign backlog items to a sprint.

Note

Projects are limited to defining a maximum of 10,000 Iteration Paths, and assigning a maximum of 300 Iteration Paths to a single team. To learn more, see Work tracking, process, and project limits.

As needed, you can do the following actions at any time:

• Add additional child iteration nodes
• Rename an iteration path (except the root path)
• Move a child iteration path under another node
• Delete a child iteration path
• Change the default and selected iteration paths assigned to a team

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 results, and other release milestones. A team usually leaves work items assigned to the team's default iteration if they aren't 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, Beta 1, Beta 2, Release 1.0, and Release 2.0 are defined for the MyApplication project.

As you create the backlog of product features and tasks, assign them to milestones. Assign the features and task by which you expect the team to finish. 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.

Iterations don't 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 open for that iteration and take appropriate action. You can, for example, move them to a different iteration or return them to the backlog.

Naming restrictions

The Area Path and Iteration Path fields, data type=TreePath, consist of multiple node items separated by the backslash (\) character. Minimize the names of nodes and make sure you conform to the following restrictions when you're adding child nodes.

Restriction type	Restriction
Node length	Must not contain more than 255 characters.
Reserved names	- Must not consist only of 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. For more information about reserved names, see File Names, Paths, and Namespaces.
Special characters for nodes	- Must not contain Unicode control characters. - Must not contain any one of the following characters: \ / : * ? " < > | # $ * +. - Must not contain characters prohibited by the local file system. For more information about Windows character restrictions, see Naming Files, Paths, and Namespaces.
Path length	Must not contain more than 4,000 Unicode characters.
Path hierarchy depth	Must be fewer than 14 levels deep.

Related articles

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

• Define area paths and assign to a team
• Define iteration (sprint) paths and configure team iterations
• Agile tools and sprint definitions
• Query by date or current iteration