Define area paths and assign to a team

Azure Boards | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

You can add area paths to support teams and to group work items based on product, feature, or business areas. Then, define area paths at the project level and assign them to a team under the team configuration. You can also create a hierarchy of area paths to support subcategories within categories.

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 commands and az boards area (Azure DevOps CLI).

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.

To understand how the system uses area paths, see About area and iteration paths.

Important

To view the content available for your platform, make sure that you select the correct version of this article from the version selector which is located above the table of contents. Feature support differs depending on whether you are working from Azure DevOps Services or an on-premises version of Azure DevOps Server, renamed from Team Foundation Server (TFS).

To learn which on-premises version you are using, see What platform/version am I using?.

Prerequisites

  • Add Area Paths to a project. 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 Set permissions at the project- or collection-level.

  • 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 set. To learn more, 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 sequence

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, you'll want to add one Area Path for each team that you'll define. For guidance, review About areas and iterations.
  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

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


Open Project Settings, list project areas

Note

To enable the new user interface for the Project Permissions Settings Page, see Enable preview features.

  1. Sign in to your organization (https://dev.azure.com/{yourorganization}) and go to your project.

  2. Choose (1) Project settings, choose (2) Project configuration and then (3) Areas.

    Project Settings>Project Configuration

Azure DevOps CLI commands aren't supported for Azure DevOps on-premises deployments at this time.


You define both areas and iterations for a project from the Project Settings > Work > Project configuration.

  1. From the web portal, open Project settings.

  2. Choose (1) Project settings, choose (2) Project configuration and then (3) Areas.

    Project Settings>Project Configuration

You define both areas and iterations from the Work pages of the project admin context. From the user context, you open the admin context by choosing the  gear icon.

  1. From the web portal for the project, choose the  gear icon.

    Open Admin context, project level

    If you're currently working from a team context, then hover over the gear icon and choose Project settings.

    Open Project Settings, horz nav

  2. Choose Work.

  1. From the web portal, choose the  gear icon to open project administration pages. Then choose Areas.

    Open the project administration page


Add an area path

Note

To enable the new user interface for the Project Permissions Settings Page, see Enable preview features.

If you haven't added any areas or teams, you'll see that only one area is defined. You add area paths under the root area path for the project, or as a child to another area path.

Areas, defaults defined for project

  • To add a child node, highlight the area path and then choose New child. Optionally, you can open the  context menu 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.

    Add a new area path

Azure DevOps CLI commands aren't supported for Azure DevOps on-premises deployments at this time.


Areas, defaults defined for project

  • To add a child node, highlight the area path and then choose New child. Optionally, you can open the  context menu 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.

    Add a new area path

Areas, defaults defined for project

  • To add a child node, highlight the area path and then choose New child. Optionally, you can open the  context menu 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.

    Add a new area path

  1. Open Areas.

    Open the areas page defined for 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've selected.

    Create a new area node

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.

Note

To enable the new user interface for the Project Permissions Settings Page, see Enable preview features.

  1. Open your project, and then select Project settings > Team configuration > Areas.

    Project settings, Team configuration page

  2. If you need to switch the team context, use the team selector within the breadcrumbs.

    Team Configuration, Team breadcrumb

Azure DevOps CLI commands aren't supported for Azure DevOps on-premises deployments at this time.


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.

  1. Open a backlog or board for a team and choose the  team profile icon. Then choose Team Settings.

    Here we open the Board for the Fabrikam Fiber team and from there the team profile.

    Work Backlog or Board, choose team profile icon

  2. Choose Iterations and areas.

    Team Profile, choose Iterations and area

  3. If you need to switch the team context, use the team selector within the breadcrumbs.

    Team Configuration, Team breadcrumb

You open team settings from the top navigation bar. Select the team you want and then choose the  gear icon. To learn more about switching your team focus, see Switch project, repository, team

Open team settings

Set team area path(s)

All work items assigned to the area paths selected for a team appear on the backlogs and boards for that team. You can select one or more area paths and optionally include their sub-area paths. Choose to include sub-area paths when you want to support rollup views of work performed across several teams or areas.

All work items assigned to the area paths selected for a team appear on the backlogs and boards for that team. You can select a single area path, and optionally include their sub-area paths. Choose to include sub-area paths when you want to support rollup views of work performed across several teams or areas.

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 then one team's Kanban board can yield query results that don't meet your expectations. Because each team can customize the Kanban 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.

Note

To enable the new user interface for the Project Permissions Settings Page, see Enable preview features.

  1. Open Areas for the team context.

    Here, we show the Areas for the Fabrikam Fiber team.

    Area page for team

  2. Choose the area path(s) to be active for each team.

    Work, Iterations page for team

    In this instance, we choose to activate the sub-area paths for the project. The management team can now track progress across all teams.

    Multiple area paths assigned to team

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

    Backlog view of default team

    Add Area Path column to backlog

Azure DevOps CLI commands aren't supported for Azure DevOps on-premises deployments at this time.


  1. Open Areas for the team context.

    Here, we show the Areas for the Fabrikam Fiber team.

    Area page for team

  2. Choose the area path(s) to be active for each team.

    Work, Iterations page for team

    In this instance, we choose to activate all three sub-area paths for the project. The management team can now track progress across all three teams.

    Multiple area paths assigned to team

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

    ![Backlog view of default team](_img/add-team/product-backlog-default-team-horz.png

  1. Open the Areas admin page for the team context.

    Here, we navigate to the Fabrikam Fiber team. The checked box indicates the area paths selected for the team. To exclude sub-areas, select the option from the area path context menu.

    Work, Area page for Fabrikam Fiber team

  2. Refresh the product backlog page for the team, and you'll see only those work items assigned to the Fabrikam Fiber area path.

    Product backlog for Fabrikam Fiber team

Rename, move, or delete an area path

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

Note

To enable the new user interface for the Project Permissions Settings Page, see Enable preview features.

  1. To rename an area or iteration path, choose the  actions icon for the node, and then select Edit.

    Open Work>Project Configuration

  2. In the dialog that opens, enter the new name.

    Open Work>Project Configuration

  3. To move the node within the hierarchy, change the Location field.

  4. To delete a node, choose the Delete option from the actions menu.

Azure DevOps CLI commands aren't supported for Azure DevOps on-premises deployments at this time.


  1. To rename an area or iteration path, choose the  actions icon for the node, and then select Edit.

    Open Work>Project Configuration

  2. In the dialog that opens, enter the new name.

    Open Work>Project Configuration

  3. To move the node within the hierarchy, change the Location field.

  4. To delete a node, choose the Delete option from the actions menu.

Note

When you delete an area node or change the Location field for a node, the system automatically updates the existing work items with the node that you enter at the deletion prompt.

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.

Stacked bar chart by area and state

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 are assigned to the root area path and show up in the default team that's defined for the project.

Next steps

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:

Programmatic resources