Upgrading Team Projects After Migrating From TFS 2008 to TFS 2012

UPDATE: The content of this post was originally a gap in the on-line MSDN documentation which has since been filled.  The official MSDN documentation can now be found here.

I recently worked with a customer that was upgrading from Team Foundation Server (TFS) 2008 to TFS 2012.  After the upgrade, all of the existing Team Projects were available within the new project collection as expected.  However, one thing the upgrade process doesn't do for you is upgrade the team projects themselves.  That means that the Team Projects were still operating off of the MSF for Agile Software Development 4.2 process template rather than the new 6.0 version of the same template.  Since the customer wanted to take advantage of all the new functionality and work item types added since 2008, we needed to upgrade each of their existing Team Projects to add these features.

While there is documentation on TechNet for Adding Features Using a Manual Update Process, this focuses on upgrading from TFS 2010 to TFS 2012.  That didn't quite fit the bill for our scenario since there were a great deal of changes between TFS 2008 and TFS 2010 that weren’t accounted for.  I also found documentation on MSDN regarding Enabling Interfacing with Microsoft Test Manager for Upgraded Team Projects.  Since the customer was interested in using MTM, that sounded promising, but this guidance focused on an upgrade from TFS 2008 to TFS 2010.  So I had information for upgrading from 2008 to 2010 and from 2010 to 2012, but nothing to go directly from 2008 to 2012.  So we took the approach of combining the two separate pieces of guidance into one concise approach as outlined below.

1. First we need to export the MSF for Agile Software Development 6.0 Process Template as parts of this will be used in subsequent steps.

2. Using witadmin.exe, import the following work item type definitions from the 6.0 template into each of your team projects that need upgraded.

   1. UserStory
   2. TestCase- This required slight modification to the following system field names to remove spaces that were added since 2008 but that still exist based on the 2008 template.
      1. External Link Count --> ExternalLinkCount
      2. Related Link Count --> RelatedLinkCount
      3. HyperLink Count --> HyperLinkCount
      4. Attached File Count --> AttachedFilecount
      5. Area ID --> AreaID
   3. SharedStep- This required slight modification to the following system field names to remove spaces that were added since 2008 but that still exist based on the 2008 template
      1. Iteration ID --> IterationID
      2. External Link count --> ExternalLinkCount
      3. Related Link Count --> RelatedLinkCount
      4. HyperLink Count --> HyperLinkCount
      5. Attached File Count --> AttachedFilecount
      6. Area ID --> AreaID
   4. Task - Required because there are necessary fields (StartWork, StopWork) missing in the 4.2 version

3. Using witadmin.exe, import the following Linked Types - NOTE: This is a one time operation for the Team Project Collection and does not need to be run for each Team Project.

   1. TestedBy
   2. SharedStep

4. Using witadmin.exe, import categories for each Team Project being upgraded.

   1. We first had to comment out references to all new 6.0 WITs (e.g. Code Review Request/Response) since they do not yet exist.  These will be updated during the Configure operation in Step #5.

5. Run Configure from the Admin site for each Team Project

   1. 1. After performing the above steps for a given Team Project you then need to navigate to the Admin site for the project.  You can do this by clicking Web Access for the Team Project from Team Explorer as shown.

    

   1. 1. Then click on the Administrative icon in the upper right corner of the page.
      2. From the Administrative page you should see an option similar to the following indicating that you have features for this Team Project that are not configured.  Click the Configure Features link.

   

   1. 1. This should result in a dialog similar to the following indicating the process template that your Team Project will be upgraded to.

   

   1. Click on the Configure button and the Team Project should be upgraded to the new process template.

6. Finally, we need to copy the new Work Item Queries to each Team Project. 

   1. Create a test project based on the MSF for Agile Software Development 6.0 Process Template to copy the Work Item Queries from.
   2. Use WiqAdmin to copy updated queries from the test project to the migrated projects
      1. NOTE: WiqAdmin currently only supports Team Explorer 2008/2010.  The 2010 version must be run from a machine with TE 2010 installed to bind to the correct assemblies.
      2. Syntax for the copy operation should be similar to the following to copy all queries recursively without overwriting any existing queries:
         1. wiqadmin copy /collectionFrom:<collectionUrl> /collectionTo:<collectionUrl>
            /projectFrom:<test project> /projectTo:<migrate project>
            /ondup:S /folder:"Shared Queries" /recursive 
         2. Replace the collectionUrl and project name parameters above for your environment

Since we had to perform the above operation for multiple team projects (upwards of 50) we tried to automate the process as much as possible to creating some simple command line files to accommodate this.

NOTE: The above outline is specific to the MSF for Agile Software Development process template but should be similar for other process templates.

The command files and the updated process template files required for the steps listed above are included in the zip file below for reference.

Upgrade Scripts and Modified WIT Files

Comments

• Anonymous
  February 06, 2013
  FYI... We were able to take Ewald Hoffman's code over at blogs.msdn.com/.../10303404.aspx to automate step 5. That saved some additional time in upgraded a few dozen Team Projects. Thanks for sharing. Matt

• Anonymous
  February 15, 2013
  Regarding step 6.b, you can run Wiqadmin.exe on the new TFS 2012 server; you just need to install the TFS 2010 Object Model (no need for Team Explorer 2010). The TFS 2010 object model can be installed side-by-side with TFS 2012.

• Anonymous
  February 23, 2013
  In step 6.b,  i have the object model installed. I have the WIQAdmin tool.  running the command, but i get Unknown MODE parameter. The error is caused by «Recursive, ReturnMatchingChildren». Operation failed. I don't know what is potentially 'breaking' by not finishing on the recursion piece.  Wondering if there is something I'm missing?