Over a million developers have joined DZone.

Process Template Upgrade #7 – Overwrite Retaining History With Limited Migration


A little while ago I was looking into the best options for upgrading a process template but still keep your data intact, but there is still a little bit of ambiguity on how that is achieved. Although the original list had only #6 options lets look at the #7 option…

In option #7 we basically overwrite our old work items with the new ones. There is a little jiggery-pockery to get everything to align, but it allows us to keep the continuity of both history, field data and work item ID’s.

The Main Event: Upgrading Process Templates (TFS 2005 + TFS 2008 + TFS 2010 + TFS11)

I have created these instruction for doping the upgrade on “any” Team Foundation Server environment and there will be extra “fiddly” bits depending on the version and what third-party tools you are using.

WARNING: Always test the process against in a test environment before you move forward with production. Make sure that everyone (and I do mean everyone) logs in a performs a few of their normal tasks against the upgraded process before you go ahead with a production migration. If in doubt then get in touch at http://www.nwcadence.com before you get yourself into a mess!

Export old work item types

The first thing I need to do is list out all of the work items that I have available so that I know which ones I might have to change. In this case I have the Agile 6.0 Process Template, so I have User Story as the main requirement item.

witadmin listwitd /collection:http://localhost:8080/tfs/defaultcollection /p:"FabrikamFiber"

With the following result:

  • Task
  • Bug
  • Code Review Request
  • Code Review Response
  • Feedback Request
  • Feedback Response
  • Impediment
  • User Story
  • Shared Steps
  • Test Case

For each of these work item types that exist in the new template you will need to do a little bit of work, but not much. If you are moving from Agile 4.1, Agile 4.2 or Agile 5.0 you will not have the Feedback & Code Review items to worry about. However if you have customised any of the Work item Types, there will be some tinkering that you need to do.

For each Work Item Type:

witadmin exportwitd /collection:http://localhost:8080/tfs/defaultcollection /p:"FabrikamFiber" /n:Task /f:c:\temp\Task_FabrikamFiber_source.xml

Save them somewhere you can find them and not get them confused with the new ones.

Figure: Save out the Work Item Type Definition

Identify fields that do not exist in the new template

In this case I am moving from the Task Work Item Type in the MSF Agile 6.0 Template to the Visual Studio Scrum 2.0 Template. There are a number of fields that do not appear on the Scrum template that we will likely at least want to keep the data for:

  <field name="Priority" refname="Microsoft.VSTS.Common.Priority" type="Integer" reportable="dimension">
    <helptext>Importance to business</helptext>
    <allowedvalues expanditems="true">
<listitem value="1">
<listitem value="2">
<listitem value="3">
<listitem value="4">
    <default value="2" from="value">
  <field name="Original Estimate" refname="Microsoft.VSTS.Scheduling.OriginalEstimate" type="Double" reportable="measure" formula="sum">
    <helptext>Initial value for Remaining Work - set once, when work begins</helptext>
  <field name="Completed Work" refname="Microsoft.VSTS.Scheduling.CompletedWork" type="Double" reportable="measure" formula="sum">
    <helptext>The number of units of work that have been spent on this task</helptext>
  <field name="Start Date" refname="Microsoft.VSTS.Scheduling.StartDate" type="DateTime" reportable="dimension">
    <helptext>The date to start the task</helptext>
  <field name="Finish Date" refname="Microsoft.VSTS.Scheduling.FinishDate" type="DateTime" reportable="dimension">
    <helptext>The date to finish the task</helptext>
  1. For every field that has a different “refname” from that which exists in the new Work item Type you will need to add it to the list of fields. This will guarantee that you will still be able to see the history from the old work item type.

  2. Add old fields to the new Work Item Type

    This is very simple and entails adding the fields identified above to the new Work Item Type. This will allow TFS to continue to understand these fields even though you will not be displaying them.

    note: But do not add them to the UI

    note: Even if you forget to add the fields you will NOT loose the data, it will just be hidden until you add the fields.

  3. Rename the Work Item Type

    If the new  work item type has a different name from the new one you will need to perform a rename first.

    Figure: witadmin renamewitd /?

witadmin renamewitd /collection:http://vsalm:8080/tfs/defaultcollection /p:Agile3 /n:"User Story" /new:"Product Backlog Item"

This is the point at which you will start to break things. Queries, Reports, Dashboards and the new Agile Planning tools all rely on the Work Item Type name.

WARNING: Always do this on a test server first before you ever touch production

Update to the new Work Item Types

This is real easy, perhaps too easy, and you should make sure that you have all of the fields and that you know all of the impacts.

witadmin importwitd /collection:http://vsalm:8080/tfs/defaultcollection /p:Agile3 /f:"c:\data\Product Backlog Item.xml"

note: Document everything in a Script so that you make this a repeatable experience

WARNING: Always do this on a test server first before you ever touch production

Update Catagories.xml (TFS 2010+ only)

If you are using TFS 2010 or above Microsoft added the idea of categories to make reporting easier to customise.

witadmin exportcategories /collection:http://vsalm:8080/tfs/defaultcollection /p:AgileTest3 /f:c:\data\cats.xml

Calling this will dump out the existing categories so that you can edit and import them. For any of the work item types that you rename you will need to update the name in this configuration file.

< ?xml version="1.0" encoding="utf-8"?>
<cat:categories xmlns:cat="http://schemas.microsoft.com/VisualStudio/2008/workitemtracking/categories">
  <category refname="Microsoft.BugCategory" name="Bug Category">
    <defaultworkitemtype name="Bug">
  <category refname="Microsoft.CodeReviewRequestCategory" name="Code Review Request Category">
    <defaultworkitemtype name="Code Review Request">
  <category refname="Microsoft.CodeReviewResponseCategory" name="Code Review Response Category">
    <defaultworkitemtype name="Code Review Response">
  <category refname="Microsoft.FeedbackRequestCategory" name="Feedback Request Category">
    <defaultworkitemtype name="Feedback Request">
  <category refname="Microsoft.FeedbackResponseCategory" name="Feedback Response Category">
    <defaultworkitemtype name="Feedback Response">
  <category refname="Microsoft.HiddenCategory" name="Hidden Types Category">
    <defaultworkitemtype name="Code Review Request">
    <workitemtype name="Code Review Response">
    <workitemtype name="Feedback Request">
    <workitemtype name="Feedback Response">
    <workitemtype name="Shared Steps">
  <category refname="Microsoft.RequirementCategory" name="Requirement Category">
    <defaultworkitemtype name="User Story">
  <category refname="Microsoft.SharedStepCategory" name="Shared Step Category">
    <defaultworkitemtype name="Shared Steps">
  <category refname="Microsoft.TaskCategory" name="Task Category">
    <defaultworkitemtype name="Task">
  <category refname="Microsoft.TestCaseCategory" name="Test Case Category">
    <defaultworkitemtype name="Test Case">

You can see where User Story is listed in the Requirement Category and you can easily chnage and upload this. It is worth noting that using the “witadmin renamewitd” command will automatically make this change for you. Once we have make any changes necessary we can import it back into TFS and close that loop.

witadmin importcategories /collection:http://vsalm:8080/tfs/defaultcollection /p:AgileTest3 /f:c:\data\cats.xml

Note: This is done automatically if you use the “witadmin renamewitd”

Note: You can export the correct listing from a new clean template if you wish

Update the Configuration files (TFS 11+ only)

The Agile Configuration is what makes the new Agile Planning features in Team Foundation Server 11 come to life. There is also a Common configuration that will also need to b e set. In this case, because we are moving to a vanilla template we can just export both of them from an existing project and import them into the new project as is.

Agile Process Configuration

witadmin exportagileprocessconfig /collection:http://vsalm:8080/tfs/defaultcollection /p:FabrikamFiber /f:c:\data\agileprocess.xml

This produces a file that defines what is available on a couple of the agile pages including the Product and Sprint backlog pages.

< ?xml version="1.0" encoding="utf-8"?>
<column width="50" refname="Microsoft.VSTS.Scheduling.Effort">
<column width="400" refname="System.Title">
<column width="100" refname="System.State">
<column width="100" refname="System.AssignedTo">
<column width="50" refname="Microsoft.VSTS.Scheduling.RemainingWork">
        <field refname="System.Title">
<column width="400" refname="System.Title">
<column width="100" refname="System.State">
<column width="50" refname="Microsoft.VSTS.Scheduling.Effort">
<column width="200" refname="System.IterationPath">

Common Processing Configuration

witadmin exportcommonprocessconfig /collection:http://vsalm:8080/tfs/defaultcollection /p:FabrikamFiber /f:c:\data\commonprocess.xml

Which produces a file that defines what the states and names are for each of the work item types as well as formats for how things are displayed. If you want to work weekends, then this is the place to look as well.

< ?xml version="1.0" encoding="utf-8"?>
  <feedbackrequestworkitems category="Microsoft.FeedbackRequestCategory" plural="Feedback Requests">
      <state type="InProgress" value="Active">
      <state type="Complete" value="Closed">
  <feedbackresponseworkitems category="Microsoft.FeedbackResponseCategory" plural="Feedback Responses">
      <state type="InProgress" value="Active">
      <state type="Complete" value="Closed">
  <requirementworkitems category="Microsoft.RequirementCategory" plural="Backlog items">
      <state type="Proposed" value="New">
      <state type="Proposed" value="Approved">
      <state type="InProgress" value="Committed">
      <state type="Complete" value="Done">
  <taskworkitems category="Microsoft.TaskCategory">
      <state type="Proposed" value="To Do">
      <state type="InProgress" value="In Progress">
      <state type="Complete" value="Done">
    <typefield refname="Microsoft.VSTS.Common.Activity" type="Activity">
    <typefield refname="Microsoft.VSTS.Common.BacklogPriority" type="Order">
    <typefield refname="Microsoft.VSTS.Feedback.ApplicationLaunchInstructions" type="ApplicationLaunchInstructions">
    <typefield refname="Microsoft.VSTS.Feedback.ApplicationStartInformation" type="ApplicationStartInformation">
    <typefield refname="Microsoft.VSTS.Feedback.ApplicationType" type="ApplicationType">
        <typefieldvalue type="ClientApp" value="Client application">
        <typefieldvalue type="RemoteMachine" value="Remote machine">
        <typefieldvalue type="WebApp" value="Web application">
    <typefield refname="Microsoft.VSTS.Scheduling.Effort" type="Effort">
    <typefield format="{0} h" refname="Microsoft.VSTS.Scheduling.RemainingWork" type="RemainingWork">
    <typefield refname="System.AreaPath" type="Team">

And as I mentioned we are moving directly from one to another so we don’t need to make any changes, just import.

Update Reports in Reporting Services (TFS 2010 Power Tools+ only)

There is a command available from the power tools that will allow you to call one command to upload the new reports. I like to drop all of the old reports into a “_20XX-[process]-reports” folder so that I can always see what we had before. You don’t want to delete any customisation, bot they will likely not work anyway until updated.

tfpt addprojectreports  /collection:http://vsalm:8080/tfs/defaultcollection /teamproject:AgileTest3 /processtemplate:"Visual Studio Scrum 2.0"

WARNING: All out-of-the-box reports and any customisation will be inoperable until they are updated to take advantage of the new data

Migrating Data to new Fields:

At this point you have one of two choices. There will be data in field that have just had the reference name changed, like “System.Description” changing to “System.DescriptionHTML”, and we need to decide how to migrate it. Luckily the main fields, like “System.Title” have not changed so the work item will still be identifiable as it was before.

Automated Migration

You can create an application or a script to move data from one field to another. If you are using the API you can even head back in time to pull data from the past.

Dim tpc as TfsTeamProjectCollection = New TfsTeamProjectCollection("https://localhost:8080/tfs/defaultcollection")
Dim store as WorkItemStore = tpc.GetService(of WorkItemStore)
Dim wi as WorkItem = store.GetWorkItem(21)
Dim wiAtDate WorkItem = store.GetWorkItem(21, Date.Parse("2012-03-02 08:00"))
Dim wiRevision as WorkItem = store.GetWorkItem(21, wi.Rev -1)
    1. Either of these options will allow you to repopulate data auto-magically and almost transparently to your users.

    2. Self service migration

      In the self-service option we let the first user to edit a work item manually do the migration.

      Figure: You can select text from the history

      You can have user peruse t6he history at their leisure and copy any data that they need back into the main work item. This allows for some really complex translations and stops you getting caught up in arguments with users as to what data they want and how it will be converted. Even two teams working in the same project can do it in slightly different ways using the MK1 Eyeball and MK1 Logic System to interpret the results much more effectively than you can.

    And that’s almost it! If this is TFS 2010 then you are done, but if it is TFS 11 then there are a couple of other things that you may need to do depending on the breadth of the changes. In my case I am mainly going to be moving from [insert out-of-the-box template] or [insert-frankin-template] to the Visual Studio Scrum 2.0 template so I need to tell the rest of TFS how I am going to be using the data.

  1. DONE – You are now on a new Process Template with minimal baggage


I will try to catalogue any problems here, so add them in the comments and I will update!

  1. TF400508: The current process settings are either missing or not valid.

    If you are on Visual Studio 11 Team Foundation Server (dev11 | TFS11) then you will need to reconfigure the Planning Boards to work with the new work item types. In this case I have renamed the “User Story” work item type to “Product Backlog Item” and it results in an error.

    Figure: TF400508 is about Agile Planning boards

    You forgot to update #7 above. Go back and do it now!

  2. [TBA] Let me know what errors you find…

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}