Define Iteration Paths (aka sprints) and configure team iterations

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

You add Iteration Paths to support teams who implement Scrum or use sprint planning to group work items based on a time-box interval or sprint. You define Iteration Paths at the project level and then each team selects the ones they want to be active for them under the team configuration. You can create a flat iteration path structure or a hierarchy of paths to support releases, sub-releases, and sprints.

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

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. All you need to do is specify the dates.

Important

Make sure that you select the correct version of this article for Azure DevOps Services or Azure DevOps Server, renamed from Team Foundation Server (TFS). The version selector is located above the table of contents.
Content version selector

Prerequisites

  • You add Iteration Paths to a project. If you don't have a project yet, create one now.
  • To add an Iteration Path under the root node or edit or delete any child node, you must be a member of the Project Administrators group. To acquire these permissions, see Set permissions at the project- or collection-level.
  • Or, 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 you want to manage: Create child nodes, Delete this node, and Edit this node, and View permissions for 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.
  • To set team Iteration Paths, you must be added as the team administrator or be a member of the Project Administrators group.

For naming restrictions on Iteration Paths, see About areas and iterations, Naming restrictions.

Get started sequence

If you are new to managing projects and teams, the most straight forward sequence for configuring iterations for your project and teams is as follows:

  1. First, define the Area Paths and teams following the guidance provided in Define area paths and assign to a team.
  2. 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.
  3. Determine if you want a flat structure or hierarchy of sprints and releases.
  4. 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.
  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 iteration path(s).
  6. Each team should assign the default Iteration Path they selected to their work items. This is needed in order 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 perform the following actions 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

Backlog iteration versus default iteration

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.

For TFS 2015 and earlier versions, the default iteration is the same as the backlog iteration. The one value selected both filters items that appear on the team's backlogs and boards, and is assigned to work items created from the team context.

Open Project Settings, list project iterations

From the web portal, open Project Settings.

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

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

    Project Settings>Work>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, open Project settings.

  2. From the web portal for the project context, 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

  3. Choose Work.

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

Open the project administration page

Add iterations and set iteration dates

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

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

You add and modify area paths from the Work, Iterations page from the project admin or settings context.

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

Project Settings Context, Work, Iterations page

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

    Choose the calendar icon to choose new dates.

    Work, Iterations page, scheduled set of sprints

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

    Work, Iterations page, scheduled set of sprints

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

  1. Open the Iterations tab for the project context.

    For Scrum-based projects, you'll see these set of sprints.

    Example Iterations for a Team

    You can change the name, location within the tree hierarchy, or set dates for any sprint. Simply open it (double-click or press Enter key) and specify the info you want.

  2. Schedule the start and end dates for those sprints you plan to use.

    Define start and end dates for a sprint

    After you set the start and end dates for one iteration, the calendar tool automatically attempts to set the next set of dates, based on the same iteration length you specified for the first. For example, if you set a three week sprint for Sprint 1, then when you select the start date for Sprint 2, the calendar tool automatically determines the start and end dates based on the next three weeks. You can accept or change these dates.

  3. To add another sprint, select New child and name it what you want. Here, we call it Sprint 7.

    Iterations, defaults defined for Agile

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

Open team settings, list team iterations

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.

From a web browser, open the web portal administrative context for your team.

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 the  team profile icon. Then choose Team Settings.

    Here we open the Board for the Web 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

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.

    Project settings>Work>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.

    Work, 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 used when a work item is created from the team dashboard (new work item widget) and queries page. You can use an explicit value or use @CurrentIteration to assign new work items to the team's current iteration. This is the same macro used in queries to list work items assigned to the currently active iteration assigned to the team.

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

    Work, Iterations page for team, set team default for new work items

  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.

    Work, Iterations page for team, select sprints

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

    Work, Iterations page for team, activates sprint list

    If you don't see the sprints you need, or the dates aren't set, you can add or edit iterations for the project, provided you have the required permissions. To learn more, see Define iteration paths (aka sprints).

  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.

    Work, Iterations page for 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.

![Work, Iterations page for team, set team backlog iteration for backlogs and boards](_img/team-defaults/stdefaults-team-backlog-iteration.png)

Also, all work items added through a team's backlog or board are assigned the backlog iteration. 
  1. Default iteration. The default iteration defines the iteration used when a work item is created from the team dashboard (new work item widget) and queries page. You can use an explicit value or use @CurrentIteration to assign new work items to the team's current iteration. This is the same macro used in queries to list work items assigned to the currently active iteration assigned to the team.

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

    Work, Iterations page for team, set team default for new work items

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

    Work, Iterations page for team, select sprint to activate

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

    Work, Iterations page for team, activates sprint list

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

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

  1. Open the Iterations page for the team context.

    Here we open the Iterations page for the Web team.

    Open team admin iterations page

    If your team isn't listed in the navigation row, open the Overview tab, select your team, and then return to the Iterations tab.

  2. Default iteration. Only work items assigned to an iteration equal to or under the default iteration appear in the team's backlogs and boards. Also, the default iteration defines the iteration used when a work item is created from the team dashboard (new work item widget) and queries page.

    Open the context menu for the iteration path you want.

    Here we set the P1 1 path. Only child iterations of the backlog iteration can be active for a team.

    Set team default iteration path

    This path determines which work items appear in your team backlogs and boards, and the default assigned to work items created from any area under your team's context.

  3. Active sprints. Check each box under the default iteration that you want active for the team.

    Here, the Fabrikam Fiber Web team activates Sprints 1 through 7.

    Select team active sprints

    Check boxes only appear for sprints defined under the default iteration path.

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

Rename, move, or delete 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 or paths.

  1. To rename an iteration path, choose the  actions icon for the node, and 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 iteration node, the system automatically updates the existing work items with the node that you enter at the deletion prompt.

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.

Prior to archiving the iterations, consider if you have captured all the reports that you may want.

Chart progress by iteration

You can quickly generate queries to view the progress for those areas. As an example, you can visualize progress of work items 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 won't be able to gain much use of sprint planning tools.

As you can see, iterations play a major role in supporting Agile tools and managing work items. You can learn more about working with these fields from these articles:

Programmatic resources