Rename Category for TFS 2013 Agile Portfolio Management

We have come from originally a TFS 2008 CMMI Work Item Template and have upgrade through 2010 and 2012. When we upgraded to TFS 2013 we were keen to use the Agile Portfolio Management features. After enabling it we ended up with the categories Features and Requirements. These categories names we find are often use interchangeably so having them mean distinctly different  things was confusing.

Agile Portfolio Management Categories

By default if you are the Scrum template you get something far less confusing, Features and Backlog items. Initiatives can be added following Agile Portfolio Management: Using TFS to support backlogs across multiple teams guide.

Scrum Template Categories

So when it came to use agile portfolio management the hierarchy is was not clear. Fortunately this is easily fixed. I assume the TFS Team did not what to end up with another area like Team Projects that is not able to be renamed. To begin open the Developer Command Prompt which has the paths configured for witadmin.
Developer Command Prompt for VS2013

The examples I have done below have been done on the Visual Studio 2013 ALM Virtual Machine provided by Brian Keller. I recommend anyone who is a TFS Admin have the appropriate Visual Studio ALM Virtual Machines for testing changes on. Especially if you are managing a small team since you are unlikely to have a staging environment and setting one up is too much work. Consider these staging and test environments. With the error I got below no one was effected while I worked out the solution.

Renaming Categories

  1. Export the process configuration definition to an xml file: 
    witadmin exportprocessconfig /collection:http://vsalm:8080/tfs/FabrikamFiberCollection /p:FabrikamFiber /f:%userprofile%\desktop\ProcessConfiguration.xml 
  2. Modify the export xml setting the name to something more appropriate:

    <!-- Feature to Saga -->
    <PortfolioBacklog category="Microsoft.FeatureCategory" pluralName="Features" singularName="Feature">
    <PortfolioBacklog category="Microsoft.FeatureCategory" pluralName="Sagas" singularName="Saga">
    <!-- Backlog Item to Journey -->
    <RequirementBacklog category="Microsoft.RequirementCategory" parent="Microsoft.FeatureCategory" pluralName="Backlog items" singularName="Product Backlog Item">
    <RequirementBacklog category="Microsoft.RequirementCategory" parent="Microsoft.FeatureCategory" pluralName="Journeys" singularName="Journey">
    <!-- Task to Quest -->
    <TaskBacklog category="Microsoft.TaskCategory" parent="Microsoft.RequirementCategory" pluralName="Tasks" singularName="Task">
    <TaskBacklog category="Microsoft.TaskCategory" parent="Microsoft.RequirementCategory" pluralName="Quests" singularName="Quest">
  3. Import the process configuration definition file: 
    witadmin importprocessconfig /collection:http://vsalm:8080/tfs/FabrikamFiberCollection /p:FabrikamFiber /f:%userprofile%\desktop\ProcessConfiguration.xml 

Refreshing the browser after renaming the categories, my URL is wrong since the category no longer exists but I get this very good message:

Most comforting error message ever.

After messing with the process configuration and then getting an error message containing the line, “Don’t worry, the system is not broken”, is very comforting.

Renaming Work Item Types

This is appears easy with just one command.

Rename Feature to Saga:

witadmin renamewitd /collection:http://vsalm:8080/tfs/FabrikamFiberCollection /p:FabrikamFiber /n:Feature /new:Saga

A confirmation prompt appears:

Are you sure you want to rename the work item type Task to the new name of Quest? (Yes/No)

Rename Task to Quest:

witadmin renamewitd /collection:http://vsalm:8080/tfs/FabrikamFiberCollection /p:FabrikamFiber /n:Task /new:Quest

However after doing this you may get this nasty error message when viewing the backlog essentially telling you this time your system is broken and not really useful information on how to fix it:

Broken Configuration Error message

If you export and then import the process configuration definition it will tell you a reason why this could be.


Correcting this color reference in the xml as such however gives you this error.

<!-- Update Task to Quest for the new work item type name -->
<WorkItemColor primary="FFF2CB1D" secondary="FFF6F5D2" name="Task" />
<WorkItemColor primary="FFF2CB1D" secondary="FFF6F5D2" name="Quest" />


Regardless neither of them are the error. This issue is an application pool recycle of TFS is required. After the application pool recycle, the backlog will be working again.

Now you can upload your modified process configuration definition correcting the work item colors.


Now I have a much more interesting hierarchy:

Final Hierarchy


Technorati Tags:

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s