Customize the Backlog Pages

  • Article

You can customize the backlog features of Team Web Access to specify different types of work items, fields, and columns that appear on the pages. The backlog page provides access to two types of pages. The product backlog page lists those backlog items for the product that are to be developed but are as yet uncommitted. The iteration backlog pages list those backlog items that have been assigned to a specific iteration. To learn more about using the backlog pages, see Collaborate.

Tip

If your team wants to track bugs as tasks or as backlog items, you can customize your team project using the procedures outlined in this blog post: Add bugs to the task board or backlog pages.

If your organization has several teams that work from a common backlog and across many product areas, you might want to configure your team project to decouple teams from area paths. To learn more, see Customize a team project to support team fields.

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 or modified their workflow, you may need to customize one of the definition files for process configuration.

You customize the backlog pages by exporting the XML definition files for your team project, or by downloading the latest version of the process templates for your team project. The XML definition files used to customize the backlog pages are the Categories, AgileConfiguration, and CommonConfguration. For information on exporting these files or downloading them, see Customize the Categories for Work Item Types [witadmin], Manage Process Configuration [witadmin], and Download the Latest Version of the Process Templates.

In this topic

  • “Quick add” experience

  • Columns and the column sequence

  • Types of work items that are considered backlog items

  • Team velocity

  • Remaining work, capacity-by-activity, and non-working days

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 page, your Team Web Access Permissions must be set to Full. Additional licensing requirements may apply. For more information, see Change access levels.

“Quick add” experience

Using the “quick add” feature, you can specify the fields and types of work items available for quickly adding items to the backlog. You can add or remove fields that appear in the panel that the team uses to enter new backlog items. The default configuration specifies only the Title (System.Title) for Agile and Scrum, and includes the Requirement Type (Microsoft.VSTS.CMMI.RequirementType) for CMMI.

Note

To add types of work items to the “quick add” experience, add them to the Requirements Category as described in Types of work items that are considered backlog items.

To customize the quick add panel

  1. To run the witadmin command-line tool, open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:

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

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

  2. Enter the following command 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 exportagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"

    An example of a CollectionURL is http://MyServer:8080/tfs/TeamProjectCollectionName.

  3. Open the AgileConfiguration file in Notepad, and locate the AddPanel element.

  4. Add a Field element that specifies the reference name of the field that you want to add to the panel.

    Tip

    If you have added required fields to a backlog item without specifying a default value for them, then you should consider adding these fields to the quick add experience.

    If your team project is configured to synchronize with Project Server, then you might want to add the field used to submit work items to Project Server (Microsoft.Sync.ProjSrv.Submit).

    For example, the following syntax adds the Priority element to the panel.

    <AddPanel>
   <Fields>
      <Field refname="System.Title" />
      <Field refname="Microsoft.VSTS.Common.Priority" />
   </Fields>
</AddPanel>

    Note

    For the Requirement Category, you define types of work items to include on the product backlog, and for these work items, you define fields. You must specify the reference name for a field that is defined for a type of work item that you include in the Requirements Category. For more information, see Work Item Field Reference for Visual Studio ALM.

  5. Enter the following command to import the definition file:

    witadmin importagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"

    The following illustration shows the panel after you import the file.

    Backlog panel with Rank field added

    You might have to refresh your browser to view the changes.

Back to top

Columns and column sequence for the backlog pages

You can add or remove columns, change the sequence of the columns, or change the column width for the pages that display the product backlog or an iteration backlog.

To customize the column layout

  1. From the Command Prompt window for witadmin, enter the following command, 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 exportagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"

  2. Open the AgileConfiguration file in Notepad, and locate the Columns element within the ProductBacklog section for the product backlog page, or the IterationBacklog for the iteration backlog pages.

  3. To add a new column, add a Column element that specifies the reference name of the field that you want to add.

    For example, the following syntax adds the Priority element to the columns that appear for the product backlog page. Columns appear in the order in which they're listed within this section.

    <ProductBacklog>
   <Columns>
      <Column refname="Microsoft.VSTS.Common.Priority" width="400" />
      <Column refname="System.Title" width="400" />
      <Column refname="System.State" width="100" />
      <Column refname="Microsoft.VSTS.Scheduling.Effort" width="50" />
      <Column refname="System.IterationPath" width="200" />
   </Columns>
    . . .
</ProductBacklog>

    Optionally, you can remove a column for a field.

  4. (Optional) To change the width of a column, change the value assigned to width, which is specified in pixels.

    For example, you can change the width for Story Points to 100 pixels by specifying the following syntax.

    <Column refname="Microsoft.VSTS.Scheduling.StoryPoints" width="100" />

  5. Enter the following command to import the definition file:

    witadmin importagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"

  6. Choose F5 to refresh the web page for Team Web Access to reflect the changes.

Back to top

Types of work items that are considered backlog items

Backlog items correspond to those types of work items added to the Requirements Category. Items that appear on the product backlog page correspond to work items whose workflow state is associated with the Proposed metastate or the InProgress metastate that have not yet been assigned to an iteration. For more information on these states, see Workflow states, metastates, and process configuration.

To add a work item type as a backlog item, you must configure the following elements:

  • Add the work item type to the Requirements category (Microsoft.RequirementCategory).

  • Configure the metastates for the work item type in the CommonConfiguration file if they differ from those already defined.

  • Add the field used to track effort to the work item type definition. For example, for Agile, add the following field definition:

    <FIELD name="Story Points" refname="Microsoft.VSTS.Scheduling.StoryPoints" type="Double" reportable="measure" formula="sum" >

    For more information on how the field used to track effort is used, see Team velocity. For more information, see Add a Field and Change the Layout of an Existing Work Item Type.

To specify the types of backlog work items that appear

  1. On the Command Prompt window for witadmin, type the following command, 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"

  2. Open the categories file in Notepad, and locate the CATEGORY element for the "Requirement Category".

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

    For example, the following syntax adds the work item type of "Phone Bug" to the Requirement Category for a team project that uses the Scrum process template.

    <CATEGORY name="Requirement Category" refname="Microsoft.RequirementCategory">
   <DEFAULTWORKITEMTYPE name="Product Backlog Item" />
   <WORKITEMTYPE name="Bug" />
   <WORKITEMTYPE name="Phone Bug" />
</CATEGORY>

    Important

    You must specify a type of work item that has been defined for your team project. Also, you cannot add a type of work item to the Requirement Category that has also been added to the Task Category.

  4. Enter the following command to import the definition file:

    witadmin importcategories /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\Categories.xml"

  5. Choose F5 to refresh the web page for Team Web Access to reflect the changes.

To assign metastates to workflow states of backlog work item types

  1. Continuing from the previous procedure, export the definition file for CommonConfiguration for your team project by typing the following command in the Command Prompt window:

    witadmin exportcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"

  2. Open the CommonConfiguration file in Notepad, and locate the RequirementWorkItems element.

  3. To assign a workflow state, add a STATE element that specifies the name of the state and its metastate type.

    For example, the following syntax specifies the four states for the Requirement Category of work item types, assigning two of them to the same metastate of "Proposed".

    <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

    Important

    You must specify a value for the State element that corresponds to a valid workflow state. A valid workflow state in this case is a state that has been defined for a work item type that is included in the Requirements Category for your team project. Also, you must assign a metastate type that is defined within the Agile group; that is, you can assign Proposed, InProgress, or Complete.

  4. (Optional) You can change the column heading assigned to the backlog items by changing the value assigned to plural for the RequirementWorkItems element.

    For example, the following syntax changes the column heading from "Backlog items" to "Stories":

    <RequirementWorkItems category="Microsoft.RequirementCategory" plural="Stories">

  5. Enter the following command to import the definition file:

    witadmin importcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"

  6. Choose F5 to refresh the web page for Team Web Access to reflect the changes.

Back to top

Team velocity

You can change the field used to calculate team velocity. The default field corresponds to the field used to estimate the size of your backlog items. If you change the field, then make sure that you add a FIELD element definition for the new field to the definitions of all work item types included within the Requirements Category.

The default configuration references the same field assigned to the backlog item that records the level of effort. The default process templates for Visual Studio ALM reference different fields for type="Effort", which include: Story Points for Agile (Microsoft.VSTS.Scheduling.StoryPoints), Scheduling Size for CMMI (Microsoft.VSTS.Scheduling.Size), and Effort for Scrum (Microsoft.VSTS.Scheduling.Effort). The field that you specify for type="Effort" is used to calculate team velocity and to support forecasting.

To change the field used to calculate team velocity

  1. Locate the section for TypeFields in the CommonConfigurations file.

  2. Locate the entry specified for type="Effort".

    To customize, change the field assigned to refname.

    For example, the following example specifies FabrikamFiber.Points as the field used to estimate the size of backlog items:

    <TypeField refname="FabrikamFiber.Points" type="Effort" />

Back to top

Remaining work, capacity-by-activity, and non-working days

The fields used to specify remaining work, activity, and non-working days are used in calculating the capacity, remaining work, and burndown charts. Capacity information is automatically calculated for the entire team, each team member, and for specified activities after information about team member capacity and items have been added to the backlog for an upcoming iteration. For more information, see Work in sprints.

The default configuration references the following fields defined for the task work item type and elements in the CommonConfigurations file in making the calculations:

  • Remaining Work (Microsoft.VSTS.Scheduling.RemainingWork) to report estimated and remaining work. The field that you specify should match the same field specified in the definition for the work item type that you use to track work, which is typically the task type for all process templates.

    Note

    You can report work in hours or days, or whatever time unit you want. You will want to be consistent in the units that you use to track work and to set the capacity for team members.

  • Activity (Microsoft.VSTS.Common.Activity) to associate tasks with activity and to display capacity-by-activity bars.

  • DayOfWeek to specify non-working days.

You should change the non-working days when the days that your team has off differ from Saturday and Sunday.

To change the field used for remaining work calculations

  1. Continuing from the previous procedure, locate the section for TypeFields in the CommonConfigurations file.

  2. Change the field specified for type="RemainingWork".

    To customize, change the field assigned to refname for the following TypeField entry, and optionally change the format designation from format="{0} h" to format="{0} TimeUnitString". For example, the following syntax specifies hours in place of the default text string of h,

    <TypeField refname="Microsoft.VSTS.Scheduling.RemainingWork" type="RemainingWork" format="{0} hours"

    Note

    The string that you specify for format is used on the backlog and task board pages wherever remaining work is reported. For example, when reporting capacity-by-activity or capacity per team member, or next to the column heading for the task states on the task board.

To change the field used for capacity-by-activity calculations

  1. Continuing from the previous procedure, locate the section for TypeFields in the CommonConfigurations file.

  2. Change the field specified for type="Activity".

    To customize, change the field assigned to refname for the following TypeField entry.

    <TypeField refname="Microsoft.VSTS.Common.Activity" type="Activity"/>

To change the non-working days used to calculate capacity and burndown

  1. Continuing from the previous procedure, locate the Weekends element within the CommonConfigurations file.

  2. To change a day, change the value that appears within one of the DayOfWeek elements.

    For example, if your team doesn’t work on Friday and Saturday, then specify the following syntax:

    <Weekends>
   <DayOfWeek>Friday</DayOfWeek>
   <DayOfWeek>Saturday</DayOfWeek>
</Weekends>

    Note

    You must specify the day of a week in English, regardless of the installed language of Team Foundation Server.

    Optionally, you can add a DayOfWeek element if your team works only four days out of the week.

  3. Enter the following command to import the definition file:

    witadmin importcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"

  4. Choose F5 to refresh the web page for Team Web Access to reflect the changes.

See Also

Concepts

Create and organize the product backlog

Customize Work Item Tracking and Your Team Project

Customize the Backlog and Board Pages Using Process Configuration