| title | Define area paths and assign to a team |
|---|---|
| titleSuffix | Azure Boards |
| description | Group work items based on team, product, or feature area by defining area paths for Azure Boards and Azure DevOps. |
| ms.subservice | azure-devops-settings |
| ms.assetid | 97358022-AE19-4775-AE25-47BA24FF3C74 |
| ms.author | chcomley |
| author | chcomley |
| ms.topic | how-to |
| monikerRange | <= azure-devops |
| ms.date | 12/22/2025 |
| ms.custom | teams, engagement-fy23, devx-track-azurecli, sfi-image-nochange |
[!INCLUDE version-lt-eq-azure-devops]
Add area paths to organize teams and group work items by product, feature, or business areas. Assigning area paths to teams ensures that work items under those paths appear on the respective team's backlogs and boards. By default, all work items are assigned to the root area path and appear in the project's default team.
After you define area paths at the project level, assign them to teams within the team configuration. You can also create a hierarchical structure of area paths to support subareas, with up to 14 levels deep.
[!INCLUDE temp]
To understand how the system uses area paths, see About area and iteration paths.
| Category | Requirements |
|---|---|
| Permissions | - To set team area or iteration paths: Team administrator or a member of the Project Administrators group. By default, the user who created the project has these permissions. - To add an area path under the root node or edit or delete any child node: Member of the Project Administrators group. - To add, edit, and manage area paths under a node: One or more of the following permissions set to Allow: - Create child nodes - Delete this node - Edit this node - View permissions in this node |
For more information, see Set permissions and access for work tracking.
For naming restrictions on area paths, see About areas and iterations, Naming restrictions.
Each team has access to various Agile tools, as described in About teams and Agile tools. These tools reference the team's default area paths. Most teams use one area path and several iteration paths for work tracking, but teams can also use multiple area paths on their backlogs and boards to support different scenarios.
New projects include a single root area corresponding to the project name and a default team with the same name assigned to this root area path.
If you're new to managing projects and teams, follow these steps to configure your project and teams:
- Define area paths: Determine the number and names of area paths needed to categorize your work. Add at least one area path per team. For more information, see About areas and iterations.
- Define teams: Decide the number and names of teams required. For more information, see About teams and Agile tools.
- Configure area paths: Go to Project settings > Project configuration > Areas and define the area paths for your project. Follow the steps in Add area paths.
- Create teams: Create the necessary teams based on step 2. For more information, see Add a team, move from one default team to several teams.
- Assign area paths to teams: In the team configuration, assign the default and other area paths to each team. Do the steps in Set team default area paths.
- Assign area paths to work items: Assign work items to the defined area paths using bulk modify to update multiple items at once.
Note
Assigning the same area path to multiple teams may cause conflicts over work item ownership and can lead to unexpected behavior on team boards. For more information, see Limitations of multi-team board views.
As needed, you can do the following actions at any time:
- Add other 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
To list project areas, do the following steps:
From your web portal, select (1) Project settings > (2) Project configuration > (3) Areas.
[!div class="mx-imgBorder"]
::: moniker range="azure-devops"
List project area paths | Add a project area path | List team areas paths | Set team area paths | Rename or move a project area path | Remove area path from a team
You can list area paths defined for a project using the az boards area project list command. To get started with the CLI, see Get started with Azure DevOps CLI.
[!div class="tabbedCodeSnippets"]
az boards area project list [--depth]
[--path]
[--project]
- depth: Optional. Depth of child nodes to be listed. Example:
--depth 3. When not specified, only the top-level area paths are returned. - path: Optional. Absolute path of an area.
\Area\must follow after the\ProjectName, which distinguishes this path from an iteration path. For example,--path \ProjectName\Area\AreaName. If spaces are used within a node, then enclose in double-quotes, for example,--path "\Fabrikam Fiber\Area\Service Delivery\Performance". When not specified, lists area paths from the root level. - project: Optional. Name or ID of the project. Example:
--project "Fabrikam Fiber".
For example, the following command lists the area paths to a depth of 3 for the Fabrikam Fiber project. For other output format options, see Output formats for Azure CLI commands.
[!div class="tabbedCodeSnippets"]
az boards area project list --depth 3 --project 'Fabrikam Fiber' --output table
ID Identifier Name Path Has Children
----- ------------------------------------ ------------------ -------------------------------------------------- --------------
55302 91d8644a-e430-4fd0-aa95-742ea98770a3 Fabrikam Fiber \Fabrikam Fiber\Area True
55373 26be05fd-e68a-4fcb-833f-497f6bee45f2 Service Delivery \Fabrikam Fiber\Area\Service Delivery True
55303 637dc203-0549-4415-9663-b6358ac27d21 Internet \Fabrikam Fiber\Area\Service Delivery\Internet False
55306 3f2067f9-684f-4121-8004-4a4745198b39 Voice \Fabrikam Fiber\Area\Service Delivery\Voice False
55372 4afc9ede-db1d-4703-8be6-95899b99be44 Email \Fabrikam Fiber\Area\Service Delivery\Email False
55381 f96d4738-c67e-42d0-bd4e-99f6b3fdeb22 Service Status \Fabrikam Fiber\Area\Service Delivery\Service S... False
55384 3a0c1189-6454-4ccd-9354-d72b653b7f74 TV \Fabrikam Fiber\Area\Service Delivery\TV False
55380 4ea27e90-248c-41a0-8d11-eace6c9fd90e Account Management \Fabrikam Fiber\Area\Account Management True
55382 4235f40d-753b-49dd-868f-82372065ec83 Shopping Cart \Fabrikam Fiber\Area\Account Management\Shoppin... False
55383 49d34650-6c65-446c-aff6-79edd3a21a75 Customer Profile \Fabrikam Fiber\Area\Account Management\Custome... False
::: moniker-end
[!INCLUDE temp]
Only one root area is defined by default. Add new and child area paths under the root area path for the project, or as a child to another area path or team. New area paths are added to the root node by default.
[!div class="mx-imgBorder"]
You can also add new and child area paths to a team. For more information, see Set team area paths.
To add a new area path, do the following steps:
-
Highlight the area path and then choose New child. Alternatively, you can select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for an area path and choose New, or select the New menu item at the top of the area list.
-
Enter a name (255 characters or less) for the node. For more name restrictions, see About areas and iterations, Naming restrictions.
[!div class="mx-imgBorder"]
-
Select Save and close
All new areas are added as a child node to the root area path.
To add a child area path, do the following steps:
-
Highlight the area path and then choose New child. Alternatively, you can select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for the area path and choose New child or select New child from the menu at the top of the area list.
-
Enter a name (255 characters or less) for the node. For more name restrictions, see About areas and iterations, Naming restrictions.
[!div class="mx-imgBorder"]
-
Select Save and close
You can also add area paths to a team on the Team configuration > Areas page.
::: moniker range="azure-devops"
You can add area paths to a project using az boards area project create. To get started, see Get started with Azure DevOps CLI.
If you specify the --path parameter, the new area path is added as a child node to the specified path. If you don't specify the --path parameter, the new area path is added as a child node to the root node.
[!div class="tabbedCodeSnippets"]
az boards area project create --name
[--path]
[--project]
- name: Required. Area path name.
- path: Optional. Absolute path of an area. Example: --path \ProjectName\Area\AreaName. When not specified, adds an area at the root level.
- project: Optional. Name or ID of the project. Example:
--project "Fabrikam Fiber".
For example, the following command adds the Voice area path to the Fabrikam Fiber project at the root node.
[!div class="tabbedCodeSnippets"]
az boards area project create --name Voice --project "Fabrikam Fiber"
{
"attributes": null,
"children": null,
"hasChildren": false,
"id": 55412,
"identifier": "b00f86a2-3d49-4ad2-af01-da2537947baa",
"name": "Voice",
"path": "\\Fabrikam Fiber\\Area\\Voice",
"structureType": "area",
"url": "https://dev.azure.com/fabrikam/56af920d-393b-4236-9a07-24439ccaa85c/_apis/wit/classificationNodes/Areas/Voice"
}
And, here's the same command with the table output format.
[!div class="tabbedCodeSnippets"]
az boards area project create --name Voice --project "Fabrikam Fiber" --output table
ID Identifier Name Path Has Children
----- ------------------------------------ ------ --------------------------- --------------
55413 3c16691b-160c-4498-ab42-aa77b7f354fc Voice \Fabrikam Fiber\Area\Voice False
::: moniker-end
[!INCLUDE temp]
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.
[!div class="mx-imgBorder"]
::: moniker range="azure-devops"
You can list the area paths defined for a team using az boards area team list. To get started, see Get started with Azure DevOps CLI.
[!div class="tabbedCodeSnippets"]
az boards area team list --team
[--project]
- team: Required. Name or ID of the team.
- project: Optional. Name or ID of the project. Example:
--project "Fabrikam Fiber".
For example, the following command lists the area paths for the Service Delivery team. For other output format options, see Output formats for Azure CLI commands
[!div class="tabbedCodeSnippets"]
az boards area team list --team "Service Delivery" --project "Fabrikam Fiber" --output table
Area Include sub areas Is Default
------------------------------- ------------------- ------------
Fabrikam Fiber\Service Delivery True True
::: moniker-end
[!INCLUDE temp]
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 :::image type="icon" source="../../media/icons/team.png" border="false"::: > Team Settings.
Here we open the Board for the Fabrikam Fiber team and from there the team profile.
[!div class="mx-imgBorder"]
-
Choose Iterations and areas.
[!div class="mx-imgBorder"]
-
If you need to switch the team context, use the team selector within the breadcrumbs.
[!div class="mx-imgBorder"]
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 efficient work organization and performance. For more information about limits, 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 produce unexpected query results. Since each team can customize their board columns and swimlanes, work item values may vary across different team boards. To avoid this issue, maintain single ownership of work items by assigning them to specific team area paths.
::: moniker range="<=azure-devops"
You can select existing area paths or create new or child area paths from the team settings.
-
Select Project settings > Team configuration > Areas.
-
Select the team you want to configure from the drop-down list at the top of the page.
Here, we show the Areas for the Fabrikam Fiber team.
[!div class="mx-imgBorder"]
-
Choose one or more area paths to be active for the team.
[!div class="mx-imgBorder"]
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 finish, refresh the product backlog page for the team, and you see those work items assigned to the team. Add area path to the columns shown to see the assignments made to work items.
::: moniker-end
::: moniker range="azure-devops"
You can set the default area path for a team or add an area path, using az boards area team add. To get started, see Get started with Azure DevOps CLI.
[!div class="tabbedCodeSnippets"]
az boards area team add --path --team
[--include-sub-areas {false, true}]
[--project]
[--set-as-default]
- path: Required. Absolute path of an area. Example:
--path \ProjectName\AreaName. - team: Required. Name or ID of the team.
- include-sub-areas: Optional. Include child nodes of the area path. Accepted values: false, true.
- project: Optional. Name or ID of the project. Example:
--project "Fabrikam Fiber". - set-as-default: Optional. Specify as the default area path for the team. Default: False.
For example, the following command adds the Voice area path to the Voice team for the Fabrikam Fiber project, sets it as the default and to include subareas.
[!div class="tabbedCodeSnippets"]
az boards area team add --path "\Fabrikam Fiber\Voice" --team Voice --project "Fabrikam Fiber" --include-sub-areas --set-as-default --include-sub-areas true --output table
Area Include sub areas Is Default
------------------------------------- ------------------- ------------
Fabrikam Fiber\Service Delivery\Voice False False
Fabrikam Fiber\Voice True True
::: moniker-end
[!INCLUDE temp]
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 :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: context menu for the node, and select Edit.
:::image type="content" source="media/areas/edit-area-rename-project-configuration.png" alt-text="Screenshot of open context menu for an Area Path node, choose Edit option.":::
-
In the dialog that opens, enter the new name.
:::image type="content" source="media/areas/edit-area-rename-dialog.png" alt-text="Screenshot of Edit area dialog.":::
-
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.
::: moniker range="azure-devops"
You can rename or move an area path for a project, using az boards area project update command. To get started, see Get started with Azure DevOps CLI.
[!div class="tabbedCodeSnippets"]
az boards area project update --path
[--child-id]
[--name]
[--project]
- path: Required. Absolute path of an area. Example:
--path \ProjectName\AreaName. - child-id: Optional. Moves an existing area path and adds it as a child node for the specified path name or ID.
- name: Optional. Specifies the new name of the area path.
- project: Optional. Name or ID of the project. Example:
--project "Fabrikam Fiber".
For example, the following command renames the Voice area path to Voice and Web for the Fabrikam Fiber project.
[!div class="tabbedCodeSnippets"]
az boards area project update --path "\Fabrikam Fiber\Area\Voice" --name "Voice and Web" --project "Fabrikam Fiber" --output table
ID Identifier Name Path Has Children
----- ------------------------------------ ------------- ---------------------------------- --------------
55412 b00f86a2-3d49-4ad2-af01-da2537947baa Voice and Web \Fabrikam Fiber\Area\Voice and Web False
To remove an area path from a team, use az boards area team remove.
[!div class="tabbedCodeSnippets"]
az boards area team remove --path
--team
[--project]
- path: Required. Absolute path of an area. Example:
--path \ProjectName\AreaName. - team: Required. Name or ID of the team.
- project: Optional. Name or ID of the project. Example:
--project "Fabrikam Fiber".
For example, the following command removes the \Service Delivery\Voice area path from the Voice team of the Fabrikam Fiber project.
[!div class="tabbedCodeSnippets"]
az boards area team remove --path "\Fabrikam Fiber\Service Delivery\Voice" --team Voice --project "Fabrikam Fiber" --output table
::: moniker-end
[!INCLUDE temp]
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.
[!INCLUDE note-delete-area-paths]
-
To delete an Area Path, open the web portal Project settings>Project configuration>Areas page.
-
Choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: 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.
:::image type="content" source="media/areas/delete-area-path-dialog.png" alt-text="Screenshot of Delete area dialog.":::
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.
[!div class="nextstepaction"] Set iteration paths or sprints
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:
- Learn about areas and iterations
- Add another team
- Configure team settings and add team administrators
- Use Agile tools that rely on areas or iterations
- Query by area or iteration path
- Set permissions and access for work tracking
Area paths and iteration paths are also referred to as Classification Nodes.
::: moniker range="azure-devops"
- Use the az boards area (Azure DevOps CLI).
- Use the Teams (REST API) to manage team configurations.
- Utilize the Classification Nodes (REST API) to organize work item classifications.
::: moniker-end
::: moniker range="< azure-devops"
- Use the Teams (REST API) to manage team configurations.
- Utilize the Classification Nodes (REST API) to organize work item classifications.
- Configure the process by defining the classification plug-in (Process Template).
::: moniker-end