How to upgrade TFS2008 Conchango projects to TFS2012 Microsoft Visual Studio Scrum

I recently finished up a huge Team Foundation Server migration and Scrum training project for a well-known, global accounting firm.  They were running Team Foundation Server 2008 (TFS2008) and wanted to upgrade to Team Foundation Server 2012 Update 3 (TFS2012.3).  They had approximately 175 Team Projects and about 100 of those projects were using the Conchango Scrum Process Template (aka. Scrum for Team System).  For those 100 Scrum projects, they wanted to be able to use the new Scrum planning tools that comes with the Microsoft Visual Studio Scrum 2.2 process template and also to get as close as possible to an out-of-the-box TFS Process Template. 

This migration had some pieces of complexity that would make an in-place upgrade fairly difficult. 

1. TFS2008 was running on a 32-bit operating system. 
2. TFS2012 needs a 64-bit operating system.
3. TFS2012 needs a different version of SQL Server than TFS2008.
4. TFS2012 needs a different version of SharePoint than TFS2008.
5. Any team project that uses Conchango is going to break because Conchango’s service doesn’t work under Team Foundation Server 2012. 

This blog post will outline the rough steps for doing the upgrade and migration from TFS2008 Conchango to something that is very close to out-of-the-box Microsoft Visual Studio Scrum 2.2. 

Upgrade TFS2008 to TFS2012

Basically, in order to get upgraded to TFS2012, this TFS2008 instance would need to get moved to a completely new server.  Here’s the rough overview of the steps to get the TFS2008 server moved to new hardware and get upgraded to TFS2012:

1. Build a new Windows Server 2008 R2 machine
2. Install Team Foundation Server 2012
3. Backup the SQL Server databases from the TFS2008 database tier and restore them into the SQL Server data tier for TFS2012
4. Backup the SQL Server Reporting Services encryption key
5. Restore the SharePoint content databases
6. Restore SQL Server Reporting Services (SSRS) and its encryption key
7. SSRS is probably broken at this moment with an error that says “Scale Out Deployment Not Supported”.  You’ll need to use “rskeymgmt -l” followed by “rskeymgmt -r {guid}” to remove the old SSRS instance from the configuration database.   (Hint: rskeymgmt.exe is probably in  C:\Program Files (x86)\Microsoft SQL Server\100\Tools\Binn)
8. Run the TFS2012 upgrader that’s part of the TFS2012 installer

Fix the Conchango SharePoint Sites

At this point, TFS2012 should be working and you should have access to your work items, version control repositories, reports, and SharePoint sites.  Unfortunately, the SharePoint site for any Conchango project is going to be showing a lot of errors and have a lot of broken image links.  This is because the supporting files for the Conchango SharePoint sites are missing.  Here are the steps to fix the Conchango SharePoint sites:

1. Log on to the server that’s running SharePoint
2. Download the Conchango MSI installer
3. Open a Command Prompt as an Administrator
4. Using the command prompt window, go to the directory where you downloaded the Conchango installer
5. Type “msiexec /a ConchangoInstaller.msi /qb TARGETDIR=c:\temp\conchango.  You’ll now have a bunch of extracted files from the installer in “c:\temp\conchango”.
6. Copy the contents of the “Web server Extensions/60” folder to “C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14” on the new SharePoint server
7. Find “Conchango.TeamSystem.Scrum.Sharepoint.wsp” in the extracted files directory and “CD” to that directory in the command prompt window
8. Type “stsadm -o addsolution -filename Conchango.TeamSystem.Scrum.Sharepoint.wsp” in order to import the SharePoint solution file
9. Open a browser and go to the SharePoint Central Administration site
10. Click System Settings
11. Click Manage Farm Solutions.  You’re probably now at a URL that is something like http://the-sharepoint-server:17012/_admin/Solutions.aspx.
12. Deploy the SharePoint Solution (WSP) for Conchango

Rename Work Item Fields

Between TFS2008 and TFS2012, there have been some Work Item fields that got renamed.  Before you can start upgrading the Conchango Work Item Types (WITs) to the Microsoft Visual Studio Scrum 2.2 WITs, you need to rename these fields in TFS2012.  This changes the friendly names for these fields on the entire TFS instance and only has to be run once.  Here is the script for that:

witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”System.Id” /name:”Id” /noprompt
witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”System.IterationId” /name:”Iteration ID” /noprompt
witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”System.ExternalLinkCount” /name:”External Link Count” /noprompt
witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”System.RelatedLinkCount” /name:”Related Link Count” /noprompt
witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”System.HyperLinkCount” /name:”Hyperlink Count” /noprompt
witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”System.AttachedFileCount” /name:”Attached File Count” /noprompt
witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”System.AreaId” /name:”Area ID” /noprompt
witadmin changefield /collection:”http://tfs-server:8080/tfs/DefaultCollection” /n:”Microsoft.VSTS.Common.BusinessValue” /name:”Business Value” /noprompt

Upgrade the Conchango Team Projects

You’ll need to run this set of steps for each of your Conchango Team Projects.   When I did this, I had to upgrade 100 team projects each with 10’s of thousands of work items so it made sense to write a utility that would do all the modifications automatically.  My Conchango upgrader tool read a script that described the steps that needed to be run.  That script has 71 steps in it.  Roughly described, here are the steps for upgrading the work item type definitions.

1. Export the current Work Item Type Definitions (WITDs) for the Team Project (TP) using “witadmin exportwitd”. 
2. Using Process Template Manager in Visual Studio 2012, export the Microsoft Visual Studio Scrum process template to your local disk for the machine where you’ll be doing the upgrade/conversion.
3. Make a copy of the current version of the WITDs in case you need to revert back to the original
4. The Conchango “Sprint Backlog Item” WITD is going to be renamed to “Task” as part of this conversion.  You’ll probably want to rename the WITD file for the SBI to be something like “Task.xml” so that you don’t get confused.
5. Edit the WITDs to hide the old Conchango fields and bring display the new fields that are in the MSFT Scrum template.  You’ll probably want to do this for the Product Backlog Item, Task, Impediment, and Bug work items.  I called these the “Final Merged” WITDs.
6. Since there are different work item states and fields between the new and old WITDs, you might want to copy values between fields and change work item states on all your old work items as part of this conversion.  If you’re going to do this, you’ll probably want to create a copy of the Final Merged WITDs where you’ll relax a lot of the validation rules so that you can more easily update the values on your existing TFS work items.  I called this the “Merged During Upgrade” WITDs.  Once I copied the WITDs, I removed the read only flags related to work item states, removed the restrictions on the System.ClosedDate field, and changed the Conchango Team field from having “required” values to having “suggested” values. 
7. On the Final Merged WITDs, I removed any old work item states (System.State) values and replaced all the state transitions with the states and transitions from the MSFT Scrum template WITDs.
8. The WITDs are now ready to start uploading to TFS but in order to make them actually pass validation, you need to upload a bunch of supporting pieces for the Microsoft Visual Studio Scrum Template.  These files are all located in the directory where you exported the Microsoft Visual Studio Scrum process template. 
9. Using “witadmin importwitd”, upload SharedStep.xml from the Microsoft Visual Studio Scrum Template TypeDefinitions folder.
10. Using “witadmin importwitd”, upload TestCase.xml from the Microsoft Visual Studio Scrum Template TypeDefinitions folder.
11. Using “witadmin importwitd”, upload CodeReviewRequest.xml from the Microsoft Visual Studio Scrum Template TypeDefinitions folder.
12. Using “witadmin importwitd”, upload CodeReviewResponse.xml from the Microsoft Visual Studio Scrum Template TypeDefinitions folder.
13. Using “witadmin importwitd”, upload FeedbackRequest.xml from the Microsoft Visual Studio Scrum Template TypeDefinitions folder.
14. Using “witadmin importwitd”, upload FeedbackResponse.xml from the Microsoft Visual Studio Scrum Template TypeDefinitions folder.
15. Using “witadmin importlinktype”, upload TestedBy.xml from the Microsoft Visual Studio Scrum Template LinkTypes folder.
16. Using “witadmin importlinktype”, upload SharedStep.xml from the Microsoft Visual Studio Scrum Template LinkTypes folder.
17. Using “witadmin renamewitd”, rename the “Sprint Backlog Item” WIT to “Task”.
18. Using “witadmin importcategories”, upload categories.xml from the Microsoft Visual Studio Scrum Template Work Item Tracking folder.
19. If you’re using transitional “Merged During Upgrade” WITDs, upload them to your TFS server using “witadmin importwitd”.
20. Using “witadmin importcommonprocessconfig”, upload CommonConfiguration.xml from the Microsoft Visual Studio Scrum Template Process folder.
21. Using “witadmin importagileprocessconfig”, upload AgileConfiguration.xml from the Microsoft Visual Studio Scrum Template Process folder.
22. Before you upload the Work Item Queries (WIQs) for the Microsoft Scrum Template, you’ll need to create the default Iteration (System.Iteration) that is referenced by the WIQs.  Log on to TFS and create an iteration named “Release 1/Sprint 1”. 
23. If you want to archive your existing WIQs, you should do it now.
24. The Microsoft Visual Studio Scrum Template Work Item Tracking Queries folder contains a bunch of WIQs that need to get uploaded to your Team Project.  Upload all of these WIQs to your Team Project.  Unfortunately, there doesn’t appear to be a way to do this other than through the TFS APIs so you’ll need to write a tool that will upload the WIQs to TFS. 
25. If you’re copying values and updating state values for your Bug work items, do the modifications now.  You’ll probably want to map the following fields:
    System.Description to Microsoft.VSTS.TCM.ReproSteps
    Conchango.TeamSystem.Scrum.EstimatedEffort to Microsoft.VSTS.Scheduling.Effort
    Conchango.TeamSystem.Scrum.BusinessPriority to Microsoft.VSTS.Common.BacklogPriority
    Conchango.TeamSystem.Scrum.TestingImpact to Microsoft.VSTS.Common.Severity
    Conchango.TeamSystem.Scrum.Team to System.AssignedTo
26. If you’re copying values and updating state values for your Product Backlog Item work items, do the modifications now.  You’ll probably want to map the following fields:
    Conchango.TeamSystem.Scrum.EstimatedEffort to Microsoft.VSTS.Scheduling.Effort
    Conchango.TeamSystem.Scrum.ConditionsOfAcceptance to Microsoft.VSTS.Common.AcceptanceCriteria
    Conchango.TeamSystem.Scrum.Team to System.AssignedTo
    Conchango.TeamSystem.Scrum.BusinessPriority to Microsoft.VSTS.Common.BacklogPriority
27. If you’re copying values and updating state values for your Task work items, do the modifications now.  You’ll probably want to map the following fields:
    Conchango.TeamSystem.Scrum.WorkRemaining to Microsoft.VSTS.Scheduling.RemainingWork
    Conchango.TeamSystem.Scrum.TaskPriority to Microsoft.VSTS.Common.BacklogPriority
    Conchango.TeamSystem.Scrum.Team to System.AssignedTo
28. If you’re copying values and updating state values for your Impediment work items, do the modifications now.  You’ll probably want to map the following field:
    Conchango.TeamSystem.Scrum.Team to System.AssignedTo
29. If you’re using transitional “Merged During Upgrade” WITDs, upload the “Final Merged” WITDs to your TFS server using “witadmin importwitd”.
30. Using a call to the TFS APIs, call the TeamSettingsConfigurationService’s SetTeamSettings() method to populate the default team for the Team Project. 
31. Using “tfpt addprojectreports” command, update the SQL Server Reporting Services site for the Team Project using the definitions in the Microsoft Visual Studio Scrum Template.

Summary

At this point, your Team Project has been updated and is now basically the same as an out-of-the-box Microsoft Visual Studio Scrum template project.  I’ll admit it – it’s a lot of work and what I wrote above is really just the sketch of what you’ll need to do.  But it’s a lot better than being stuck on TFS2008 or moving to TFS2012 and having a whole lot of broken team projects. 

I hope this helps you out.

-Ben

— Got a pile of Conchango projects that you’d like upgraded to Team Foundation Server 2012 or Team Foundation Server 2013?  We know how.  We’ve done it before.  Drop us a line at info@benday.com.