Add bugs to the task board or backlog

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 the Agile and CMMI process templates that TFS 2013 provides. The state model for the work item types 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.

If you are making changes to process templates provided with TFS 2012, view the Visual Studio 2012 version of this topic.

Note Note

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.

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 12.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:"CollectionURL" /p:MyProject  /n:bug /f: "DirectoryPath/bug.xml"
    

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

  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="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. 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>
    
  6. Import the updated bug definition.

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

Add the bug work item type to the Task Category

  1. Export the categories definition.

    witadmin exportcategories /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.xml"
    
  2. Add bug to the Task Category.

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

    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:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.xml"
    

Add metastate mapping to the process configuration

  1. Export the process configuration definition.

    witadmin exportprocessconfig /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/ProcessConfiguration.xml"
    
  2. 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".

  3. Import the process configuration.

    witadmin importprocessconfig /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/ProcessConfiguration.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 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.

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 that’s 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:" CollectionURL" /p:MyProject /n:bug /f:DirectoryPath/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 Size.

    <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>
    
  3. 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>
    
  4. Import the updated bug definition.

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

Add the bug work item type to the Requirements Category

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

    witadmin exportcategories /collection:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.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:"CollectionURL" /p:MyProject /f:"DirectoryPath/categories.xml"
    

Verify the metastate mappings in the process configuration

  1. Export the process configuration definition.

    witadmin exportprocessconfig /collection:"CollectionURL" /p:MyProject /f: "DirectoryPath/ProcessConfiguration.xml"
    
  2. 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".

  3. Import the process configuration.

    witadmin importprocessconfiguration /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.

    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

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:

  1. Edit the Bug work item definition: Add the Activity and Remaining Work fields to the FIELDS and FORM sections.

  2. Edit the Categories definition: Add Bug to the Task Category and remove it from the Requirements Category.

  3. Edit the process configuration definition: Map the Resolved state for the Task Category and remove it from the Requirements Category.

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

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.

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 ProcessConfiguration definition file.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft