Add and modify area and iteration paths
Go here to open the Visual Studio 2015 version of this topic.
To group work items by product, functional, or feature area, use area paths. To group work into sprints, milestones, or time periods in which they’ll be worked on, use iteration paths. To restrict access to a group of work items, use either area or iteration paths.
Area and iteration paths 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.
Add an area node or a child node
If you aren’t a project administrator, get added as one. You need to be a project administrator to add nodes under a team area, or have your permissions set to Allow for Create child nodes for an area path, as described later in this topic, in Restrict access to work items assigned to an area or an iteration.
From your team project page in Team Web Access (TWA), open the administration page.
.png "Choose the gear icon to open administration")
To learn more about connecting to TWA, go here.
Open Areas. Most teams are associated with a default area path.
.png "Areas page for a team project, TWA admin context")
The default area path is used to filter the backlog items for the team project backlog pages. Also, the area path is set to the team’s default when teams create work items from an Agile planning tool page.
Add a child node to the area you have selected. For restrictions on names, go here.
.png "New child link on Areas page, Create Area dialog.")
Add an iteration child node and set iteration dates
Most team projects come with a predefined set of iteration paths, based on the process template. You can rename or add to this set.
From the Iterations page, you can add and select the iterations that will be active for your team. Add iteration nodes the same way you add area nodes.
.png "Example Iterations for a Team")
To specify an iteration or a child iteration for a team, select the check box next to that iteration or child iteration. If you choose an iteration, you won’t be able to select any child iterations. If you want to use the child iterations, clear the check box for the iteration, and then select the check boxes for the child iterations you want to use for your team.
Open a sprint or iteration to set the start and end dates.
.png "Define start and end dates for a sprint")
After you set the start and end dates for one iteration, the calendar tool automatically sets the next set of dates, based on the same iteration length you specified for the first. For example, if you set a 3 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.
Tip
You don’t have to define dates for your iteration or use them at all, but doing so can help you schedule your work and track progress against that schedule.
Restrict access to work items assigned to an area or an iteration
You can assign permissions at either the user level or the group level for both areas and iterations. Permissions restrict or allow access to work items, test cases, or test plans. You can also restrict or allow users or groups to manage the project structure for an area or iteration.
Open permissions for the node you want to manage.
.png "Security option in an Area context menu")
Select the group or team member, and then change the permission settings. In the following example, the Disallow Access Group has no permissions to view, modify, or edit work items or permissions in the FabrikamFiber area path.
.png "Permissions page for a team project")
To change a permission, choose Not set, Inherited allow, Allow, or Deny.
If the group or team member doesn’t appear in the list, you can Add it. To create a TFS group, open the Security tab.
If your application-tier server has been upgraded to TFS 2013.3, then permissions to Manage test suites has been added to the area path security model. The existing Manage test plans permission has been re-scoped to manage only test plans. Previously it covered permission management of both test plans and test suites. To learn more about these permissions, see Q: What functions are covered under test management permissions?
For additional ways to restrict modifications to work items, see Restrict who can create or modify a work item.
Q & A
Q: Are there restrictions in terms of naming and structuring child nodes?
A: The Area and Iteration fields are paths that consist of multiple node items that are separated by backslash (\) characters. These fields use the TreePath data type. A best practice is to minimize the names of nodes, and consider these restrictions when naming area and iteration paths:
Restriction type |
Restriction |
|---|---|
Node length |
|
Special characters for nodes |
|
Reserved names |
|
Path length |
|
Path hierarchy depth |
|
For more information about the TreeType field, see Areas and iterations field reference.
Q: Are there restrictions on applying field rules to the Area Path and Iteration Path fields?
A: Yes. Many field rules can’t be defined for System.XXX fields. To learn more, see Apply a field rule.
Q: What permissions do I need to add or modify area and iteration paths?
A: To create or modify 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.
Q: How do I structure teams, areas, and iterations to support hierarchical teams or scale agility within an enterprise?
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.
Also, these two white papers can walk you through the steps for configuring teams, area paths, and iterations to support portfolio management or enterprise organizations: Agile Portfolio Management: Using TFS to support backlogs across multiple teams and Scaled Agile Framework: Using TFS to support epics, release trains, and multiple backlogs.
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 your 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. As an example, when work items are assigned to area paths, you can visualize progress by area, as shown in the following stacked bar chart.
.png "Configure Chart dialog box for a Stacked bar chart")
The built-in Velocity chart relies on the definition of team iterations.
In addition, the security permissions assigned to an area path control who has access to manage test plans and test suites under that area path.
Q: What functions are controlled by test management permissions? (Requires TFS 2013.3)
A: The Manage test suites permission enables users to:
Create and modify test suites
Add or remove test cases to/from test suites
Change test configurations associated with test suites
Modify the suite hierarchy by moving a test suite
The Manage test plans permission enables users to:
Create and modify test plans
Add or remove test suites to or from test plans
Change test plan properties such as build and test settings
Additional test management permissions are assigned at the team project level and include the ability to create, delete, and view test runs, and manage test configurations and environments. See Project-level permissions.
Q: What kind and how many area nodes should a team define?
A: You don’t have to add any area nodes. However, areas are useful to filter work item queries and reports based on features. Consider these guidelines when adding area nodes:
Define areas that support your traceability and security requirements.
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 might find that it is too much work to duplicate the structure and permissions in other team projects.
Each team can create a hierarchy of areas under which the team can organize their backlog items, user stories, requirements, tasks, and bugs.
Use areas to represent logical or physical components, and then create child areas to represent specific features. Your team can use this structure to keep work items organized and improve traceability by component or feature.
Create areas that you want to restrict access to.
Q: How many iteration nodes should a team define?
A: You define as many iteration paths as you need to reflect your project lifecycle. These paths represent a hierarchy of events, such as sprints, pre-beta and beta deliverables, and other release milestones. Consider these guidelines when defining iteration child nodes:
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, perhaps labeled Future, for work items that you’re not ready to assign to a target release cycle.
For an overview of how you can plan a sprint by using iterations, see Work in sprints.
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.
Backlog Beta 1 Beta 2 Release 1.0 Release 2.0 |
.gif "Area and Iteration Hierarchy icon")
MyApplicationAs 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.
Backlog Sprint 1 Sprint 2 Sprint 3 Sprint 4 Sprint 5 |
.gif "Collapse icon for Area and Iteration hierachies")
Beta 2Iterations 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.
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.