Create and Modify Areas and Iterations

To group work items by product, functional, or feature area, you define area paths. To group work into sprints, milestones, or time periods in which they’ll be worked on, you define iteration paths. To restrict access to a group of work items, you can use either area or iteration paths. The procedures to create and modify area and iteration paths in a team project are the same when working in Visual Studio Online and Team Foundation Server (TFS). If you need to create a team project, go here.

Area and iteration paths are useful for generating queries and also support key functions of the Agile planning tools. A team’s default area path is used to filter the backlog items for each team’s backlog pages. Work items created using Agile planning tools auto-assign the area and iteration paths based on team defaults. Many artifacts provided by the default process templates use the iterations to organize work and display team progress.

In addition, the default method for creating teams associates each team with a default area path. If your organization has several teams that work from a common backlog and across many product areas, might may want to use a custom field to represent teams. To support this configuration, see Customize a team project to support team fields.

Requirements

You must be a member of the team for which you want to modify areas and iterations. All team members can choose iterations for the team, specify areas for the team, and specify dates for the iterations for the team.

To create areas or iterations, you must either be a member of the Project Administrators group or your Create and order child nodes, Delete this node, and Edit this node permissions must be set to Allow for the area or iteration node that you want to modify. For more information, see Change permission levels.

Modify work areas

You use the context menu for areas to add, edit, or delete child nodes, to set permissions on who can modify work items under a node, to set a default area for a team, and to exclude subareas.

Context menu for Areas

To add an area or subarea

1. From your team project page in Team Web Access (TWA), open the administration page.

   

   To learn more about connecting to TWA, go here.

2. Open Areas. Most teams are associated with a default area path.

   

   The default area path is used to filter the backlog items for the team project backlog pages.

3. To add a new area or subarea, do one of the following:

   • To create a subarea, choose New Area.

   • To create an area that is a child of an existing area, highlight that area, choose the context icon for the area, and then choose New Child.

   • To create an area that is a peer of an existing area, highlight that area, choose the down arrow next to that area, and then choose New.

   The Create Area window opens.

4. In the Create Area window, specify the Area Name, and then choose Save and Close.

To specify an area as the default area for a team or team project

• Continuing from the previous procedure with the Areas page displayed, choose the set default link for the area that you want to be the default.

  All new work items will automatically be set to the default area path.

Modify iterations and set iteration dates

To view and specify iterations for a team

1. Open the home page for the team, and then choose Configure schedule and iterations.

   The Iterations window opens.

   

2. In the Iterations list, view the iterations selected for your team. Iterations selected for your team will have a check box selected by the iteration name.

   Tip

   By default, all iterations for a team project will be displayed. To view only the iterations selected for your team, next to Show, choose all to toggle the selection to selected only.

3. To specify an iteration or sub-iteration for a team, select the check box next to that iteration or sub-iteration. If you choose an iteration, all sub-iterations will not be selectable. If you want to use the sub-iterations, clear the check box for the iteration, and then select the check boxes for the sub-iterations you want to use for your team.

To add an iteration or sub-iteration

1. Continuing from the previous procedure with the Iterations window displayed, do one of the following:

   • To create an iteration, choose New Iteration. A new iteration will be created that is a peer to the other iterations in the list.

     The Create Iteration window opens.

   • To create an iteration that is a child of an existing iteration, highlight that iteration, choose the context menu next to that area, and then choose New Child.

   • To create an iteration that is a peer of an existing area, highlight that iteration, choose the context menu next to that iteration, and then choose New.

     The Create Iteration window opens.

2. In the Create Iteration window for Iteration Name, specify a name for the iteration. Optionally specify start and end dates for the iteration either by typing them in the text boxes for Start Date and End Date, or by choosing the calendar icon and then specifying the dates within the calendar window. If you are creating an iteration in a different location from the default, specify a different location for the iteration in Location, and then choose Save and Close.

To specify dates for an iteration

1. Continuing from the previous procedure with the Iterations window displayed, highlight the iteration for which you want to specify dates, and then choose set dates.

   The Edit Iteration window opens.

2. Specify start and end dates for the iteration either by entering them in the text boxes for Start Date and End Date, or by choosing the calendar icon and then selecting the dates within the calendar window. Then choose Save and Close.

Restrict access to work items assigned to an area

By assigning permissions, you can scope the set of actions that users or groups can perform on work items or test plans that are assigned to an area. You can also restrict or allow users or groups to manage the project structure for an area or iteration.

To control access to an area

1. Open the

2. The Permissions window appears for the node you selected, as the following illustration shows:

   

3. Choose the name of a group or user whose permissions you want to set.

   You can add users or groups and then set the permission to allow or deny for each user or group. Specifically, you can grant or deny permission to manage the structure of a node, and for area paths, to view or modify work items or manage test plans that are assigned under the node.

4. To change a permission, choose not set, deny or inherited to change it to allow, or choose allow to change it to deny.

   Note

   Your ability to change a permission will depend on your current permission settings. If you are unable to change a permission, contact your administrator for either the team project or Team Foundation Server.

5. When you have finished modifying the permissions, choose Save and Close.

For additional ways to restrict modifications to work items, see Manage Permission to Create or Modify Work Items.

Guidelines for specifying areas and iterations

For an overview of how you can define iterations and plan a sprint, see Collaborate. When you specify the areas and iterations for your team or team project, consider the following guidelines:

• For Areas

  • Define areas that support your traceability and security requirements.

  • Each team can create a hierarchy of areas under which the team can organize their user stories, requirements, tasks, and bugs.

  • Use areas to represent logical or physical components, and then create sub-areas to represent specific features. Your team can use this structure to keep work items organized and improve traceability by component or feature.

  • Set permissions on areas to restrict access to work items that are assigned to particular categories. You can set security options that dictate not only who can change each area node but also who can edit or even view work items in a particular area. For more information, see Restrict access to work items assigned to an area or iteration earlier in this topic.

  • Avoid creating an area structure that is too complex. You can create areas to partition permissions on work items, but complex trees require significant overhead for permission management. You may find that it is too much work to duplicate the structure and permissions in other team projects.

• For Iterations

  • Use iterations to represent sprints, milestones, or cycle time for your project.

  • Determine the cycle duration that meets your team processes, and define your iterations to support that cycle.

  • Create a separate iteration for unassigned backlog items, user stories, requirements, tasks, or other work items.

  • For an overview of how you can plan a sprint by using iterations, see Work in sprints.

• For Both Areas and Iterations

  • When you name an area or iteration, follow the conventions that Naming conventions and restrictions on areas and iterations summarizes later in this topic.

  • The area and iteration fields use the TreePath data type. For more information, see Areas and Iterations Field Reference.

  • When you run a query to find work items that are assigned to an area or an iteration, the results always include all work items that are defined under the path of that area or iteration. You can also create queries to find work items that are not under a specific node. For more information, see Query Fields, Operators, Values, and Variables and Query for Bugs, Tasks, or Other Work Items.

  • You cannot export the area and iteration nodes that you have created for one team project to use with another team project.

Back to top

Areas

You build the structure of product areas by creating nodes that represent components and features. As an example, you might create three areas for a team project that is named MyApplication. These areas would represent the three main development components of a tiered web application: the website, the web services, and the database. As the following illustration shows, you can create a node under the team project node for each of these components, which are labeled My Websites, My Web Services, and My Database.

After you create these areas, you can assign work items, such as user stories, tasks, or bugs, to a specific area and run a query to find all items that are assigned to that area.

You can also organize the major components into more granular groupings. As the following example shows, each top node now contains two or more child nodes.

Iterations

You build the structure of the project lifecycle by creating nodes that represent a hierarchy of events, such as sprints, pre-beta and beta deliverables, and other release milestones. In the following example, Backlog, Beta 1, Beta 2, Release 1.0, and Release 2.0 are defined for the MyApplication team project. You can assign all work items to the Backlog iteration if they are not yet scheduled for work or for a release.

As you create the backlog of product features and tasks, you can start to assign them to the milestones by which you expect the team to finish the features and tasks. As your needs change, you can add events under each major milestone that reflect how your team schedules and manages its work. As the following example shows, the Beta 1 iteration now contains five child nodes, one for each sprint in the Beta 1 time period.

Iterations do not enforce any rules. For example, you can assign a task to an iteration but not close or complete it during that iteration. At the end of an iteration, you should find all work items that remain active or have not been closed for that iteration and take appropriate action. You can, for example, move them to a different iteration or return them to the backlog.

Restrictions on area and iteration paths

The Area and Iteration fields are paths that consist of multiple node items that are separated by backslash (\) characters. The following table describes the restrictions that govern the definition of nodes and paths.

Q & A

Q: What happens when I rename or delete an area or iteration node?

A: When you rename an area or an iteration, or move the node within the tree hierarchy, you must manually update the work items that reference the existing path or paths. You can perform a bulk update using TWA or Excel.

When you delete an area or an iteration node, the system automatically updates the existing work items with the node that you enter at the deletion prompt.

Q: What tools rely on area or iteration paths?

A: The Agile planning tools—Create and organize the product backlog and Work in sprints—are built from system queries that reference the team area path. You can view these queries by choosing the Create query link that appears on these tools’ pages. However, you can’t change the underlying query.

Also, for a sprint or iteration backlog page to appear for a team, it must first be defined and selected.

You can quickly generate queries or filter reports to view the progress for those areas and iterations.

Q: How do I create another team? Is there a way to create a “hierarchy” of teams?

A: Although there is no concept of sub-teams, you can create teams whose area paths are under another team, which effectively creates a hierarchy of teams. To learn more, see Add another team.

Q: Is there a way to decouple teams from the team area path?

A: Yes. If your organization has several teams that work from a common backlog and across many product areas, you might want to change how teams are configured. By adding a custom field to represent teams in your organization, you can reconfigure the agile planning tools and pages to support your teams and decouple assignment to teams and area paths.

Q: Can I export the area and iteration paths?

A: No. You can’t export the structure of tree paths for one team project to use with another team project.

Q: How are default area and iteration paths defined?

A: By default, team projects that are based on Visual Studio ALM process templates have several predefined iteration nodes and the team project as the top area node. For information about how to customize these settings, see Define the Initial Areas and Iterations in the Classification Plug-in.

See Also

Concepts

Areas and Iterations Field Reference

Collaborate

Other Resources

Work Items and Workflow (Agile)

Use Team Web Access to interact with Visual Studio ALM