Add bugs to the task board or backlog

  • Article

Some teams like to track bugs as tasks and other teams track them as backlog items, such as user stories or requirements. If you’re using a Scrum project, bugs are already in your backlog. However, if your team project was created using the Agile, CMMI, or other process template, bugs don't appear on the task board or the backlog.

You can configure your team project so that bugs appear in either the task board or the backlog, but not both.

This topic describes how to make changes to your team project that is based on either the Agile or CMMI process templates that TFS provides. The state model for the work item types that you add must align to the metastate mappings specified within the CommonConfiguration file. If the state model and the metatstate mappings do not align, you have to make additional definitions, as described here.

Important

Some of the fields shown in your version of work item types might differ from what is shown here. With TFS upgrades, some changes were made to process templates. Follow the basic procedures outlined in this topic and adapt as needed to fit your team project.

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.

Track bugs as tasks

To track bugs as tasks, make these modifications:

  1. Add required fields to the bug work item type.

  2. Add the bug work item type to the Task Category.

  3. 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 to the bug work item type

  1. If you don't have admin permissions for your team project, get them.

  2. 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)%. You can download Team Explorer for free.

  3. Export the bug work item type definition.

    witadmin exportwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject  /n:bug /f:Directory/bug.xml

  4. 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="Stack Rank" refname="Microsoft.VSTS.Common.StackRank" type="Double" reportable="dimension">
      <HELPTEXT>Work first on items with lower-valued stack rank. Set in triage.</HELPTEXT>
   </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>

  5. Add the Activity and scheduling fields to the work item form.

    <FORM>
. . . 
   <Group Label="Status">
      <Column PercentWidth="33">
         <Control Type="FieldControl" FieldName="System.AssignedTo" Label="Assi&amp;gned to:" LabelPosition="Left" />
         <Control FieldName="Microsoft.VSTS.Common.StackRank" Type="FieldControl" Label="Stack Rank" LabelPosition="Left" />
         <Control FieldName="Microsoft.VSTS.Common.Activity" Type="FieldControl" Label="Activity" LabelPosition="Left" EmptyText="&lt;None&gt;" />
         </Column>
         <Column PercentWidth="33">
         <Control Type="FieldControl" FieldName="System.State" Label="&amp;State:" LabelPosition="Left" />
         <Control Type="FieldControl" FieldName="System.Reason" Label="&amp;Reason:" LabelPosition="Left" />
      </Column>
      <Column PercentWidth="33">
         <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Triage" Label="Triag&amp;e:" LabelPosition="Left" />
         <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Priority" Label="Priorit&amp;y:" LabelPosition="Left" />
         <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>
. . . 
</FORM>

  6. Import the updated bug definition.

    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/bug.xml

Add the bug work item type to the Task Category

  1. Export the categories definition.

    witadmin exportcategories /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/categories.xml

  2. 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.

  3. Import the categories file.

    witadmin importcategories /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/categories.xml

Add metastate mapping to the process configuration

  1. Export the common process configuration definition.

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

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

    <TaskWorkItems 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>
. . . 

  </TaskWorkItems>

    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".

  3. Import the process configuration.

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

Confirm that you can add bugs to the task board

  1. Open the task board page, or refresh the page if it’s already open.

  2. You should be able to select either task or bug as a linked work item to a user story.

    Task board with bug work item type added

  3. 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.

    Link several bugs to a user story

    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.

Track bugs as backlog items

Work item types that you add to the Requirements 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:

  1. Add the field used to estimate effort to the bug work item type: Story Points (Agile) or Size (CMMI),

  2. Add the bug work item type to the Requirement Category.

  3. Verify the metastate mappings in the process configuration.

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

Add the Story Points field to the bug work item type

  1. Export the bug work item type definition.

    witadmin exportwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /n:bug /f:Directory/bug.xml

  2. 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 MSF for CMMI, you would add the Discipline field.

  3. Add the Story Points field to the form layout.

    <FORM>
. . . 
   <Column PercentWidth="33">
      <Control FieldName="Microsoft.VSTS.Scheduling.StoryPoints" Type="FieldControl" Label="Story Points" LabelPosition="Left" />
      <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Triage" Label="Triag&amp;e:" LabelPosition="Left" />
      <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Priority" Label="Priorit&amp;y:" LabelPosition="Left" />
      <Control FieldName="Microsoft.VSTS.Common.StackRank" Type="FieldControl" Label="Stack Rank" LabelPosition="Left" />
   </Column>
. . . 
</FORM>

  4. Import the updated bug definition.

    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/bug.xml

Add the bug work item type to the Requirements Category

  1. Export the categories definition.

    witadmin exportcategories /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/categories.xml

    Verify the metastate mappings in the process configuration

    1. Export the common process configuration definition.

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

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

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

  </RequirementWorkItems>

      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".

    3. Import the common process configuration.

      witadmin importcommonprocessconfiguration /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/CommonConfiguration.xml"

  2. Add the bug work item type to the Requirements Category.

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

  3. Import the categories file.

    witadmin importcategories /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/categories.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.

    Updated panel with bug work item type added

Customize the Kanban board to map Bug states to swim lanes

  1. 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.

    Error message indicates need to customize columns

  2. Open Customize Columns and map the bug workflow states for each column you have defined.

    For example, map each column as shown:

    Map Bug workflow states for each column

Q & A

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

A: A: The task board only shows tasks linked to backlog items that have been assigned to an iteration. 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 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.

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.

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 work item types 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 CommonConfiguration definition file.