A while back we wanted to make some changes to our process template. The template was selected back when we switched to TFS 2010 and has been used every since. We’re using TFS 2013 now. The problem is that we had no idea which variant of template we were using. There are several flavors and versions of Agile, SCRUM and even CMMI. Searching online revealed that most people just recommend setting up a new team project but that was out of the question. We had years of history and work items that we didn’t want to migrate. So we opted to go through the tedious process of upgrading our template manually to the latest version before making our customizations. This is a summary of what we did in case anyone else needs to go down this road.

WARNING: This is a dangerous, potentially corruptive process. Ensure you have a backup of your TFS databases before proceeding. You should also strongly consider doing this in a test environment first to verify everything works before doing it in production. If anything goes wrong then you are most likely going to be restoring your TFS database so proceed with extreme caution.

Getting Started

First things first, BACK UP YOUR DATABASES. This goes without warning. Next you should ensure that your template is up to date in TFS by going to the project’s web settings and verify that there are no features to be configured. Then download TFS Team Project Manager from CodePlex (herein referred to as TPM). This awesome tool allows you to compare, import, edit and export your templates and is a time saver. You’ll also want to download the TFS Power Tools for Visual Studio.

Figuring Out Your Template

Unfortunately, unless you wrote it down, there is no way of knowing. So the first step is to figure out which template you’re using. To do that you need to compare your team project template with the available templates (or at least the one’s you might be using).

• Download the templates from TFS
  • Open Visual Studio and connect to your TFS Server
  • Click TeamTeam Project Collection SettingsProcess Template Manager to view and download the templates available in TFS
  • Download the templates you may be using to a central location
    
• Start TPM
• Select your team project
  • Under Team Projects select the correct server
  • Check the box next to the appropriate team project
• Import the process templates
  • Select Work Item Configuration from the options at the top of the screen
  • Next to Sources click Add, select Import From Process Template XML and select the ProcessTemplate.xml file for one of the templates you downloaded
  • Repeat the previous step for each additional template you might have used or want to use

    

• Compare the team project configuration the imported templates
  • Click Compare Team Projects with Sources to compare all the templates
  • Click the results row to display a summary of the differences

    

Microsoft has published a useful comparison of the various template work items and states to help narrow it down.

The Sources column provides a summary of the matches. While not completely accurate it is a pretty good gauge as to which template you’re using. It is unlikely that any of the templates match exactly.

The Items column provides a better summary of what items are available in each template and how closely they match. Each template provides different sets of work items.  By comparing the work items you can identify the template that most closely matches yours.  You can ignore the categories and configurations for now as they are most likely mismatched because of missing data.

At this point it would be a good idea to write down which template you are using.  The description for the team project might be a good choice.

At this point you should know the base template that is in use for your team project.  Most likely you want to upgrade it to the current version that ships with TFS.  Upgrading an existing template is easier than switch templates altogether but the process is similar.

To upgrade your template you’ll need to do the following

• Add new work item types
• Update existing work items
• Update work item categories
• Update process configuration

Adding New Work Item Types

Adding missing work item types is straightforward.

• In TPM go to Work Item Types under Work Item Configuration and select Get Work Item Types
• Select Import and then Add to bring up the open dialog
• In the process template folder you downloaded earlier go to Work Item TrackingTypeDefinitions and select the XML file associated with the type to import
  
• Repeat for any additional missing types
• Once all the types have bee selected then click Import to import them into TFS

Updating Existing Work Item Types

Updating an existing work item type is harder as you have to determine the differences and apply them. Within the comparison dialog select each of the items that do not match 100% to bring up the differencing editor in Visual Studio.  In many cases you will simply be copying missing values from one XML file to another.  For example in this image there is a reason missing from the field.

Unfortunately you cannot update the template from within Visual Studio. Instead switch back to the TPM, close the comparison dialog and go to Work Item Types and select View/Export/Delete/Edit. Select the work item type and click the Edit button to bring up the editor where you can make the XML changes.

Be very careful to make the changes in the appropriate location. Fields can appear multiple times in a type definition but for different reasons. Also be aware that the comparison view may show the values in a different order then they are in the XML file.

Simply copying the missing value into the XML file and saving it will update TFS with the change. You should update the entire definition before trying to save the changes. In the case above this is a new reason value so the reason definition will need to be added as well.

There are several areas to be careful with. The <FORM> element is used by the UI for collecting information about the work item. There are often lots of attributes that are different. If you are adding fields then most likely the entire <FORM> element will need to be adjusted as well to make room for the form. I find that making the other changes and saving them to TFS first and then going back and making the UI changes helps reduce the likelihood of getting a validation error. Do be careful about fields moving around on the form. If you are adding a field then it helps to ensure the field isn’t already on the form elsewhere.

When making changes in the <WORKFLOW> element be sure that you are adding states and transitions to the appropriate sections. Because the ordering of the items is not guaranteed and many states have similar transitions it is very easy to make a change to the wrong state. VS actually has an editor for work item states but I prefer to use TPM. For transitions ensure you match the from and to states.

Some times field names are different between templates based strictly upon spaces in the name. At this point you are getting into potentially breaking changes. In general continue to use the original template field names to ensure that the BI functionality does not break.

Finally be very careful about removing things from the XML file. Sometimes you will run across fields that aren’t in the original template. Depending upon the template removing a field could break the template. If you are unsure then just leave the field in.

An alternative approach, if you have not customized your templates, is to simply copy the XML from the template to the editor and then save it. This is less error prone but any customizations you may have made will be lost.

At this point you can repeat the process of comparing the types and making any changes until all the work items are in sync. You might find that some work item types are not a 100% match. This generally occurs when there is more in the TFS template than the template you are copying.

Updating Work Item Categories

If the categories do not match then you will follow a similar approach. Categories simply associate work item types together. For example some types are hidden so they are part of a hidden category. To edit the categories use the Categories tab in TPM. TPM provides a UI for edit categories so you can use it to add or remove types from categories. Be sure to click Import Work Item Categories when done to save the changes to TFS.

Updating the Process Configuration

Assuming you selected similar templates then there should be only a few configuration changes to make. If there are a lot of changes for the process then you likely chose the wrong template. Most changes will be simple property changes like widths or display names. All the changes can be made in TPM by going to the Process Configuration tab and then clicking Get Process Configurations and finally Edit.

As with the <WORKFLOW> element, be very careful when editing the process configuration.  Most sections look similar. Verify the parent element (PortfolioBacklogs, BugWorkItems, etc.) match before making changes within the section.