February 12th, 2013

Add bugs to the task board or backlog pages

Kathryn Elliott
Kathryn Elliott

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

This post shows you how to add bugs to either the task board or the product backlog.

You can add bugs or other work item types to appear in either the task board or the product backlog, but not both.

NOTE: With the witadmin command line tool, you import and export definition files as shown in this post. You can also use the Process Editor GUI tool, available with the download of TFS Power Tools, or TFS Team Project Manager, a community resource project available on codeplex.

The steps provided in this post describe how to make changes to a 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 they do not, additional definitions must be made as described here.

Track bugs as tasks

To track bugs as tasks, you add required fields to the bug work item type, and you add the bug work item type to the Task Category.  Here’s how you do that 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.0Common7IDE

On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%. You can download Team Explorer for free.

  1. Export the bug work item type definition.

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

  1. Add the Activity and Stack Rank fields. If you don’t, the configuration won’t be valid. Optionally, add the scheduling fields that your team uses. 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>

You can also manage the items in the Activity field using a global list.
(For a team project based on MSF for CMMI, you would add the Discipline and Stack Rank fields.)

NOTE: The backlog and board pages use the Stack Rank field to manage the sort order of work items. This field must match the field assigned to the Order type in the CommonConfiguration definition file. To download this file, use witadmin exportcommonprocessconfig.

  1. Add 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 Type=”FieldControl” FieldName=”Microsoft.VSTS.Common.Rank” Label=”Ran&amp;k:” LabelPosition=”Left” NumberFormat=”WholeNumbers” MaxLength=”10″ />
         <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>

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

  1. 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.  It just can’t belong to both the Task Category and the Requirements Category.

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

  1. Open the task board page, or refresh the page if it is already open.
  2. You should be able to select either task or bug as a linked work item to a user story.

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

NOTE: You can’t add bugs through the Implementation tab because that tab is restricted to user stories and 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. For example, include the <Filter WorkItemType=”Bug” /> syntax as highlighted below. 

  <Tab Label=”Implementation”>
                <Control Type=”LinksControl” Name=”Hierarchy”>
                  <LinksControlOptions>
                    <WorkItemLinkFilters FilterType=”include”>
                      <Filter LinkType=”System.LinkTypes.Hierarchy” />
                    </WorkItemLinkFilters>
                    <WorkItemTypeFilters FilterType=”include”>
                      <Filter WorkItemType=”User Story” />
                      <Filter WorkItemType=”Task” />
                      <Filter WorkItemType=”Bug” />
                    </WorkItemTypeFilters>
                    <ExternalLinkFilters FilterType=”excludeAll” />
                    <LinkColumns>
                      <LinkColumn RefName=”System.ID” />
                      <LinkColumn RefName=”System.WorkItemType” />
                      <LinkColumn RefName=”System.Title” />
                      <LinkColumn RefName=”System.AssignedTo” />
                      <LinkColumn RefName=”System.State” />
                      <LinkColumn LinkAttribute=”System.Links.Comment” />
                    </LinkColumns>
                  </LinksControlOptions>
                </Control>
              </Tab>

 

 

Track bugs as backlog items

Work item types that you add to the Requirements Category show up on the backlog pages. For the configuration to be valid, you must first add the estimate and backlog sort order fields to the bug work item type.

Add required fields 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

  1. Add the estimate and backlog sort order fields. For Agile, these correspond to Story Points and Stack Rank.

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

  . . .
</FIELDS>

For a team project based on MSF for CMMI, you would add the Size and Stack Rank fields.

 

NOTE: The backlog and board pages use the Stack Rank field to manage the sort order of work items. This field must match the field assigned to the Order type in the CommonConfiguration definition file. To download this file, use witadmin exportcommonprocessconfig.

  1. Add the Story Points and Stack Rank fields to the work item form.

<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 Type=”FieldControl” FieldName=”Microsoft.VSTS.Common.Rank” Label=”Ran&amp;k:” LabelPosition=”Left” NumberFormat=”WholeNumbers” MaxLength=”10″ />
</Column>

. . .
</FORM>

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

  1. Add bug to the Requirements Category.

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

NOTE: It’s OK for the bug work item type to belong to two categories—the Bug Category and the Requirements Category.  It just can’t belong to both the Task Category and the Requirements Category.

 

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

  1. Open the product backlog page, or refresh the page if it is already open.
  2. You should be able to select either task or bug as a linked work item to a user story.

 

Learn more about …

 

 

 

Category
AgileDevOps

0 comments

Discussion are closed.

Read next