Configure Azure Boards to support SAFe® programs and portfolios

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

This tutorial walks you through the steps to convert a new project with a single team to one that is configured to support Scaled Agile Framework (SAFe®) programs and portfolios. Specifically, you'll learn how to configure Azure Boards to support SAFe® programs and portfolios by completing the following tasks:

  • Define Agile, program, and portfolio teams
  • Configure a hierarchy of Area Paths to support your teams
  • Define Iteration Paths to support SAFe® release trains, PIs, sprints, and IPs
  • Configure each team to support SAFe®

You'll need to be a member of the Project Administrators group to make these configurations.

Once you've completed these core configurations, you can then consider customizing your project to support specific business needs. Customization options are addressed in Customize Azure Boards to support SAFe® .


If you plan to add custom work item types, portfolio backlogs, or workflows; you may want to make those customizations first and then define and configure your teams.

If you're new to Azure Boards, we recommend that you review About teams and Agile tools and About area and iteration (sprint) paths before adding and configuring your teams. Also, two excellent articles to review around team structure and Agile culture are Introduction to planning efficient workloads with DevOps and Building productive, customer focused teams.


This article is one of a set of Scaled Agile Framework® tutorials that applies to Azure Boards and Azure DevOps Services. Most of the guidance is valid for both the cloud and on-premises versions. However, some of the features and procedures are specific to the cloud or the latest version of Azure DevOps Server.

Understand team hierarchy

In this article, we'll go from having one project and one team, both named "Fabrikam", to the following set of nine teams.

Teams, list


Azure Boards doesn't support a hierarchy of teams. However, by configuring the Area Paths as indicated in this article, you effectively create a type of team hierarchy. The hierarchy is defined through the structure of Area Paths.

We'll then configure the area path to the following hierarchy and configuring each team's area path. This configuration supports each team's backlog view and rollup of views within the hierarchy.

Area path and team configuration


If you have a large number of teams, area paths, and iterations that you need to add, you may want to use command line or programmatic tools. See the Command line and programmatic tools provided later in this article.

All teams can manage their own workload and priorities while clearly understanding how their work supports those epics managed in the portfolio team's backlog. At the same time, the portfolio team can monitor progress of its backlog on their own board, prioritize the items on their backlog, and view progress across release trains.

While the above may sound complicated, it actually takes little configuration to set up the teams and get started. To go from one project with one default team, first define each team while automatically creating a default area path for that team. Then reconfigure the flat set of area paths to a hierarchical structure. Next, define the iteration paths to support the release structure you want and the program and Agile teams to use. Lastly, configure each team and populate the membership of teams.

Define your teams

To start, we'll add each team, creating a default area path for each. Later in this article, we'll configure those area paths into the necessary hierarchy. This structure maps the following SAFe® teams to Azure Boards teams:

  • Portfolio team -> default top-level team, the Fabrikam team (already defined)
  • Program teams -> secondary-level teams, Fiber Suite, and Service Suite
  • Agile teams -> tertiary-level teams defined under Fiber Suite and Service Suite.

You'll need to be a project administrator to complete these steps. If you need more-detailed guidance, see Portfolio management.

Add each team, one by one.


The following procedure uses the New Teams Page user interface that is in preview. To enable this feature, see Manage or enable features.

  1. From the web portal, choose Project settings and open Teams.

    Open Project settings, and then Teams

  2. Choose New team.

    Create a subteam with its own area path

  3. Give the team a name, and optionally a description.

    Here we add the App team. Choose the team administrator and ensure the Create an area path with the name of the team checkbox is checked. Optionally add team members.

    Add the App team.

    Assign the team's Scrum Master, Program Manager, or Portfolio Manager as the team administrator. As team administrators, they can configure their team's tools to support their Agile practices and business needs.

  4. Repeat steps 2 and 3 to define all teams.

  5. Optional. If you have two or more Portfolio teams, create a team for each of them.

Configure Area Paths

To support your team hierarchy, you'll now configure the area paths created in the first step of defining teams into a hierarchy.

  1. From the Project Settings page, choose Project configuration and then Areas. You should see a flat list of Area Paths.

    Flat list of area paths

  2. You'll want to choose each feature team's Area Path under the top Area Path and move it under the Area Path hierarchy to which it belongs.

    You can drag and drop each area path under the parent node where it belongs. For example, here we drag the Migrate node to the Fiber Suite node.

    Area Paths, drag-and-drop to parent node

    Instead, you can open the context menu for the Area Path, choose Edit, and select the node where you want to move it.

  3. Repeat step 2 and 3 for the remaining Agile team area paths.

    If you've defined two or more portfolio teams, you'll need to change the move each program team's area path under their corresponding portfolio team's area path.

  4. When finished, your area path structure should appear similar to the following image.


    This structure shows that area paths are owned by Agile teams, program teams, and the portfolio team. We'll correct this structure later in this article when we configure each team to be the sole owner of its area path.

    Hierarchical area path

Define Iteration Paths

To track progress towards Releases, create your iteration path structure. Unlike area paths, multiple teams can share the same iteration path structure. Sharing the iteration structure lets multiple teams work in the same sprint cadence towards the same release trains.


Deleting, renaming, or moving iteration paths causes a loss of associated historical data.

If you already have iterations for your default team, you can rename them. You'll want to create an iteration structure that supports your entire team structure, not just one team.

  1. From the Project Settings page, choose Project configuration and then Iterations.

  2. Under the default iteration, which shares the same name as the project, create a child iteration that represents your first program increment (PI). Optionally, add a start and end date for the PI, but keep in mind that the iteration gets broken down further into sprints.

    Create a child iteration.

  3. Next, create a child iteration for each Sprint within the PI. Set dates for these sprints to correspond your Agile teams' cadences.

    Iterations page, create IP Sprint iteration

  4. Continue to add as many iterations as needed to meet the time box cadence structure for all your teams.

    When finished, you should have a structure similar to the following image.

    Iterations page, list of iterations


    You can drag and drop Iteration Paths to structure your iterations, similar to as shown in Step 2 under Configure Area Paths. Azure Boards always lists the iteration paths in order of their dates under each parent node.

Configure your teams

Now that your teams, Area Paths, and Iteration Paths are defined, the next step is to configure each team. You'll want to configure the following settings for each team.

  • Active backlogs
  • Working with bugs
  • Set default Iteration Path
  • Select team Iteration Paths

The following table lists the recommended settings to make based on the team level.


Agile feature team

Program team

Portfolio team

Backlog navigation levels

Features, Stories

Features, Stories


Working with bugs

Bugs are managed with requirements

Bugs are not managed on backlogs and boards

Bugs are not managed on backlogs and boards

Default Iteration




Backlog Iteration




Selected iterations

Sprint 1 thru Sprint 4, IP Sprint

PI 1, PI 2, PI 3



Include sub areas

Exclude sub areas

Exclude sub areas


By setting the Default Iteration to @CurrentIteration, all work items created from the team's backlog or board are assigned to the current iteration based on the current date. By setting the Backlog Iteration to the root, Fabrikam, indicates that only the Area Path acts as a filter for work items to appear on the team backlogs and boards.

  1. From the Project Settings page, choose Team configuration.

    Choose the team you want to configure from the Team selector.

    Team profile, choose Iterations and areas link

  2. On the General page, uncheck backlogs you don't want to be active.

    For example, for the Portfolio team, only check the Epics checkbox.

    Team configuration, General, Backlog navigation levels, Epics only

    For program and Agile teams, uncheck the Epics checkbox.

    Team configuration, General, Backlog navigation levels, Features and Stories

  3. For program and portfolio teams, choose the Working with bugs radio button as shown.

    Team configuration, General, Working with bugs, don't track

    And, for Agile teams, choose the Working with bugs option to track bugs along with requirements.

    Agile Team configuration, General, Working with bugs, don't track

  4. Choose the Iterations tab to configure the team's iterations.

    For Agile teams, configure the settings as shown.

    Team configuration, Iterations, select sprints

    For program teams, choose only the PI iterations.

    Team configuration, Iterations, select PIs

  5. For program and portfolio teams, choose the Areas tab to change the default setting from Include sub areas to Exclude sub areas.

    Open the context menu, and choose Exclude sub areas.

    Team configuration, Areas, Exclude sub areas


    Because we created each team with the Create an area path with the name of the team checked, each team is already preconfigured with their default area path. This Area Path acts as the main filter for work items that appear on each team's backlogs and boards.

  6. Repeat steps 2 through 5 as needed for each team you need to configure.

  7. After you've completed step 5 for all teams, verify the Area Path-Team structure. Choose Project configuration and Areas. The Area Path and team structure should now appear as shown, where each team owns their Area Path and doesn't share it with any other team.

    Project configuration, Areas

Configure teams to support Shared Services

For teams that support several other teams, such as a UX Design team, configure your teams as described in the following steps.

  1. Add a team for each Shared Services team. Refer to Define your teams for details.

  2. Return to the Project configuration>Area Paths page and under each shared services area path, add sub area paths for each Agile team supported by the shared services. For more information, see Configure Area Paths provided earlier in this article.

    For example, here we add four sub area paths under the UX Design area path, one for each Agile team supported by the UX Design team.

    Shared services sub area paths

  3. Configure each Shared Services team as an Agile feature team as described in Configure your teams.

  4. For each Agile team, open the Team configuration>Areas page as shown in Step 5 of Configure your teams. Choose Select areas and add the sub area path for that team.

    Here we add the UX Design\App sub area path to the App feature team.

    Budget estimate rollup

  5. Return to the Project configuration>Area Paths page and verify that the Area Path structure appears as expected for each Shared Services area path.

    For the UX Design team, the structure should appear as shown.

    Shared services area path and team structure

    Work items that appear on shared area paths appear on the backlogs and boards of the associated teams.

Command-line and programmatic tools

You can use Azure DevOps command-line tools to add or update the following artifacts:

Use programmatic tools

You can use Azure DevOps REST APIs to add or update the following artifacts:

Next steps