TFS 2010: Changing Template for an Upgraded Team Project

The situation is fairly common, you have been using TFS 2008 for ALM in your work environment for a while, but suddenly, you have access to the latest version: TFS 2010, and wonder how cool could be make use of all the new features included in this new major version (like collections, work item hierarchies and finally a better integration with MS Project). You followed the Upgrade Guide (kindly provided by the TFS Rangers) and after some work you finally have your precious Team Projects safe in their new 2010 home. Clean and straightforward upgrade, wasn’t it?

Opps, wait a minute!, why I do not have access to those new cool dashboards, and reports from my upgraded project portals? Ok, let’s take a look at those functional testing capabilities I’ve been waiting for a long time.. opps.. The new MS Test Manager cannot connect to my upgraded projects!! The reason for all this and many other symptoms: the upgrade process did not upgrade the definition of your Team Projects.

You ended up with the same Work Items, Reports, etc. that you had in TFS 2008. No way!!

Steps to enable new features in upgraded team projects, or adding the missing dashboards are scattered through the blogosphere and the MSDN web site.

Based on my own experience, basically you have two options here:

  1. Branch the code from each upgraded project to a brand new Team Project in TFS 2010. Remove permissions to the upgraded project. This way you could have your source code history accessible from the new Team Project. Obviously, you will have trouble if you accidentally delete your old upgraded project from TFS. If you could live without your history then simply move the latest version to the new Team Project. This is very easy, and it is a valid option, but you will probably have this uneasy feeling that it could be done in a more elegant way (see option 2).
  2. Rebuild the entire definition of your Team Project to the latest ones included in TFS 2010!! This could sound a little drastic and unfortunately you will not easily find a comprehensive guide in the Web on how to accomplish this. That is exactly the goal of this article.

Guide to Rebuilding your Team Project Template

Note: this guide is based on the assumption that you can delete all the preexisting Work Items created in your upgraded projects.  If you know how to overcome this limitation just let me know.

  1. Log in your TFS 2010 server or a desktop machine with Team Explorer 2010 installed. You must be Project Collection Administrator to execute the following steps.
  2. Download the latest CMMI and Agile Templates from your TFS 2010.  Open the Team Explorer 2010 (or VS 2010) as an Administrator. Right-click on the Collection..Team project Collection Settings..Process Template Manager…and download both templates to a folder in your disk. We will use the path C:MSF for CMMI Process Improvement v5.0 in the following steps.
  3. Take a full back of your TFS 2010 server. Use the TFS Backup Power Tool for this.
  4. Open a command line prompt and change dir to C:<Program Files>Microsoft Visual Studio 10.0Common7IDE. You will need to execute the following steps for each one of the upgraded projects. In this case I will use a Collection named “Migrated”, and a Team Project called “TemplateChgTest”:

4.1 – Open Notepad and create a XML file called “ImCategories.xml” with the following content:

<?xml version="1.0" encoding="utf-8"?> 
<cat:CATEGORIES xmlns:cat=""> 

4.2 – Clean-up the current category list for the project. This would allow us to delete all the Work Item definitions. Import the empty Category list (ImCategories.xml) for the TemplateChgTest project.

witadmin.exe exportcategories /collection:http://localhost:8080/tfs/Migrated /p:TemplateChgTest /f:"C:TFSUpgradeImCategories.xml"

4.3 – Delete each one of the Work Item definitions of the team project. You can get a list of the current definitions through the Team Explorer, or using the witadmin listwitd command.

witadmin destroywitd /collection:http://localhost:8080/tfs/Migrated /p:TemplateChgTest /n:[Wort Item Name]

4.4 – Import the new definitions from the template downloaded in step 2. Do this for each one of the Work Item definitions in the new template.

witadmin importwitd /collection:http://localhost:8080/tfs/Migrated /p:TemplateChgTest /f:"C:MSF for CMMI Process Improvement v5.0WorkItem TrackingTypeDefinitionsBug.xml"

4.5 – Import the new Category list from the downloaded template.

witadmin.exe importcategories /collection:http://localhost:8080/tfs/Migrated /p:TemplateChgTest /f:"C:MSF for CMMI Process Improvement v5.0WorkItem Trackingcategories.xml”

4.6 – At his point you should be able to connect to your upgraded projects from MS Test Manager. You can also check your new definitions from Team Explorer (remember to refresh your projects or restart VS).

5 – Let’s rebuild the project portal and the new dashboards and reports. Details of this process are further explained here, but  in summary you will need to do this:

5.1 – In case you want your portal in the same path, backup your upgraded content and delete the portal. Open the WSS-based project portal and delete it (Site Actions…Site Settings…Site Administration…Delete this site).

5.2 – Delete your upgraded SSRS reports. Find the SSRS Server URL in the TFS Admin Console applet (under the Reporting node). Open the SSRS Report Manager in your browser and delete the reports folder for the upgraded team project.

5.3 – Manually copy the Queries from a new Project using the same template. Just copy and paste the queries in the Team Explorer tree view.

5.4 – Create the following XML file in notepad (C:TFSUpgradeAddDashboards.xml):

<?xml version="1.0" encoding="utf-8"?> 
<Project xmlns="ProjectCreationSettingsFileSchema.xsd"> 
<ProcessTemplateName>MSF for CMMI Process Improvement v5.0</ProcessTemplateName>

Configure the parameter based on your environment. Remember that you can get the ProjectSiteWebApplication parameter from the TFS Admin Console (Under the Name column in the SharePoint Web Applications node.

5.5 Execute the rebuild process. For this, open the Command Window in VS2010 and enter the following command:

File.BatchNewTeamProject C:TFSUpgradeAddDashboards.xml

Wait for the completion of the command, and the check the generated log file for exceptions. This must contain a line to consider the process as successfully completed:

2011-04-12T15:36:08 | Module: BatchTeamProjectCreator | Thread: 1 | Team Project Batch Creation succeeded.

6 – Finnish! You are ready to go. Check the new portal, Excel and SSRS reports.


  • Keep in mind that these steps will also work if you need to change the definition of your Team Project from CMMI to Agile or vice versa.
  • You will need minor changes if you are using your own template.

Enjoy, please let me know any comments!


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 )

Google+ photo

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

Connecting to %s