Define iteration paths (sprints) and configure team iterations

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

Iteration Paths, also referred to as sprints, support assignment of work items to time-box intervals. You define iteration paths at the project level, and then each team selects the paths that they want to use. Iteration paths are a shared resource used by all teams that select them. You can create a flat set of iteration paths or a hierarchy of paths to support releases, sub-releases, and sprints.

Define iteration paths and assign them to teams when you want to use the following tools:

Tip

If a team hasn't subscribed or selected an iteration path, that iteration path won't appear in a team view or tool.

For information about naming restrictions and limits placed on addition of Iteration Paths, see About areas and iterations, Naming restrictions.

Tip

If all you need to do is change the iteration dates, you can do that quickly as shown in Change sprint dates. However, if you need to define the iteration paths and tree structure, then follow the guidance provided in this article.

Prerequisites

  • To add an iteration path to a project, you must be a member of the Project Administrators group. If you don't have a project yet, create one now. By default, the user who created the project has these permissions set.
  • To add, edit, and manage iteration paths under a node, you must have one or more of the following permissions set to Allow for the node that you want to manage: Create child nodes, Delete this node, Edit this node, and View permissions for this node.
  • To set team iteration paths, you must be added as the team administrator or be a member of the Project Administrators group.

For more information about acquiring permissions, see Change project-level permissions or Set permissions and access for work tracking.

Get started

Newly created projects contain a single, root area path that corresponds to the project name. You add area paths under this root. Also, each project typically specifies a predefined set of iteration paths to help you get started tracking your work. You only need to specify the dates.

If you're new to managing projects and teams, complete the following steps.

  1. Review Configure and customize Azure Boards.
  2. Define the area paths and teams following the guidance provided in Define area paths and assign to a team.
  3. Determine the length of the iteration you want to support. Recommended practice is to have all teams use the same sprint cadence. For guidance, review About areas and iterations.
  4. Determine if you want a flat structure or hierarchy of sprints and releases.
  5. 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.
  6. 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 iteration path(s).
  7. Each team should assign the default iteration path they selected to their work items. Do so for those work items to 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.

As needed, you can do the following tasks 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

Team backlog iteration versus default iteration

Each team has access to many Agile tools, as described in About teams and Agile tools. Each tool references the team's default area path(s). Several tools reference the team's default and selected iteration paths or sprints. 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.

Teams can set a default iteration different from the backlog iteration. The backlog iteration determines which items appear on the team's backlogs and boards. And, the default iteration determines what value is assigned to work items created from the team context.

All work items that you create from your team context are automatically assigned both the team's default area path and default iteration path.

Important

Select a version from Azure DevOps Content Version selector.

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 iterations

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

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

From the web portal, open Project Settings.

Define both areas and iterations for a project from the Project settings > Boards > Project configuration.

  1. Choose (1) Project Settings, expand Boards if needed, and then choose (2) Project configuration and (3) Iterations.

    Screenshot of Project Settings, Project Configuration.

From the web portal, open Project Settings.

Define both areas and iterations for a project from the Project configuration > Iterations.

  1. From the web portal, choose Project settings(1), select Project configuration(2), and then Iterations(3).

    Screenshot of Project Settings, Project Configuration for Azure DevOps Server 2019.

From the web portal, choose Project settings to open project administration pages. Then, choose Iterations.

Screenshot of Open the project administration page for TFS 2018.

Add iterations and set iteration dates

You can add iterations in the same way that you add areas. For more information about working within a sprint cadence, see Scrum and sprint planning tools.

  1. Add and modify area paths from Project settings > Project configuration > Iterations.

    For Scrum-based projects, you see the following set of sprints.

    Screenshot of Project Settings context, project configuration, Iterations page.

  2. To schedule the start and end dates for each sprint that your teams use, highlight the sprint and choose Set dates. Or, you can select Actions for the iteration path and choose Edit.

    Screenshot of dialog to Set dates.

  3. Choose the calendar icon to select new dates.

    Screenshot of Iterations page, and calendar icon for selecting new dates.

  4. When you're finished, you have a set of sprints scheduled - similar to the following image:

    Screenshot of Iterations page, scheduled set of sprints.

    Your next step is to choose the sprints each team uses.

From Iterations, you can add iterations that teams can then select for their use.

  1. Add and modify area paths from the Work > Iterations page from the project admin or settings context.

    For Scrum-based projects, you see the following set of sprints.

    Screenshot of Project Settings Context, Work, Iterations page.

  2. To schedule the start and end dates for each sprint your teams use, Highlight the sprint and choose Set dates. Or, you can select Actions context menu for the iteration path and choose Edit.

    Choose the calendar icon to choose new dates.

    Screenshot of Work, Iterations page, and calendar icon to choose for new dates for Azure DevOps Server 2019.

  3. When you're finished, you have a set of sprints scheduled - like this:

    Screenshot of Work, Iterations page, scheduled set of sprints for Azure DevOps Server 2019.

    Your next step is to choose the sprints each team uses.

Add and modify area paths from the Work > Iterations page from the project admin or settings context.

For Scrum-based projects, you see the following set of sprints.

Screenshot of Project Settings, Work, Iterations page for TFS 2018.

  1. To schedule the start and end dates for each sprint your teams use, Highlight the sprint and choose Set dates. Or, you can select Actions for the iteration path and choose Edit.

    Choose the calendar icon to choose new dates.

    Screenshot of Work, Iterations page, and calendar icon for setting new dates in TFS 2018.

  2. When you're finished, you have a set of sprints scheduled - like this:

    Screenshot of Work, Iterations page, scheduled set of sprints for TFS 2018.

    Your next step is to choose the sprints each team uses.

Open team settings, list team iterations

You can 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

Teams can be assigned a maximum of 300 Iteration Paths. To learn more, see Work tracking, process, and project limits.

You define both areas and iterations from Project settings > Boards > 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 Team profile and then Team Settings.

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

    Screenshot of Work Backlog or Board, choose team profile icon.

  2. Choose Iterations and areas.

    Screenshot of Team Profile, choose Iterations and area.

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

    Screenshot of Team Configuration, Team breadcrumb.

You open team settings from the upper navigation bar. Select the team you want and then choose Team settings . For more information about switching your team focus, see Switch project, repository, team

Screenshot of Open team settings for TFS 2018.

Select team sprints and set the default iteration path

You define sprints for the project and then select them to be active for each team. You assign the default iteration to use when creating new work items.

  1. Open Project settings > Boards > Team Configuration > Iterations for a team.

    Here, we navigate to the Fabrikam Fiber Team.

    Screenshot of Project settings, Team Configuration, Iterations page.

  2. Backlog iteration. Only work items assigned to an iteration equal to or under this backlog iteration appear in the team's backlogs and boards.

    Screenshot of Iterations page for team, set team backlog iteration for backlogs and boards.

    Also, all work items added through a team's backlog or board are assigned the backlog iteration.

  3. Default iteration. The default iteration defines the iteration that's used when you create a work item from the team backlog or Kanban board. You can specify any iteration defined under the Backlog iteration path. To assign new work items to the current iteration, specify @CurrentIteration. The same macro used in queries to list work items assigned to the currently active iteration assigned to the team is used.

    For example, you might want all new work items added to a future iteration path, which you use to triage and assign to specific sprints at periodic intervals.

    Screenshot of Work, Iterations page for team, set team default for new work items.

    Note

    New work items added through the Work Items page or the New Work Items widget on a team dashboard don't reference the Default Iteration Path assigned to the team. Instead, new work items are assigned the last Iteration Path selected by the user. New work items added through a team's Sprints backlog or taskboard are always assigned the Iteration Path associated with the selected sprint.

  4. Active sprints. Add an iteration for each sprint backlog you want active for the team. Add each sprint, one by one, by selecting it from the menu.

    Screenshot of Work, Iterations page for team, select sprints.

    When you're done, you should see a list of sprints, similar to the following.

    Screenshot of Work, Iterations page for team, activates sprint list.

    If you don't see the sprints or dates that you need, you can add or edit iterations for the project, provided you have the required permissions. For more information, see Define iteration (sprint) paths.

  5. To see the newly activated sprint backlogs, refresh your team's product backlog page.

  1. Open Work > Iterations for a team.

    Here, we navigate to the Fabrikam Fiber Team.

    Screenshot of Work, Iterations page for a team.

  2. Backlog iteration. Only work items assigned to an iteration equal to or under this backlog iteration appear in the team's backlogs and boards.

    Screenshot of Work, Iterations page for a team, set team backlog iteration for backlogs and boards.

    Also, all work items added through a team's backlog or board are assigned the backlog iteration.

  3. Default iteration. The default iteration defines the iteration that's used when you create a work item from the team dashboard and queries page. You can use an explicit value or use @CurrentIteration to assign new work items to the team's current iteration. The same macro used in queries to list work items assigned to the currently active iteration assigned to the team is used.

    For example, you might want all new work items added to a future iteration path, which you use to triage and assign to specific sprints at periodic intervals.

    Screenshot of Work, Iterations page for team, set team default for new work items for TFS 2018.

  4. Active sprints. Add an iteration for each sprint backlog you want active for the team. Add each sprint, one by one, by selecting it from the menu.

    Screenshot of Work, Iterations page for team, select sprint to activate for TFS 2018.

    When you're done, you should see a list of sprints, similar to the following.

    Screenshot of Work, Iterations page for team, activates sprint list for TFS 2018.

    If you don't see the sprints or dates that you need, then return to the project administration context and define them there.

  5. To see the newly activated sprint backlogs, refresh your team's product backlog page.

Rename or move an iteration

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

  1. To rename an iteration path, choose the context menu for the node, and then select Edit.

    Screenshot of Open Work, Project Configuration in browser.

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

    Screenshot of Open Work, Project Configuration dialog in browser.

  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 iteration node, the system automatically updates the existing work items with the node that you enter at the deletion prompt.

Delete an Iteration Path

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.

When you delete an Iteration Path, you must provide an Iteration Path to use to update the work items assigned to the Iteration Path you want to delete.

  1. To delete an Iteration Path, open the web portal Project settings>Project configuration>Iterations page.

  2. Choose the context menu for the node, and select Delete or Remove.

  3. In the dialog that opens, select the Iteration Path to reassign work items to, and then choose Delete path.

    Screenshot of Delete iteration dialog.

Export/import iteration paths

You can't export or import the structure of tree paths for one project to use with another project.

However, using the az boards iteration commands you can list the iterations defined for one project and then add them to another project. Once they are added, you can then use the az boards iteration team commands to add them to a team and set the default and backlog iteration path for the team. Using the Classification Nodes (REST API) and Teams (REST API), you can perform similar actions.

Archive iteration paths

After a while, you may want to archive iteration paths that were used for sprints that are a year or more out of date. You can do that by moving the iteration path under a node that you label "Archive". All work items are updated with the moved iteration path. Also, teams can de-select those sprints that have past. All data is maintained in the data store with the new iteration path assignments.

Before you archive the iterations, consider if you've captured all the reports that you may want.

Chart progress by iteration

You can quickly generate queries to view the progress for those areas. For example, you can visualize progress of work items that are assigned to sprints, as shown in the following stacked bar chart.

Stacked bar chart by area

Q & A

Q: Do I have to assign iteration paths to a team?

A: If your team doesn't use sprints to plan and track work, then no. You can leave the defaults assigned to the team as they are. You can then use the product and portfolio backlogs and boards, however you can't gain much use of sprint planning tools.

Programmatic resources

Area paths and iteration paths are also referred to as Classification Nodes.