Add bugs to the task board or backlog pages

Add bugs to the task board or backlog pages

Rate This
  • Comments 23

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.0\Common7\IDE

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

 

 


 

Leave a Comment
  • Please add 5 and 6 and type the answer here:
  • Post
  • After adding the Bug type to the Task Category, I notice that when I go to the Sprint Backlog and click the plus to add a child to a User Story, it shows a loading icon, and never finishes.  I can only add children by right-clicking on the user story.  Is this a known issue?

  • Our team is using the Scrum template.  Would you have any advice on accomplishing the same as above on that template?  For instance, several fields that you show already in the WIT are not present, and as well I get an error 'The form uses undefined field 'Microsoft.VSTS.Common.Rank'.

    Any "bug as a task" love for the Scrummers?

  • Ryan - the loading icon should resolve after a few seconds and create a User Story.

  • Kathryn - I am referring to the plus symbol on an existing user story, which normally opens the form for a new Task, but in this case, should offer a choice of Task or Bug.  That's where it freezes the item up.

  • Ryan - I have never heard of that behavior before. Do you have a consistent repro? I would love to work with you to get the bug fixed.

  • KathrynE

    I speak of the ability to have a bug represented as a child of Product Backlog Item.  The PBI edit form (and task board) currently do not allow me to create bugs, only tasks.  I *can* create bugs elsewhere, and add them to the sprint and thus the taskboard as a row and then add tasks to that.  What we would like to do is open a PBI (or press the plus icon on the task board for a PBI) and have the option of creating and linking a bug with the hour tracking fields similar to how they are represented above.

    Additionally, the link you replied with is broken.  

  • Sorry for the broken link. This topic, Customize Work Item Tracking and Your Team Project (msdn.microsoft.com/.../jj190744.aspx), contains information about customizing the agile planning tool pages.

    Your Scrum project (if created using Scrum 2.0 or later) should have the bug work item type added to the Requirements Category and therefore you should be able to add it from the product backlog page as a backlog item.

    However, if you want to add the Bug as a child to a PBI and have it show up on the task board, then you need to take these steps:

    1. Add the following to the Bug work item type definition:

    a. Activity field

    b. Remaining Work field

    2. Remove the Bug work item type from the Requirements Category and add it to the Task Category (category definition file).

    3. Either swap out the workflow section defined for the Bug wit with that defined for Task:

    a. Task states are To Do, In Progress, and Done.

    b. Bug states are New, Approved, Committed, and Done.

    OR   Add mappings for the Bug metastates in the CommonConfiguration file:

     <TaskWorkItems category="Microsoft.TaskCategory">

       <States>      

           <State value="New" type="Proposed" />      

           <State value="To Do" type="Proposed" />

           <State value="Approved" type="Proposed" />

          <State value="In Progress" type="InProgress" />

         <State value="Committed" type="InProgress" />

         <State value="Done" type="Complete" />

       </States>

     </TaskWorkItems>

    You will need to export and then import the CommonConfiguration file using the witadmin exportcommonprocessconfig and witadmin importcommonprocessconfig.

    Hope this helps.

  • Ewald - I can most certainly reproduce.  Feel free to contact me!

  • And here I am logged in, so you actually can contact me!  :)

  • @Ryan: shoot, I am not receiving notifications on posted comments. You can contact me at ewald_dot_hofman_at_microsoft_dot_com.

    I would love to hear what your repro is.

  • Once I managed to include the bugs in my task board, I had the following issues:

    - Bugs are created as active. If I want to use them as tasks in my board, I can't track a transition state from new to active (when someone started working in it) as I do with regular tasks. If I create the 'new' state for bugs in the process editor, the board will stop working and TFS will show an error message.

    - Bugs have the 'resolved' state, which is not tracked on the board. What happens is that once bugs are resolved, they disappear from the board until they are closed.

    Any suggestions on how to work around those issues (if that is possible)?

  • Bernardo - The workflow states and metastate mappings must be in sync for the Bug.  IF you change the workflow states, then you must change the metastate mappings in the commonConfiguration file.

  • I'm having an issue trying to get bugs to appear in the backlog.

    Our project is using the CMMI Process template, and we are running TFS 2012 Update 1. We've made no modifications up to this point.

    I added the Discipline field to the bug workitem definition. StackRank was already in the field list so didnt need to modify it. I then added both these fields to the form layout and imported the changes. In visual studio, bugs showed the new fields as expected.

    The issue comes when trying to modify the categories. I added the bug workitemtype to the requirementcategory like so:

    <CATEGORY refname="Microsoft.RequirementCategory" name="Requirement Category">

     <DEFAULTWORKITEMTYPE name="Requirement" />

     <WORKITEMTYPE name="Bug" />

    </CATEGORY>

    But after importing this change to the categories. The backlog page in the web portal shows the following error:

    TF400917: The current configuration is not valid for this feature. This feature cannot be used until you correct the configuration.

    I didnt make any modifications to the CommonConfiguration.xml because StackRank was already set for the Order type.

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

    Am I missing something else here?

  • Fixed my issue above!

    I got the backlog to show bugs after adding the Size field (Microsoft.VSTS.Scheduling.Size) to the bug item definition. Was suggested here - social.msdn.microsoft.com/.../5d760572-8682-4970-baa3-d102992b395b

    Hope this helps.

  • Is there anyway to get the WIT ID to show on the cards in the task board?

Page 1 of 2 (23 items) 12