Define area paths and assign to a team
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Add area paths to support teams and group work items based on product, feature, or business areas. Once you define area paths at the project level, you assign them to a team under the team configuration. You can also create a hierarchy of area paths to support sub-areas, up to 14 levels deep.
To perform the following tasks, you must define area paths:
- Query and chart work items based on Area Path
- Assign work to more than one team
- Work with management and feature teams
- Filter a backlog, query, board, or plan using Area Paths
Tip
You can define your area path structure and assign area paths to teams. Or, you can add a team and create the area path with the team name at that time. If teams are fully independent, create a flat set of area paths. However, if you want to create a hierarchy of teams, then you'll want to create a tree-hierarchy of area paths. For more information, see Configure a hierarchy of teams.
To use the following tools, teams must subscribe to area paths:
To understand how the system uses area paths, see About area and iteration paths.
Prerequisites
If you don't have a project yet, create one now.
Ensure you're a member of the Project Administrators group to add an area path under the root node or edit or delete any child node. To acquire these permissions, see Change project-level permissions.
Have one or more of the following permissions set to Allow, to add, edit, and manage area paths under a node:
- Create child nodes
- Delete this node
- Edit this node
- View permissions in this node
By default, the user who created the project has these permissions already set. For more information, see Set permissions and access for work tracking.
Ensure you're added as a team administrator or are a member of the Project Administrators group to set team area paths.
For naming restrictions on area paths, see About areas and iterations, Naming restrictions.
Get started
Each team has access to a number of Agile tools as described in About teams and Agile tools. Each tool references the team's default area path(s). Most teams choose one area path and several iteration paths to support their work tracking activities. However, to support other scenarios, it's possible for teams to choose several area paths to appear on their backlogs and boards.
New projects contain a single, root area that corresponds to the project name. A team is created with the same project name and the root area path is assigned to that team.
If you're new to managing projects and teams, the most straight forward sequence for configuring your project and teams is as follows:
- 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 you define. For more information, review About areas and iterations.
- Determine the number and names of teams you want to support. For more information, review About teams and Agile tools.
- 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.
- Define the teams you need to support step 2. For more information, see Add a team, move from one default team to several teams.
- 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).
- Assign the area path of work items to an area path you defined. Use bulk modify to modify several work items at once.
Note
While you can assign the same area path to more than one team, doing so can cause problems if two teams claim ownership over the same set of work items. For more information, see About boards and Kanban, Limitations of multi-team 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
Important
Select the version of this article that corresponds to your platform and version. The version selector is above the table of contents. Look up your Azure DevOps platform and version.
Open Project Settings, list project areas
Define both areas and iterations for a project from the Project Settings > Boards > Project configuration.
From your web portal, choose (1) Project settings, choose (2) Project configuration and then (3) Areas.
Add an area path
Only one area is defined, by default. Add area paths under the root area path for the project, or as a child to another area path.
To add a child node, highlight the area path and then choose New child. Optionally, you can select
for the area path and choose New child.Enter a name (255 characters or less) for the node. For additional name restrictions, see About areas and iterations, Naming restrictions.
Open team settings, list team area paths
You set team defaults from team settings. If you're not a team administrator, get added as one. Only team or project administrators can change team settings.
Open your project, and then select Project settings > Team configuration > Areas.
If you need to switch the team context, use the team selector within the breadcrumbs.
Open team settings from the team profile
You define both areas and iterations from Project Settings > Team configuration. You can quickly navigate to it from a team work tracking backlog, board, or dashboard.
Open a backlog or board for a team and choose Team profile
> Team Settings.Here we open the Board for the Fabrikam Fiber team and from there the team profile.
Choose Iterations and areas.
If you need to switch the team context, use the team selector within the breadcrumbs.
Set team area path(s)
All work items that are assigned to a team area path appear on the backlogs and boards for that team. You can select one or more area paths and optionally include their subarea paths. Choose to include subarea paths when you want to support rollup views of work done across several teams or areas.
Note
Teams can be assigned a maximum of 300 Area Paths. For more information, see Work tracking, process, and project limits.
The default area path determines the default area path assigned to work items that are created from the team context.
Important
Work items that appear on more than one team's board can yield query results that don't meet your expectations. Because each team can customize the board columns and swimlanes, the values assigned to work items which appear on different boards may not be the same. The primary work around for this issue is to maintain single ownership of work items by team area path.
Open Areas for the team context.
Here, we show the Areas for the Fabrikam Fiber team.
Choose the area path(s) to be active for each team.
In this instance, we choose to activate the subarea paths for the project. The management team can now track progress across all teams.
When you've finished, refresh the product backlog page for the team, and you'll see those work items assigned to the team. Add area path to the columns shown to see the assignments made to work items.
Open Areas for the team context.
Here, we show the Areas for the Fabrikam Fiber team.
Choose the area path(s) to be active for each team.
In this instance, we choose to activate all three subarea paths for the project. The management team can now track progress across all three teams.
When you've finished, refresh the product backlog page for the team, and you'll see those work items assigned to the team. Add area path to the columns shown to see the assignments made to work items.
Rename or move an Area Path
The system automatically updates work items and queries that reference your updated area path. Each Area Path is associated with a unique GUID.
To rename an Area Path, open the web portal Project settings>Project configuration>Areas page.
Choose the
context menu for the node, and select Edit.
In the dialog that opens, enter the new name.
To move the node within the hierarchy, change the Location field.
Note
When you rename or change the Location field for a node, the system automatically updates the existing work items that reference the Area Path.
Delete an Area Path
When you delete an Area Path, you must provide an Area Path to use to update the work items assigned to the Area Path you want to delete.
Important
- Deleting Area Paths or reconfiguring Iteration Paths causes irreversible data loss. For example, burndown and burnup widget charts, sprint burndown, and velocity charts for teams with changed Area Paths won't display accurate data. Historical trend charts reference the Area Path and Iteration Path as they were defined at the time for each work item. Once deleted, you can't retrieve historical data for these paths.
- You can only delete area and iteration paths that are no longer used by any work items.
To delete an Area Path, open the web portal Project settings>Project configuration>Areas page.
Choose the
context menu for the node, and select Delete or Remove.In the dialog that opens, select the Area Path to reassign work items to, and then choose Delete path.
Chart progress by area
You can quickly generate queries to view the progress based on an area path. For example, visualize progress of work items that are assigned to each team's area path, as shown in the following stacked bar chart. Choose Node Name to get the leaf node of the area path.
Q & A
Q: Do I have to assign an area path to a team?
A: No. You assign area paths to teams so that the work items assigned to that area path appear on the team's backlogs and boards. By default, all work items get assigned to the root area path. These work items appear in the default team that's defined for the project.
Next steps
Related articles
As you can see, area paths play a major role in supporting Agile tools, teams, and managing work items. Learn more about working with these fields from the following articles:
- About areas and iterations
- Add another team
- Configure team settings and add team administrators
- Agile tools that rely on areas or iterations
- Query by area or iteration path
- Set permissions and access for work tracking
Programmatic resources
Area paths and iteration paths are also referred to as Classification Nodes.