Customize Work Item Tracking and Your Team Project
Article
After you create a team project, you can customize it for your teams. Most areas that you can customize apply to the team project. A few areas apply to individual teams. This topic provides an overview of the most common types of customizations, implementation notes regarding operations and inter-dependencies, and links to topics that provide details on how to customize specific areas.
Note
This topic refers to team projects and work item tracking (WIT) objects that are created from one of the default process templates that Team Foundation Server (TFS) provides. A backlog item can refer to a user story, requirement, product backlog item, or bug, based on whether your team project was created using the Agile, CMMI, or Scrum process template. For more information, see Process Guidance and Process Templates for Team Foundation Server.
Areas you can customize
Area and iteration paths
Teams, team alerts, and team favorites
Agile pages and charts
Backlog pages, remaining work, capacity, velocity, and forecasting
Kanban board
Task board
Work item tags
Pick lists or items within a drop-down menu in a work item form
Fields used to track work and support reporting and integration
Workflow defined for a work item type
Limit the number of names in the Assigned To field
Restrict who can make changes to a work item or to whom a field rule applies
Apply pattern matching to a field
Methods and resources to support customization
Methods used to customize WIT objects
Additional resources
Note
You can customize the process template that you will use to create a team project. Then, after you create a team project, the customizations are already in place. Specifically, you customize the WIT object and project artifacts. Customizing process templates is the most efficient way to deploy customizations when several team projects will be created for an enterprise deployment. See Customize Process Templates.
Requirements
To create or delete areas and iterations, you must be a contributing member of the team or team project.
To create a team or to customize most WIT objects, such as a work item type, categories, or process configuration, you must be a member of the Project Administrators group for the team project.
To modify the attributes of a work item field, you must be a member of the Project Collection Administrators group.
To view team features such as the backlog and task board, you must be a member of the Full access group in Team Web Access (TWA). Additional licensing requirements may apply. For more information, see Change access levels.
To group work items into useful categories, such as related features and development milestones, you can define areas and iterations. You use areas to assign work to logical, physical, functional categories, or areas owned by a team. You use iterations to assign work to the sprints or time cycles for your team.
What you can customize related to areas and iterations:
Add child areas and iterations that nest up to 14 levels deep.
Specify a default area path and a default iteration path for a team. The defaults are automatically assigned to those backlog items that you create through the quick add panel on the product backlog page.
Set the start and end date for iterations that your team uses to track an iteration or sprint.
Limit access to view, create, or edit work items and manage test plans that are defined under an area.
Restrict who can add or modify child nodes that are defined under an area or iteration.
Implementation notes:
Child areas and iterations appear in the drop-down menus of the Area Path and Iteration Path fields. These fields appear in most work item forms and in the filter criteria within the query editor. Also, many out-of-box (OOB) reports reference these fields for the purposes of filtering.
Links for iteration backlog pages appear on the backlog page only for those iterations that have been selected for a team.
You must select at least one area path as active for a team before you can use features such as the product backlog, the task board, or team home page. See Add another team.
If you define a path that contains more than 256 characters, you will not be able to specify it in Microsoft Project. To avoid this problem, label child areas and iterations with fewer than 10 characters, and do not nest nodes more than 14 levels deep.
How you customize:
To add or modify area, open Team Web Access, and choose the gear icon next to your user name at the top of the page. On the administrative page, choose areas. Or, from Visual Studio, choose Team, Team Project Settings, Work Item Areas.
To add or modify iteration paths, from the Team Web Access administration page, choose iterations.
You can create teams within a team project to allow each team to manage their own backlog of work and manage their sprints. Also, teams can track progress using their task board and burndown chart, and set up team alerts. Each team project acts as a default team.
Note
The default team project configuration maps each new team to its own area path. However, if your organization has several teams that work from a common backlog and across many product areas, you might want to decouple teams from area paths. See Customize a team project to support team fields.
You can customize the live tiles that appear on the team home page. You add a tile by adding an object to Team Favorites from the shortcut menu for the work item query, build definition, or source control folder. The following illustration shows an example of where six tiles have been added. By choosing a tile, you can quickly access the information for the query, build definition, or source control folder.
What you can customize related to teams:
Manage team members and access to team resources.
Define team areas and iterations as described in Area and iteration paths.
Define team alerts, which send email notifications when changes occur to work items, code reviews, source control files, and builds.
Add or remove tiles from the team home page that link to the work item queries, build definitions, and source control folders.
Re-sequence the set of tiles on the team home page.
Implementation notes:
The Assigned To field is designed to only display team members when accessed from the shortcut menus of TWA.
All team members will see the tiles and sequence that you specify for the team home page. Any team member can change the tile set and sequence.
How you customize:
To add a team, from TWA, choose the gear icon to open the administrative page. On the Overview tab, choose the New Team link. See Add another team.
To add a tile to the team home page, choose Add to team favorites from the shortcut menu for each object that you want to appear on the home page. You can only add team favorites to the team home page. You can't add my favorites. See Manage team favorites.
To re-sequence the tiles, open the team home page and drag tiles to rearrange them to the preferred sequence.
Back to top
Agile pages and charts
You can customize some elements of the backlog and board pages that TWA provides. While each team can manage their own backlog and board pages, all customizations made to these pages apply to all teams defined for a team project.
Backlog pages, remaining work, capacity, velocity, and forecasting
TWA provides two types of backlog pages—the product backlog for creating and sorting backlog items and the iteration pages that support creating tasks to implement backlog items assigned to a specific iteration. In addition to these pages, charts that display capacity, burndown, and team velocity are displayed. For information on using these pages, see Collaborate.
What you can customize related to backlog pages:
Change the types of work items that appear on the backlog pages.
Change the types of work items that you can create as tasks that are linked to backlog items on the iteration backlog pages.
Change the fields that display within the quick add panel on the product backlog page. For example, you might add a required field as part of the quick panel entry.
Change the initial columns and column sequence displayed. You can modify these elements and TWA will remember your modifications.
Change the work item fields that are used to track remaining work, activity types, size of backlog items and calculate team velocity, capture the sort order for listing backlog items, and the standard days off for the team.
Implementation notes:
Links for iteration backlog pages appear on the backlog page only for those iterations that have been selected for a team.
For each work item type that you add to the backlog page, you must map one or more of its workflow states to the process configuration metastates. All states that are mapped must correspond to one of the work item types assigned to the category for which they are mapped.
If you remove a work item type from appearing on the backlog page, you must remove the mapping of its states to metastates.
The following work item fields are mapped to process configuration data types. When you add a work item type to either the Requirements Category or Task Category, you should consider adding the corresponding fields to the definition of the work item type.
Work Item Field
Type
Description
Remaining Work
RemainingWork
Supports generation of the burndown and capacity charts. Add Remaining Work to work item types that you add to the Task Category.
Activity (Agile and Scrum) or Discipline (CMMI)
Activity
Supports generation of capacity by activity. Add the corresponding field to work item types that you add to the Task Category.
Story Points (Agile), Effort (Scrum), or Size (CMMI)
Effort
Supports generation of the team velocity chart and forecasting. Add the corresponding field to work item types that you add to the Requirements Category.
Stack Rank (Agile and CMMI) or Backlog Priority (Scrum)
Order
Supports tracking the sort order of backlog items. Add the corresponding field to work item types that you add to the Requirements Category.
You can specify a different field then the ones listed in the above table as long as you assign the same field that is mapped to the process configuration type.
The sort order assigned through the product backlog page defines the sequence of items that appear on the iteration backlog and board pages.
To add or remove work item types from appearing on the backlog pages, add or remove the type from the Requirement Category. To modify the Requirement Category, modify the Categories.xml file.
To add or remove work item types that you can create as tasks from the iteration backlog pages, add or remove the type from the Task Category. To modify the Task Category, modify the Categories.xml file.
To modify the quick add panel or the initial columns or column sequence, modify the AgileConfiguration.xml file.
To modify the metastate mapping or the field-to-type assignments, modify the CommonConfiguration.xml file.
The Kanban board displays a swim lane or series of columns that list work items in the product backlog according to their workflow state.
Note
Visual Studio 2012 Update 1 or later must be installed on the application-tier servers for Team Foundation Server in order to use the Kanban board. Visual Studio 2012 Update 2 or later must be installed in order to customize the Kanban board. See Quarterly Update for Microsoft Visual Studio Team Foundation Server 2012.
What you can customize on the Kanban board:
Add or remove columns and change the column titles.
Change the column sequence.
Set a limit on the number of work items to appear in an intermediate workflow state (one that is not new or completed).
The sequence used to list work items in each swim lane is derived from their assigned backlog priority, as described in Create and organize the product backlog.
The original set of columns and column titles are derived from the workflow-to-metastate mappings defined in the CommonConfiguration file.
You add or modify workflow states by modifying the work item type. See Workflow defined for a work item type.
Task board
The task board displays the work items defined for the current iteration. They include work item types that have been assigned to the Task Category arranged under the column that corresponds to their current State assignment.
Tip
To better understand how TWA determines which work items to display on the task board, you can view the filter criteria for the current iteration. Choose the backlog page for the current sprint, choose Create Backlog Query, choose OK, and then choose the Click here to view it link. On the work items page, choose Editor.
The board column headings are derived from the workflow states assigned to the work item types added to the Task Category. Only those states that have been mapped to a metastate appear. Also, the iteration backlog pages reference which work item types that you can add as tasks according to those that have been defined for the Task Category. To learn more about how to use the task board, see Work in sprints.
What you can customize on the task board page:
Add or change the types of work items that appear on the task board. For example, in addition to the Task type, you can add Bug to the set of types that are treated as task on the iteration backlog pages and task board.
Add or remove a column by adding or removing a state from the metastate mapping. For example, if you have a workflow state that you use to indicate blocked work items, you can map that state to have the blocked column appear on the board page.
Change the maximum limit set for the number of work items that can appear on the task board. By default, the task board is restricted to a total of 500 work items.
Implementation notes:
For each work item type that you add to the Task Category, you have to map one or more of its work flow states to the process configuration metastates. All states that are mapped must correspond to one of the work item types assigned to the category for which they are mapped. Only those states that are mapped appear as columns on the board.
To support tracking work and burndown calculations, you should add the Remaining Work field to the definition for each work item type that is added to the Task Category.
You can't add a work item type to both the Requirements Category and the Task Category. For example, you can't add Bug to the Requirements Category and Task Category.
How you customize:
To add or remove work item types that act as tasks, add or remove the type from the Task Category. To modify the Task Category, modify the Categories.xml file.
To modify the metastate mapping, modify the CommonConfiguration.xml file. For example, by adding the mapping, <State value="Blocked" type="Proposed" />, as shown in the following syntax you can add the Blocked column to the task board:
To increase or decrease the number of items that can appear on the task board, specify a new limit in the definition for AgileConfiguration.xml. For example, to set the maximum items to 600, specify the following:
Tagging supports adding searchable keywords to work items, enabling you to quickly categorize and filter a work item list. Tags can be applied to any work item type—tasks, bugs, backlog items. You can add and assign tags to work items using TWA. You can then filter the product backlog or a work item query based on the tags you select.
Enable or disable filtering for a work item list or product backlog page by choosing Filter.
Implementation notes:
To view tags assigned to work items in a list, add the Tags field as a column to a backlog page or query.
You can view tags assigned to work items in Team Explorer, an Excel worksheet or Project plan. However, you cannot modify or create tags using one of these clients.
You cannot edit or delete tags. However, TFS automatically removes any tag from the system after 3 days of not being referenced by any work item.
Pick lists or items within a drop-down menu in a work item form
Pick lists are the enumerated values that appear within a drop-down menu in a work item form and the Value column within the query editor. You define most pick lists in the FIELD definition for a work item type. The exceptions to this rule are:
You define values for the Area Path and Iteration Path fields from the administrative pages of Team Web Access form. See Area and iteration paths.
You define values for the State and Reason fields within the WORKFLOW section of the definition for the work item type. See Workflow defined for a work item type.
You define values for fields associated with user accounts such as Assigned To by adding users to a TFS security group or by restricting access to a group or set of users.
By default, the list for the Assigned To field contains the account names for all users and groups that have been added anywhere within Team Foundation Server. These accounts are often synchronized with Active Directory. See Prepare for Installation.
What you can customize related to pick lists:
Define simple pick lists that apply to a single field within a work item type.
Define global lists that you can use across many work item types and team projects within a project collection.
Specify allowed, suggested, or prohibited values within either a pick list or a global list.
Combine lists, restrict to whom a list applies, and set conditions on when a list appears on the work item form.
Implementation notes:
You can define pick lists only for fields with a data type of Integer or String.
By using global lists, you can minimize the work that is required to update a list that multiple types of work items share and that are shared by many team projects within a team project collection. Use global lists when you want to enforce common usage across team projects.
You can define different pick lists for the same field, which appears in different work item types and team projects.
How you customize:
To define or modify a pick list, modify the field definition for the work item type. See Define Pick Lists.
To define a global list, modify the definition for the global list maintained for the team project collection. To use the global list, include it within the field definition within the work item type. See Define Global Lists.
Back to top
Fields used to track work and support reporting and integration
You use work item fields to track data for a work item type, to define the criteria for queries, and to design reports. You can customize how you use a predefined work item field for a work item type, or you can create fields that will support additional requirements for tracking data. Also, you can specify or change the attribute of a field.
A default set of fields appears in the relational warehouse database or the cube, based on the assignments made to each work item field. Before you add a new field, you should consider if you can use an existing field or modify the reportable attributes of an existing field. See Reportable Fields Reference for Visual Studio ALM.
What you can customize related to work item fields:
Add a field to a work item type. You can add a system field, a field defined in another work item type, a custom field, or an integration field.
Any field that you want to appear in a report, except system fields, must be defined in the definition file for the types of work items that the field will track.
To support data entry for a field, you must include the field in both the FIELDS section and the FORM section of the definition of the work item type.
When you add or modify fields, you should apply systematic naming conventions to make sure that data is logically grouped into folders in the SQL Server Analysis Services cube. See Add and Modify Work Item Fields to Support Reporting.
All fields defined within work item types are managed at the team project collection level. Errors can result when attributes assigned to a field defined for one team project differs from those assigned to another team project. To manage these errors, see Resolve Schema Conflicts That Are Occurring in the Data Warehouse.
The workflow allows teams to track the status and progress of work. Each work item type is associated with a workflow. Each workflow definition consists of a set of valid states, transitions, reasons, and optional actions that will be performed when a team member changes the state of a work item. For example, the state determines the status of the work, such as New, Proposed, Active, In Progress, Completed, or Closed. Transitions represent a valid progression, regression, or side-ways state, such as Removed, between states. Reasons support tracking why the transition was made. For example when a bug is reactivated, you can select a reason such as Closed in Error or Regression.
The following illustration shows a side-by-side comparison of the default workflow states for the backlog items defined for the default process templates that TFS provides. For more information, see Choose a Process Template.
Important
The following illustrations are based on the default process templates provided with the installation or upgrade to TFS 2012. Significant updates were made to the workflow for several work item types in the latest quarterly update. These changes support backward transitions so that when you inadvertently drag a work item on the Kanban board or the task board to a resolved or closed state, you can drag it back to an earlier workflow state. To learn more about the update, see What's New in Planning and Tracking.
To get access to the latest versions of the default process templates and update your team project with the latest workflow definitions, install the latest quarterly update for Team Foundation Server. You can obtain the update from the Microsoft download site: Quarterly Update for Microsoft Visual Studio Team Foundation Server 2012.
Visual Studio Scrum 2.0
MSF for Agile v6.0
Product Backlog Item State Diagram
User Story State Diagram
What you can customize in the workflow for a work item type:
Add or remove states, transitions, or reasons.
Change the default reason.
Restrict the types of modifications that can be made to the work item or a field and by whom, based on the change of state, selection of a reason, or the type of transition being made. See Restrict who can make changes to a work item or to whom a field rule applies.
The drop-down menus for the State and Reason fields display the values assigned in the WORKFLOW section of the work item type.
If you add a state to a work item type that appears on the backlog or board pages in Team Web Access, and you want that state to appear as a column on the board page, you must also map the state to a metastate.
To map workflow states to metastates, modify the definition for the CommonConfiguration.xml file. See Customize Process Configuration.
Back to top
Limit the number of names in the Assigned To field
By default, the drop-down menu for the Assigned To field displays all users who have been granted access to TFS. This is the default valid users group. You can limit the set of users who are displayed to reflect only those user accounts that have been added to a TFS or Windows security group.
What you can customize in the Assigned To field :
Limit the list of users who appear in the drop-down menu for the Assigned To field or other custom person-name field.
Implementation notes:
The most efficient way to apply security restrictions is to create custom groups that you manage either in Windows or in TFS.
In Team Web Access, the shortcut menus that support assigning work items are limited to members of the team.
How you customize:
Create the security group that you want to use and add the accounts to the group. For example, create a new group called Team Contributors. See Change Permissions for a Group or User.
Modify the definition file for each work item type that you want to limit the user set. Add the VALIDUSER element to the FIELD element definition for the Assigned To field, and specify the TFS group.
For example, the following code snippet can be added to the Task definition to limit the set of users for the Assigned To field to only those team members added to the TFS Team Task Group.
<FIELD name="Assigned To" refname="System.AssignedTo" type="String" reportable="dimension" syncnamechanges="true">
<HELPTEXT>The person currently working on this task</HELPTEXT>
<ALLOWEXISTINGVALUE />
<VALIDUSER group="Team Contributors" />
</FIELD>
By specifying the ALLOWEXISTINGVALUE element, you avoid validation errors that would otherwise occur when members leave the team and are no longer registered as project contributors.
Restrict who can make changes to a work item or to whom field rules apply
You can restrict who can create, modify, resolve, or close a work item or modify a work item field. Also, you can specify restrictions on which field rules are in effect, based on who is creating or modifying a work item.
What you can restrict:
Which field rules are in effect, based on who is modifying the work item. You can apply restrictions to the following rule elements, limiting their applicability to or enforcing them for a group of users. You can specify these rules upon creation or modification of the work item or when changing the state, during a specific transition, or upon selecting a reason:
CANNOTLOSEVALUE
COPY
DEFAULT
EMPTY
FROZEN
MATCH
READONLY
REQUIRED
SERVERDEFAULT
VALIDUSER
For example, with the following code snippet, you can enforce the rule that only members of the Management Team can modify the Stack Rank field once a work item has been created.
<FIELD name="Stack Rank" refname="Microsoft.VSTS.Common.StackRank" type="Double" reportable="dimension">
<FROZEN not="Management Team" />
<HELPTEXT>Work first on items with lower-valued stack rank. Set in triage.</HELPTEXT>
</FIELD>
Which field rules are in effect, based on who is modifying the work item and conditional on the value assigned to another field. Conditional rules include WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED. See Assign Conditional-Based Values and Rules.
Who can modify work items by setting permissions on area paths. See Area and iteration paths.
Who can modify a field by adding a field rule to the WORKFLOW section. For example, you can restrict all users except those who belong to the Management Team group from making changes to the Story Points field when the work item is set to Resolve by specifying the following syntax:
You can apply field rules and conditional field rules when a user changes the state, makes a specific transition, or selects a reason.
For the State and Reason fields, you can only apply the READONLY field rule.
You cannot apply field rules to the Area Path or Iteration Path fields.
Implementation notes:
The most efficient way to apply security restrictions is to create custom groups that you manage either in Windows or in TFS.
You can apply restrictions to any system-defined or custom field that you use to assign account names. These fields are referred to as person-name fields. You can enable synchronization between TFS and Active Directory for custom person-name fields. See Managing Work Item Fields [witadmin].
How you customize:
Modify the definition file for each work item type that you want to place restrictions on. For example, you can limit users who can create a work item by specifying a VALIDUSER group for the Created By field in the WORKFLOW section.
In the same way, you can place restrictions on who can resolve, close, or re-activate a work item by adding field rules in the workflow on the following fields: Resolve By, Closed By, or Activated By.
You can create a global list that specifies which groups are valid and add that to the FIELD definition under ALLOWEDVALUES or PROHIBITEDVALUES.
You can create custom groups either in TFS or in Windows.
To place restrictions on which rules apply to a field, specify the for or not attributes within the FIELD child element within the FIELDS section. For example, you can specify that the Required for Release field is READONLY for all users except those in the Team Triage Group.
<FIELD name="Required for Release" refname="MyCompany.ProjectA.RequiredForRelease" type="String" reportable="dimension">
<READONLY not="Team Triage Group" />
<HELPTEXT>Specify Yes when true, otherwise leave blank.</HELPTEXT>
</FIELD>
You can restrict entries made to a field to match a prescribed pattern of alphanumeric characters. For example, you can enforce users to enter a value that corresponds to a build number by specifying a rule that matches the naming/numbering convention that you have established for labeling builds.
What you can customize by pattern matching:
Restrict entries to match a specific pattern.
Restrict entries to a field to match at least one of a set of patterns.
Specify users or groups for which the rule applies or does not apply.
Implementation notes:
You can apply pattern matching to Integer and String fields only.
How you customize:
Modify the definition file for the work item type with the field that you want to enforce pattern matching. For example, you can enforce entry of a date in the form of month.day.year by specifying the MATCH rule.
<FIELD refname="MyCompany.ProjectA.RequestDate">
<MATCH pattern="nn.nn.20nn" />
<HELPTEXT>Enter the date the request was received.</HELPTEXT>
</FIELD>
Once a team project has been created, you can customize a WIT object in one of the following ways:
Use the Process Editor to modify a work item type.
You can modify work item types by using Process Editor, a power tool add-in for Visual Studio which you can download and install. Located under the Tools menu, Process Editor provides a graphical user interface. You can use this tool to import and export work item types, edit work item types, and modify the contents of a process template. For more information, see the following page on the Microsoft website: Team Foundation Server Power Tools.
Modify an attribute of a work item field: You can use the witadmin command line tool to change the attributes assigned to a field. See Managing Work Item Fields [witadmin].
Export, modify, and import a definition file for a WIT object: For each object that you want to customize, you must perform the following steps: identify the scope of changes, identify dependencies, export objects, update objects, import objects, and verify changes.
Process for customizing objects that track work
The objects that you can customize using this process include work item types, categories, link types, global lists, global workflow, and process configuration.
.png "Settings Icon (Team Web Access)")
gear icon next to your user name at the top of the page. On the administrative page, choose areas. Or, from Visual Studio, choose Team, Team Project Settings, Work Item Areas..png "Manage team favorites")
.png "Turn tag filtering on or off")
Filter..png "State diagram of product backlog item")
.png "User Story state diagram")
.png "Process for customizing a WIT object")