Customize the Backlog and Board Pages Using Process Configuration

You can customize several process configuration elements to meet your Agile planning and Scrum processes. Many of these elements control the new Agile planning tools provided with Team Web Access. For more information, see Configuration Changes Made to Add New Features.

If your team project was created using a process template other than those provided by Microsoft or you have customized the type definitions for work items, you might need to customize the definition files that support process configuration. Also, if you have customized or added types of work items and want to use those fields, then you will want to determine how to modify the process configuration elements to match other objects that you have customized.

Process configuration elements determine the layout and functionality of the following features:

• Product backlog and team velocity

• Sprint or iteration backlog, team capacity, and burndown charts

• Task board

• Stakeholder feedback

• My Work and Code Review

You customize these features by customizing one or more of the following definition files for your team project: AgileConfiguration, CommonConfiguration, and Categories.

In this topic

• Categories, process configuration, and disabling creation of specific types of work items

• Workflow states, metastates, and process configuration

• Customize the product backlog page

• Customize the sprint or iteration backlog pages

• Customize the task board page

• Customize bugs and My Work

• Export and import definition files for process configuration

Requirements

• To run the witadmin command-line tool, you must be a member of the Team Foundation Administrators group or a member of the Project Administrators group for the project. For more information, see Team Foundation Server Permissions.

• To view the backlog or task board pages, your Team Web Access Permissions must be set to Full. Additional licensing requirements may apply. For more information, see Change access levels.

Categories and process configuration

Process configuration references the categories specified for the team project. A category is simply a group of work item types that have been defined as belonging in the same group to support query and process functions. For example, the default configuration for all process templates specifies the following categories, all of which are required to support features used by Visual Studio ALM:

• Bug Category

• Code Review Request Category and Code Review Response Category

• Feedback Request Category and Feedback Response Category

• Requirement Category

• Shared Step Category

• Task Category

• Test Case Category

• Hidden Types Category

Most of these categories are self-explanatory, and most only contain one work item type within the category. The exception to this rule is the Hidden Types Category.

If you have created work item types that act in similar ways and you want to treat them in similar ways as those defined by the above categories, then you will want to add them to the category. For example, if you have defined one or more types of bugs, then you might want to add those types to the Bug Category. In this way, the process configuration will automatically treat these bug types as they do the standard bug work item type. Or, you can customize the Requirements Category to include two or three types of work items that you can then add to the product backlog or set to appear on the task board.

To learn more about how categories are used, see Define Categories to Group Work Item Types.

Agile tools and category requirements and restrictions

You can specify which types of work items are considered as backlog items or as task items. For example, the Scrum process template assigns the Bug and Product Backlog Item types to the Requirements Category, whereas the Agile template assigns User Story and the CMMI template assigns Requirement. All default process templates assign the Task type of work item to the Task Category.

When assigning work item types to categories, consider the following operational notes:

• You must assign at least one work item type to the Requirements Category and one work item type to the Task Category.

• You cannot assign the same work item type to both the Requirements Category and to the Task Category.

• If you include more than one work item type in the Requirements Category or the Task Category, the type assigned to the DEFAULTWORKITEMTYPE element appears as the default type on the Agile backlog and board pages.

• For all work item types that you assign to a category that is referenced in the CommonConfiguration file, you must assign the workflow states to a valid metastate as described in Workflow states, metastates, and process configuration. Several Team Foundation clients reference category and metastate assignments defined in the CommonConfiguration file.

Hidden Types Category

The Hidden Types Category specifies the set of work item types that you do not want users to create manually. These type definitions are used to support the feedback and code review experiences, as well as the definition of test cases.

Customize categories

You can customize the types of work items that are included within any category by modifying the Categories.xml file. For more information, see Define Categories to Group Work Item Types.

To specify the types of work items to include within a category

1. Export the definition file for categories for your team project as described in Export and import definition files for process configuration.

2. Open the Categories file in Notepad or other text editor, and locate the CATEGORY element that you want to modify.

   For example, locate the CATEGORY element for the "Hidden Types Category".

   <CATEGORY name="Hidden Types Category" refname="Microsoft.HiddenCategory">
      <DEFAULTWORKITEMTYPE name="Code Review Request" />
      <WORKITEMTYPE name="Code Review Response" />
      <WORKITEMTYPE name="Feedback Request" />
      <WORKITEMTYPE name="Feedback Response" />
      <WORKITEMTYPE name="Shared Steps" />
   </CATEGORY>
   

3. To add a new type of work item to a category, add a WORKITEMTYPE element that specifies the friendly name of the work item type that you want to add.

   For example, the following syntax adds the custom work item type of "Integration Build" to the Hidden Types Category.

   <CATEGORY name="Hidden Types Category" refname="Microsoft.HiddenCategory">
      <DEFAULTWORKITEMTYPE name="Code Review Request" />
      <WORKITEMTYPE name="Code Review Response" />
      <WORKITEMTYPE name="Feedback Request" />
      <WORKITEMTYPE name="Feedback Response" />
      <WORKITEMTYPE name="Shared Steps" />
      <WORKITEMTYPE name="Integration Build" />
   </CATEGORY>
   

4. Import the definition file for categories to your team project.

Back to top

Workflow states, metastates, and process configuration

Each work item type is associated with a workflow which is comprised of a set of workflow states and valid transitions between those states. Workflow states define how a work item progresses from first activation or creation to closed or complete. For example, the states defined for the Scrum 2.0 product backlog item define a progression of four states, from New, Approved, and Committed, to Done, and also includes a fifth state, Removed, to account for a state outside of the typical progression. Metastates, on the other hand, determine how the backlog and task boards treat each workflow state. The primary metastates used by the backlog and task board are Proposed, InProgress, and Complete. By associating each workflow state to a metastate, the background operations performed to display the backlog and task boards know how to correctly interpret the status of each work item. Metastates are specific to types of work items.

For example, the following syntax represents the associations that are made in the definition file for CommonConfiguration to map the workflow states for the types of work items defined in the Microsoft.RequirementCategory for the Scrum 2.0 process template. In this example, the New and Approved states are associated with the Proposed metastate. The Proposed metastate indicates work items that are new, not yet committed, or not yet being worked on and are therefore displayed on the product backlog page. Once a workflow state transitions to a state that is associated with the Complete metastate, the associated work item will fall off the product backlog items page. However, it will continue to be listed on the Kanban board, as described in Customize the Kanban board.

  <RequirementWorkItems category="Microsoft.RequirementCategory" plural="Backlog items">
    <States>
      <State value="New" type="Proposed" />
      <State value="Approved" type="Proposed" />
      <State value="Committed" type="InProgress" />
      <State value="Done" type="Complete" />
    </States>
  </RequirementWorkItems>

The following table describes the two categories of metastates and the enumerated types supported by each.

Back to top

Customize the product backlog page

The product backlog represents a list of requirements for the product that you are developing. Backlog items correspond to a specific type of work item based on the process template used to create your team project, such as product backlog item, user story, or requirement. If you use different types of work items or capture your requirements using two or more types of work items, then you can customize the product backlog page to support your usage. Specifically, you can customize the layout and functionality of the product backlog page in the following ways:

• Specify the fields and types of work items available for quickly adding items to the backlog using the “quick add” panel.

• Set columns and the column sequence used to list product backlog items.

• Adjust the types of work items that are considered backlog items.

• Set the workflow states of backlog items that are on the product backlog, or are completed and should be considered when calculating the team velocity.

  Note

  Make sure that only work item types with a workflow state that corresponds to the Proposed metastate appear on the product backlog page. Also, if you add a work item type to the Requirements category, make sure that you add the field that is used to track effort for the team velocity to the definition for the work item type.

• Set the field used to calculate team velocity.

You customize these features by customizing one or more of the following definition files for your team project: AgileConfiguration, CommonConfiguration, and Categories. For more information, see Customize the Backlog Pages.

Back to top

Customize the Kanban board

The Kanban board displays a swim lane or series of columns that list work items in the product backlog according to their workflow state. The original set of columns and column titles are derived from the workflow-to-metastate mappings defined in the CommonConfiguration file. However, you can customize the Kanban board through the user interface to add columns and change the column headings. See Manage your backlog with the Kanban board.

Customize the sprint or iteration backlog pages

The sprint or iteration backlog pages display both the set of requirements that you and your team have committed to a specific iteration cycle and the tasks that you have linked to those requirements. Tasks must be linked to requirements using the child link type. Because the types of work items that appear on these pages correspond to the same types that appear on the product backlog page, much of the customization work that you do for the product backlog page will define the functionality of the iteration backlog pages.

You can customize the layout and features of the iteration backlog pages in the following ways:

• Set the columns and column sequence that appear.

• Determine the sequence or sort order of backlog items.

• Adjust the types of child work items that you can add (default is task). For an end-to-end example of adding a work item type to the task board or backlog, see Add bugs to the task board or backlog.

• Specify the fields and format (hours or days) used to calculate remaining work.

• Specify the field used to associate activity and remaining work using capacity-by-activity.

• Specify the non-working days that are referenced in calculating capacity and burndown (defaults correspond to Saturday and Sunday).

You customize these features by customizing one or more of the following definition files for your team project: AgileConfiguration, CommonConfiguration, and Categories. For more information, see Customize the Backlog Pages. To learn more about working with the backlog pages, see Create and organize the product backlog and Work in sprints.

Back to top

Customize the task board page

With the task board, your team can update work items and report progress. The columns of the task board correspond to the workflow states assigned to tasks. The work items displayed include all backlog items that have been assigned to the current iteration, and all linked child tasks of these items, regardless of the iteration to which they have been assigned.

Task items that can be added as child tasks to the backlog items correspond to the types of work items assigned to the Task Category. On the board, tasks appear under the column heading of their workflow state. As you drag the tasks from one column to another, the state field for that item is automatically updated.

Because the types of work items that appear on these pages correspond to the same types that appear on the iteration backlog pages, much of the customization work that you do for the iteration backlog page determines what appears on the task board page.

You can customize the features of the task board page in the following ways:

• Determine which types of child work items appear on the task board and which types you can add as a child item to a backlog item (default is task).

• Select the workflow states of task items that are considered to be on the task board.

• Change the maximum limit set for the number of work items that can appear on the task board. The default is 500 work items.

You customize these features by customizing one or more of the following definition files for your team project: AgileConfiguration, CommonConfiguration, and Categories. For more information, see Customize the Backlog Pages. To learn more about working with the task board, see Work in sprints.

Back to top

Customize bugs and My Work

My Work, a Team Explorer feature that helps developers organize their work, reduce interruptions, and work more efficiently, references the metastates assigned to the Bug Category.

You customize this area by updating the definition files for Categories and CommonConfiguration. For more information, see Support Bug Update Status Using My Work.

Back to top

Export and import definition files for process configuration

Prior to customizing your process configuration, you might have to export the current definition file defined for your team project. Once you have customized a definition file, you must import it into your team project for the changes to appear.

To export a definition file

1. On a computer where Visual Studio or Team Explorer is installed, open a Command Prompt window and enter:

   cd %programfiles%\Microsoft Visual Studio 11.0\Common7\IDE
   

   On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.

2. To export the definition files for categories or process configuration, type the following commands, one at a time, substituting your data for the arguments that are shown here, where CollectionURL specifies the URL of a team project collection, ProjectName specifies the name of a team project defined within the collection, and DirectoryPath specifies the name and location for the file to export. Then choose Enter.

   witadmin exportcategories /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\categories.xml"
   witadmin exportagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"
   witadmin exportcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"
   

   The following command shows an example of how to import definition files for the agile process configuration:

   witadmin exportagileprocessconfig /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:"C: AgileConfiguration.xml"

To import a definition file

• To import the definition files for categories or process configuration, continue from the previous procedure and type the following commands, one at a time, substituting your data for the arguments that are shown, and then choose Enter.

  witadmin importcategories /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\categories.xml"
  witadmin importagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"
  witadmin importcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"
  

  Important

  Importing a definition file overwrites any existing categories or configurations defined for the team project.

Back to top

See Also

Concepts

Process Configuration XML Element Reference

Customize Work Item Tracking and Your Team Project

Customize Project Tracking Data, Forms, Workflow, and Other Objects

Other Resources

Define and Customize Work Item Workflow

Define Categories to Group Work Item Types