Add bugs or other work item types to backlogs or boards

Article
09/18/2015

Go here to open the Visual Studio 2015 version of this topic.

Some teams like to track bugs as backlog items, such as product backlog items, user stories, or requirements. Other business processes may require tracking additional work item types (WITs) on the backlog or task board.

If you’re using a Scrum project, bugs already appear on your backlog. However, if your team project was created using other process templates, such as Agile or CMMI, bugs don't appear on the backlog nor task board.

To add bugs or other WITs, you can configure team settings or customize your team project to support these choices:

Deployment	Choices
Visual Studio Online	See Show bugs on backlogs and boards.
On-premises with TFS 2013.4 update	Option A: Allow teams to choose to track bugs on the backlog Option B: All teams track bugs or additional WITs on the backlog Option C: All teams track bugs or other WITs on the task board
On-premises without TFS 2013.4 update	Option B: All teams track bugs or other WITs on the backlog Option C: All teams track bugs or other WITs on the task board

Visual Studio Online

See Show bugs on backlogs and boards.

On-premises with TFS 2013.4 update

Option A: Allow teams to choose to track bugs on the backlog
Option B: All teams track bugs or additional WITs on the backlog
Option C: All teams track bugs or other WITs on the task board

On-premises without TFS 2013.4 update

Option B: All teams track bugs or other WITs on the backlog
Option C: All teams track bugs or other WITs on the task board

If you work in an on-premises TFS, you can customize your team project so that bugs or other WITs appear in either the backlog or the task board, but not both.

If you’re making changes to team projects defined on TFS 2012, view the Visual Studio 2012 version of this topic.

Option A: Allow teams to choose to track bugs on the backlog (Visual Studio Online or TFS 2013.4)

Each team can choose to track bugs on their backlog. If you connect to an on-premises TFS, it must be updated to TFS 2013.4. (See Microsoft Visual Studio 2013 Update 4.

If you’re not a team administrator, get added as one.
Open Settings from the team’s administration page and select the check box to track bugs.

If you don’t see the option, you need to update the process configuration for your team project.
To see the changes, open or refresh the team’s backlog page.

Update process configuration to support tracking bugs on the backlog (on-premises TFS)

If the track bugs on the backlog option is disabled on the team settings page, verify or update the following XML definition files for your team project. You’ll need to be a member of the Project Administrators group to update these objects.

Categories: The Requirement Category should only contain those WITs associated with backlog items. The Bug Category should only contain those WITs associated with bugs. Specifically, the Requirement Category mustn’t contain an entry for Bug.

For example, these definitions are correct:

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

And, these definitions are incorrect because the Bug WIT is included in the Requirement Category:

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

To update Categories, see Import and export categories [witadmin].

ProcessConfiguration: Contains the BugWorkItems element that defines the Bug Category and maps the bug workflow states to metatstates. For example:
```
<BugWorkItems category="Microsoft.BugCategory" pluralName="Bugs" singularName="Bug">
    <States>
      <State value="Active" type="InProgress" />
      <State value="Resolved" type="Resolved" />
      <State value="Closed" type="Complete" />
    </States>
</BugWorkItems>
```
In addition, metastate mappings must be consistent under RequirementWorkItems and BugWorkItems. For example, Active cannot be mapped to Proposed under one and to InProgress under another.

To update ProcessConfiguration, see Import and export process configuration [witadmin].
WIT definitions: WITs that are included in the Bugs Category must have the following fields defined:
- Field used to track effort (type=Effort in the ProcessConfiguration file), for example Story Points (Microsoft.VSTS.Scheduling.StoryPoints) or Size (Microsoft.VSTS.Scheduling.Size) based on whether Agile or CMMI process template was used to create the team project.
- Field used to track the backlog priority (type=Order in the ProcessConfiguration file), for example Stack Rank (Microsoft.VSTS.Common.StackRank).
- For a team project based on MSF for CMMI, the Requirement Type (Microsoft.VSTS.CMMI.RequirementType) field because it’s included in the quick add panel for the process configuration.

To update WIT definitions, see Import, export, and manage work item types [witadmin].

Verify or update the Kanban board column mappings

Open the product backlog Board page (Kanban board).

If you see a message indicating that the column configurations are not valid, you’ll need to adjust the column mappings.
Open Customize Columns and map the bug workflow states for each column you have defined.

For example, map each column as shown:

Option B: All teams track bugs or other WITs on the backlog

WITs that you add to the Requirement Category show up on the backlog pages. For bugs to appear on the User Stories (Agile) or Requirements (CMMI) backlog page, make the following modifications to your on-premises TFS team project:

Add the field used to estimate effort to the bug or other WIT definition: Story Points (Agile) or Size (CMMI),
Add the bug or other WITs to the Requirement Category.
Verify the metastate mappings in the process configuration.

Here’s how you add the bug WIT for a team project that’s based on the MSF for Agile process template.

Add the Story Points field

Export the bug WIT definition.

witadmin exportwitd /collection:" CollectionURL" /p:MyProject /n:bug /f:DirectoryPath/bug.xml

Add the Story Points field.

<FIELDS>
. . . .
   <FIELD name="Story Points" refname="Microsoft.VSTS.Scheduling.StoryPoints" type="Double" reportable="measure" formula="sum">
      <HELPTEXT>The size of work estimated for implementing the bug.</HELPTEXT>
   </FIELD>



. . . .
</FIELDS>

For a team project based on CMMI, add Size and the Requirement Type.

<FIELD name="Size" refname="Microsoft.VSTS.Scheduling.Size" type="Double" reportable="measure" formula="sum" >
   <HELPTEXT>The size of work estimated for implementing this requirement</HELPTEXT>
</FIELD>
<FIELD name="Requirement Type" refname="Microsoft.VSTS.CMMI.RequirementType" type="String" reportable="dimension">
   <REQUIRED />
   <ALLOWEDVALUES>
      <LISTITEM value="Scenario" />
      <LISTITEM value="Quality of Service" />
      <LISTITEM value="Functional" />
      <LISTITEM value="Operational" />
      <LISTITEM value="Interface" />
      <LISTITEM value="Security" />
      <LISTITEM value="Safety" />
      <LISTITEM value="Business Objective" />
      <LISTITEM value="Feature" />
   </ALLOWEDVALUES>
   <DEFAULT from="value" value="Functional" />
</FIELD>

Add Story Points to the form layout.

<FORM>
. . . 
   <Column PercentWidth="33">
      <Group Label="Planning">
      <Column PercentWidth="100">
      <Control FieldName="Microsoft.VSTS.Scheduling.StoryPoints" Type="FieldControl" Label="Story Points" LabelPosition="Left" />
       <Control FieldName="Microsoft.VSTS.Common.StackRank" Type="FieldControl" Label="Stack Rank" LabelPosition="Left" NumberFormat="DecimalNumbers" MaxLength="10" EmptyText="&lt;None&gt;" />
       <Control FieldName="Microsoft.VSTS.Common.Priority" Type="FieldControl" Label="Priority" LabelPosition="Left" />
       <Control FieldName="Microsoft.VSTS.Common.Severity" Type="FieldControl" Label="Severity" LabelPosition="Left" />          
       </Column>               
  </Group>

   </Column>
. . . 
</FORM>

For a CMMI based team project, add Size and the Requirement Type to the FORM section.

<Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.Size" Label="Size" LabelPosition="Left" />
<Control Type="FieldControl" FieldName="Microsoft.VSTS.CMMI.RequirementType" Label="Type" LabelPosition="Left" />

Import the updated bug definition.

witadmin importwitd /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/bug.xml"

Add the bug WIT to the Requirement Category

Export the categories definition. If you don't have TFS admin permissions, get them.

witadmin exportcategories /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.xml"

Add the bug work item type to the Requirement Category.

<CATEGORY refname="Microsoft.RequirementCategory" name="Requirement Category">
    <DEFAULTWORKITEMTYPE name="User Story" />
    <WORKITEMTYPE name="Bug" />
</CATEGORY>

Import the categories file.

witadmin importcategories /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.xml"

Verify the metastate mappings in the process configuration

Export the process configuration definition.

witadmin exportprocessconfig /collection:"CollectionURL" /p:MyProject /f: "DirectoryPath/ProcessConfiguration.xml"

Verify that the Resolved state is defined in the RequirementBacklog section.

<RequirementBacklog category="Microsoft.RequirementCategory" pluralName="Stories" singularName="User Story">
    <States>
      <State value="New" type="Proposed" />
      <State value="Active" type="InProgress" />
      <State value="Resolved" type="InProgress" />
      <State value="Closed" type="Complete" />
    </States>. . . 

  </RequirementBacklog>

If you’ve customized your bug to add additional states, then add mappings for each state you’ve added. Always map the last state within a forward transition to type="Complete".

Import the process configuration.

witadmin importprocessconfig /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/ProcessConfiguration.xml"

Confirm that you can add bugs to the product backlog

Open the product backlog page, or refresh the page if it’s already open.

You should see a drop-down menu for the work item Type.

Customize the Kanban board to map Bug states to swim lanes

Open the product backlog Board page (Kanban board).

If you have just added the Bug work item type, or any other work item type, you’ll see a message indicating that the column configurations are not valid.
Open Customize Columns and map the bug workflow states for each column you have defined.

For example, map each column as shown:

Option C: All teams track bugs or other WITs on the task board

WITs that you add to the Task Category show up on the task board and iteration backlog pages. For bugs or tasks to appear on the task board, you must link them to a parent product backlog item (Scum), user story (Agile), or requirement (CMMI).

For on-premises TFS, make these modifications to track bugs as tasks:

Add required fields to the bug WIT definition.
Add the bug WIT to the Task Category.
Add required metastate mappings to the process configuration.

Here’s how you do this for a team project based on the MSF for Agile process template.

Add required fields

If you don't have admin permissions for your team project, get added as a Project Administrator.
Open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:
```
cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDE
```
On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%. You can download Team Explorer for free.
Export the bug work item type definition.
```
witadmin exportwitd /collection:"CollectionURL" /p:MyProject  /n:bug /f: "DirectoryPath/bug.xml"
```
An example of a CollectionURL is "http://MyServer:8080/tfs/TeamProjectCollectionName".

Add the Activity field. If you don’t, the configuration won’t be valid. Optionally, add the scheduling fields so that you can track remaining and completed work. The Microsoft.VSTS.Scheduling.XXX fields are used in out-of-the-box reports, but not by the Agile planning tools. If your team doesn't use these fields, then you don't have to add them.

<FIELDS>
. . . 
   <FIELD name="Activity" refname="Microsoft.VSTS.Common.Activity" type="String" reportable="dimension">
      <HELPTEXT>Type of work involved</HELPTEXT>
         <SUGGESTEDVALUES>
            <LISTITEM value="Development"/>
            <LISTITEM value="Testing"/>
            <LISTITEM value="Requirements"/>
            <LISTITEM value="Design"/>
            <LISTITEM value="Deployment"/>
            <LISTITEM value="Documentation"/>
         </SUGGESTEDVALUES>
   </FIELD>
   <FIELD name="Remaining Work" refname="Microsoft.VSTS.Scheduling.RemainingWork" type="Double" reportable="measure" formula="sum">
      <HELPTEXT>An estimate of the number of units of work remaining to complete this task</HELPTEXT>
   </FIELD>
   <FIELD name="Original Estimate" refname="Microsoft.VSTS.Scheduling.OriginalEstimate" type="Double" reportable="measure" formula="sum">
      <HELPTEXT>Initial value for Remaining Work - set once, when work begins</HELPTEXT>
   </FIELD>
   <FIELD name="Completed Work" refname="Microsoft.VSTS.Scheduling.CompletedWork" type="Double" reportable="measure" formula="sum">
      <HELPTEXT>The number of units of work that have been spent on this task</HELPTEXT>
   </FIELD>
   <FIELD name="Start Date" refname="Microsoft.VSTS.Scheduling.StartDate" type="DateTime" reportable="dimension">
      <HELPTEXT>The date to start the task</HELPTEXT>
   </FIELD>
   <FIELD name="Finish Date" refname="Microsoft.VSTS.Scheduling.FinishDate" type="DateTime" reportable="dimension">
      <HELPTEXT>The date to finish the task</HELPTEXT>
   </FIELD>
. . . 
</FIELDS>

For a team project based on MSF for CMMI, you would add the Discipline and scheduling fields.

<FIELD name="Discipline" refname="Microsoft.VSTS.Common.Discipline" type="String" reportable="dimension">
        <ALLOWEDVALUES>
          <LISTITEM value="Analysis" />
          <LISTITEM value="User Experience" />
          <LISTITEM value="User Education" />
          <LISTITEM value="Development" />
          <LISTITEM value="Test" />
        </ALLOWEDVALUES>
        <HELPTEXT>The discipline to which the task belongs</HELPTEXT>
      </FIELD>

Add the Activity and scheduling fields to the work item form. You can simply copy the Groups defined in the Task work item type and replace the Groups that are there.

<FORM>
. . . 
      <Group Margin="(10,0,0,0)">
          <Column PercentWidth="30">
            <Group Label="Status">
              <Column PercentWidth="100">
                <Control FieldName="System.AssignedTo" EmptyText="&lt;No one&gt;" Type="FieldControl" Label="Assi&amp;gned To" LabelPosition="Left" />
                <Control FieldName="System.State" Type="FieldControl" Label="Stat&amp;e" LabelPosition="Left" />
                <Control FieldName="System.Reason" Type="FieldControl" Label="Reason" LabelPosition="Left" />
              </Column>
            </Group>
          </Column>
          <Column PercentWidth="20">
            <Group Label="Planning">
              <Column PercentWidth="100">
                <Control FieldName="Microsoft.VSTS.Common.StackRank" Type="FieldControl" Label="Stack Rank" LabelPosition="Left" NumberFormat="DecimalNumbers" MaxLength="10" EmptyText="&lt;None&gt;" />
                <Control FieldName="Microsoft.VSTS.Common.Priority" Type="FieldControl" Label="Priority" LabelPosition="Left" />
                <Control FieldName="Microsoft.VSTS.Common.Activity" Type="FieldControl" Label="Activity" LabelPosition="Left" EmptyText="&lt;None&gt;" />
              </Column>
            </Group>
          </Column>
          <Column PercentWidth="30">
            <Group Label="Classification">
              <Column PercentWidth="100">
                <Control FieldName="System.AreaPath" Type="WorkItemClassificationControl" Label="&amp;Area" LabelPosition="Left" />
                <Control FieldName="System.IterationPath" Type="WorkItemClassificationControl" Label="Ite&amp;ration" LabelPosition="Left" />
              </Column>
            </Group>
          </Column>
          <Column PercentWidth="20">
            <Group Label="Effort (Hours)">
              <Column PercentWidth="100">
                <Control FieldName="Microsoft.VSTS.Scheduling.OriginalEstimate" Type="FieldControl" Label="Original Estimate" LabelPosition="Left" />
                <Control FieldName="Microsoft.VSTS.Scheduling.RemainingWork" Type="FieldControl" Label="Remaining" LabelPosition="Left" />
                <Control FieldName="Microsoft.VSTS.Scheduling.CompletedWork" Type="FieldControl" Label="Completed" LabelPosition="Left" />
              </Column>
            </Group>
          </Column>
        </Group>

. . . 
</FORM>

Import the updated bug definition.

witadmin importwitd /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/bug.xml"

Add the bug WIT to the Task Category

Export the categories definition.

witadmin exportcategories /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.xml"

Add bug to the Task Category.

<CATEGORY refname="Microsoft.TaskCategory" name="Task Category">
    <DEFAULTWORKITEMTYPE name="Task" />
    <WORKITEMTYPE name="Bug" />
</CATEGORY>

Note

It's OK for the bug work item type to belong to two categories—the Bug Category and the Task Category.

Import the categories file.

witadmin importcategories /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.xml"

Add metastate mapping to the process configuration

Export the process configuration definition.

witadmin exportprocessconfig /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/ProcessConfiguration.xml"

Add a metatstate mapping for the Resolved state to the TaskBacklog section .

<TaskBacklog category="Microsoft.TaskCategory" pluralName="Tasks" singularName="Task">
    <States>
      <State value="New" type="Proposed" />
      <State value="Active" type="InProgress" />
      <State value="Resolved" type="InProgress" />
      <State value="Closed" type="Complete" />
    </States>
. . . 

  </TaskBacklog>

If you’ve customized your bug to add additional states, then add mappings for each state you’ve added. Always map the last state within a forward transition to type="Complete".

Import the process configuration.

witadmin importprocessconfig /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/ProcessConfiguration.xml"

Confirm that you can add bugs to the task board

Open the task board page, or refresh the page if it’s already open.
You should be able to select either task or bug as a linked work item to a user story.
To add existing bugs to the task board, open a user story. In this example, the user story is titled Bug debt. From the ALL LINKS tab, choose the bugs to include in the sprint.

You might have to refresh the task board for the bugs to show up.

Tip

You can't add bugs through the Implementation tab because those are restricted to tasks only. To support adding bugs through the Implementation tab, modify the FORM section of the user story work item type to include the filter for bugs.

On the task board, drag a bug or task to update its status. You’ll notice that you can’t drag an item to a column for which the state isn’t valid. For example, you can’t drag a bug into the New state, or a Task into a resolved state. If you want to use these states, then add them to the workflow definition for the corresponding WIT definition.

Q & A

Q: How do I add items to the backlog or task board?

A: You add backlog items, WITs that are defined in the Requirement Category, using the quick add panel on the Backlog page. You add tasks and WITs defined in the Task Category using the add feature on either the sprint backlog or task board.

Q: What other tools can I use to edit XML definition files?

A: With the witadmin command line tool, you can import and export definition files as shown in this topic. Other tools you can use for this task are the Process Editor, available with the download of TFS Power Tools, or TFS Team Project Manager, a community resource project available on CodePlex. Using TFS Team Project Manager, you can quickly export, edit, and import XML definition files without having to use the command line interface.

Q: What happens if I remove the Bug WIT from the Requirement Category for my Scrum-based team project?

A: Out-of-the-box and custom queries that reference the Requirement Category will no longer return results that include the Bug WIT. You might want to update these queries.

Also, when you create a requirement-based test suite, the retrieved work items belong to the Requirement Category. For scrum teams that want to create test plans for bugs, they'll need to update the query to include the Bug Category.

Q: What do I need to know about metastate mappings?

A: The procedures describe in Option B and Option C describe how to make changes to your team project that is based on the Agile and CMMI process templates that TFS 2013 provides. The state model for the WITs that you add must align to the metastate mappings specified within the ProcessConfiguration file. If the state model and the metatstate mappings do not align, you have to make additional definitions, as described here.

Q: How do I make bugs appear on the sprint backlogs and task board for Scrum?

A: If your team project is based on the Scrum process template and you want bugs to be peers with tasks and not product backlog items, follow these steps:

Edit the Bug work item definition: Add the Activity and Remaining Work fields to the FIELDS and FORM sections.
Edit the Categories definition: Add Bug to the Task Category and remove it from the Requirement Category.

Edit the process configuration definition: Map the New, Approved, and Committed states to metastates under the Task Category. For example:

<TaskBacklog category="Microsoft.TaskCategory" pluralName="Tasks" singularName="Task">
    <States>
      <State value="New" type="Proposed" />
      <State value="Approved" type="Proposed" />
      <State value="To Do" type="Proposed" />
      <State value="Committed" type="InProgress" />
      <State value="In Progress" type="InProgress" />
      <State value="Done" type="Complete" />
    </States>

 . . .
</TaskBacklog >

Q: Why don’t all bugs appear on the product backlog?

A: Bugs added to the backlog based on the Agile process template will disappear on a refresh because the Active state is mapped to the In Progress metastate. To make sure that these bugs appear on the backlog, change the In progress items filter to Show.

Q: Why don’t all the bugs and tasks I’ve assigned to a sprint appear on the sprint backlog?

A: It’s possible to assign tasks to an iteration but not have them linked to a parent backlog item. These items will show up in the created query, but will not show up on the task board itself. TFS runs the query and then applies a few background processes before displaying the task board items.

These reasons can cause work items that belong to the Task Category to not appear on a sprint backlog or task board:

The task hasn’t been linked to a parent backlog item. Only those bugs and tasks that you have linked to a parent product backlog item (Scrum), user story (Agile), or requirement (CMMI) whose iteration path is set to the sprint will appear on the sprint backlog page.
The task is a parent of another task. If you’ve created a hierarchy of tasks, only the child-level tasks at the bottom of the hierarchy appear.
The task’s linked parent corresponds to a backlog item defined for another team. Or, the area path of the task’s parent backlog item differs from the task’s area path.

Q: How are the Backlog Priority or Stack Rank fields used?

A: The backlog and board pages use the Backlog Priority (Scrum) and Stack Rank (Agile and CMMI) fields to manage the sort order of work items. These fields should be defined for all WITs for a team project. However, you don’t need to include them on the work item form. These fields must match the field assigned to the Order type in the ProcessConfiguration definition file.