January 4, 2013 
Recently I was at a customer who used the MSF for Agile Software Development template in Team Foundation Server 2012. As he was doing Scrum with this template he had the need to show Bugs in the Product Backlog view as well. Just like User Stories he wanted to plan bugs in a specific sprint.
Seems logical but Bugs did not show in the Product Backlog view.
When I checked a little bit further, it seems that the MSF for CMMI template only shows [Requirement] work items and the Scrum template showed [Product Backlog Item] and [Bug] Work items.
The most obvious option was to press the [Create Backlog Query] button on the Product Backlog, but that only gave the possibility to save the underlying query in the Team Project.
Because I could only find some forum answers I decided to create a blog post on how to modify the Product Backlog view in the TFS 2012 Web Access Client. It is somewhat more complicated than one would expect.
Work Item Types and Categories
Before I start my explanation on how to modify the Product Backlog, I want to explain a little bit about the underlying concepts.
Since TFS 2010 there is the notion of Work Item Categories. A Work Item category is a functional grouping mechanism to group Work Item Types. In TFS 2012 this concept is expanded and we know the following categories
- Bug category
- This contains work item types that are considered a Bug. When you use Test Manager it creates the Work Item Type that is the default of this category.
- Code Review Request / Response Category
- This contains work item types that are considered as the ones to use when performing Code Reviews. When you submit a Code Review Request in VS 2012, the default work item type for this category is created.
- Feedback Request / Response Category
- This contains work item types that are considered as the ones to use when using the Feedback tools in VS 2012. When you submit a Feedback Request in VS 2012, the default work item type for this category is created.
- Hidden Category
- This contains all work item types that are used in the backend but will not be displayed in the Web Access Client and cannot be created when choosing [New]. For example [Code Review Request], [Shared Step] or [Feedback Response]
- Requirement Category
- This contains all work item types that are considered as a requirement. In Scrum this is the [Product Backlog Item] and in CMMI this is the [Requirement].
- Shared Step Category
- This contains the work item type that is considered to be a Shared Step
- Task Category
- This contains the work item types that are considered to be a task. When you click the [+] sign in the Web Access Client on a Requirement or PBI, the default Work Item Type in this category in created
- Test Case Category
- This contains the work item types that are considered to be a Test Case. When using Test Manager and adding new Tests, the default work item type in this category will be used.
To edit categories you must use the witadmin tool to export and import the category definitions (http://msdn.microsoft.com/en-us/library/vstudio/dd273721.aspx)
The categories XML looks a bit like this
As you can see, a category can contain multiple work item types, and always 1 default type.
A category requires some fields to be present on a work item type. For example, the [System Information] field and the [Steps to Reproduce] field are required for any work item in the [Bug Category]
More about categories you can find on MSDN: http://msdn.microsoft.com/en-us/library/vstudio/dd695775.aspx
Changing the backlog
Now we know a bit more about categories, we can dive into the Product backlog. As I mentioned at the start of this post, the button [Create Backlog Query] only gives you the possibility to save the backlog query but not modify the query that is used for the backlog. Still, this is very useful information, because it provides us with valuable information about the data that is used in the Product Backlog.
As we can see in the query for the Agile Template, the product backlog shows us all Work Items from the Requirements category in the states New, Active and Resolved.
We need to perform several steps
- Change the categories for this Project so that the Requirement category also contains Bugs
- Change the Bug Work Item so that it contains all the required fields of the Requirement category
- Change the Agile Process Configuration to change the output columns and the “Add Panel”
- Look at the different states that are used in the query
I will work out an example where we are going to change the Product Backlog of an MSF Agile project so that it shows User Stories and Bugs and show the Area Path in the output columns.
Change the categories
Export the categories of the Agile Project by using the following command
1: witadmin exportcategories /collection:http://<server>:8080/tfs/DefaultCollection /p:"<ProjectName>" /f:"FileName.xml"
Change the Requirement Category element so that it includes [Bug]
Import the categories of the Agile Project by using the following command
1: witadmin importcategories /collection:http://<server>:8080/tfs/DefaultCollection /p:"<ProjectName>" /f:"FileName.xml"
Change the Bug Work Item so that it contains all the required fields of the Requirement category
When you now open the Web Access Client it shows you an error
TF400917: The current configuration is not valid for this feature. This feature cannot be used until you correct the configuration.
This means that there is something wrong with the configuration. The categories configuration however is fine. The error is located within the [Bug] Work Item. This item does not contain the fields that are necessary for the Requirements field. Add the Story Points field (exactly the same as the one on User Story) to the [Bug] Work Item.
Change the Agile Process Configuration to change the output columns and the “Add Panel”
To change the output columns in the product Backlog, open a command window and run the following command
1: witadmin exportagileprocessconfig /collection:http://<server>:8080/tfs/DefaultCollection /p:"<ProjectName>" /f:"FileName.xml"
Open the XML and change the following element
Run the following command to import the changes back into TFS
1: witadmin importagileprocessconfig /collection:http://<server>:8080/tfs/DefaultCollection /p:"<ProjectName>" /f:"FileName.xml"
This results in an adjusted “Add Panel” and adjusted output columns
Look at the different states that are used in the query
The states that are used in the query, are extracted from the meta states that are defined for the project.
Run the following command
1: witadmin exportcommonprocessconfig /collection:http://<server>:8080/tfs/DefaultCollection /p:"<ProjectName>" /f:"FileName.xml"
This file contains information about the meta states that are used.
When you follow these steps, you can modify how your Product Backlog looks and works !
Hope this helps !
The Road to ALM 
But can I also change the actual query? I don’t want to see work items with State=New from sub-iterations in my Product Backlog. I only want to see those that are not yet assigned to iterations.
No you cannot change the query. The query that you see is actually built from logic within the system. So it shows all work items in the Requirements category and from the Meta States To Do and In Progress
I modified the Product Backlog with export/import commonprocessconfig but the new columns do not allow me to set the WIP limits. Did I miss something?
You can set wip limits on the kanban board. This is another view that cannot (is coming in update 2) be customized. The view is only available in tfs 2012 update 1 and higher.
I can set the WIP limits on the standard columns but when I added the new one I cannot set the WIP limits – they don’t show at all. Figured I missed something. I did set it to an “InProgress” column.
Hi,
The kanban board is shown on the Product Backlog page. This board does not use the meta states but the “real” states of the Product Backlog Item. Take a look at this post how it works!
http://blogs.msdn.com/b/bharry/archive/2012/08/13/introducing-kanban.aspx
Hi,
I am trying to add a custom WI to the Product Backlog page. VS 2012 TFS 2012 AGILE 6.2. I have been having all kinds of trouble so I thought I would try something simple.
1) Start with just the default product backlog containing just “User Story”
2) Export User Story work item and make a copy to “My Work Item.xml”. Edit the xml file and the only change I make is
3) Save and import and verify work item functions.
4) Edit categories to look like:
5) Get well known TF400917 error
I’m missing some data in your answer. Point 1 and 2 probably contain a image. Can you provide that again please?
Thanks!
No, no image, however I do have an update.
Steps 1 & 2 were outlining the steps I used to create a work item called “Work Set” which was a copy of the default “User Story” work item with only the name changed.
For full disclosure had been making changes to the catalog, process definition files before doing steps 1 and 2, but even with the changes I had made the User Story still correctly showed in the back log but my new Work Set work item generated the error when added ot the backlog.
After making my original post I got frustrated and went back to square one with default configurations restored. I then repeated steps 1 and 2 and this time my new work item, “Work Set” appeared just as I expected it to.
I guess now my questions turns to one of how to debug problems in the configuration. Backing out to square one doesn’t seem to be very efficient. Is there some log somewhere that can be viewed or some other tool for validating configurations?
You can use the witadmin importwitd /validate but this only validates the work item definition. Take a look at this great post to read something about logging in TFS http://blogs.msdn.com/b/granth/archive/2013/02/13/tfs2012-new-tools-for-tfs-administrators.aspx
Also the event log contains some useful information now and then 😉
Good luck !
When you say, “Open the XML and change the following element”, what specifically are you changing? Please specify.
The xml that was the result of the line above. Exportagileprocessconfig had an argument /f:filename.xml. This is the one you should open
Hello, have you ever experienced a case where you export the agile config, make the changes, import the config back but no changes were applied? When I export the config again I see all my changes but the additional columns are not visible on the web. It’s driving me insane.
The agile config is the only one giving me trouble. I have successfully made change to the categories.xml and the commonprocessconfig.xml.
If you are on TFS 2013 , the agileprocess config is replaced with processconfig. If not, have you tried to reset IIS or delete the tfs cache?
Hello Rene,
Thank you for this post. I’m using it 3 years later and face same problem.
I have resolved it following your guideline.
Though I have one question. Have you notice that the bug that are now appear on the backlog, if their iteration is set to the current one, they just disappear from the backlog list.
Did you experience this?
In 2012 ? I cannot remember :). Currently you can choose to show the “in progress ” items or not. Thanks for your comment !
We can change it in TFS 2015? or in 2012?
Sorry I’m still maintaining an old server that is still running 2012.
It seems that it only display the “proposed” work item and not the “in Progress”. Strangely is that if I create a new bug, which see his state become “Active” and not “New” (this is linked to the Agile template provided by MS) the Backlog is showing this but, but if I change the iteration path it just disappears. Like he is now seing this bug as in “in Progress”
how can we change in TFS 2012 which state we want the Backlog to display?
Top of mind you can Change it in the process configuration xml and /or cAtegories. XML which you can export with witadmin