Importing Custom Work Item Types into TFS

Today a colleague of mine asked me for some help with a problem revolving around Team Foundation Server (TFS) so of course I said “sure, no problem.” I figured it’d be a no-brainer but as anyone will tell you, life often has other plans.

The question involved customizing and transferring a work item type from one collection to another. After the customization was completed (in this case a “User Story”) using the Process Editor (available via the Team Foundation Server Power Tools) my colleague wanted to know not only how is it possible to import that work item type from one collection into another but also to just have one template, not two (i.e. “User Story” and “User Story – Custom”)?

The first part of this problem about importing a work item type is extremely easy as the Process Editor within Visual Studio makes this a trivial task (see step 5). However, the second part is a little bit more involved so let’s walk through the steps:

Step 1

Export the customized work item type to an XML file (e.g. “UserStory.xml”). This can be accomplished within Visual Studio by going to the menu and selecting “Tools -> Process Editor -> Work Item Types -> Export WIT. ” I’d also recommend exporting the original work item type in the collection that’s going to be removed. A backup is always a good precaution if Murphy’s Law comes into play.

The next few steps makes use of the “witadmin” tool which is normally installed wherever Visual Studio has been installed. Also, all of these commands can be executed via a command prompt but remember to substitute the collection and project parameters with valid entries. For completeness, here are all of the commands this tool offers:

The following is the list of commands that are available:  

Type 'witadmin [command] /?' or 'witadmin help [command]' and press Enter to view help for a specific command.

categories changefield

        deactivatelinktype
        deletefield
        deletelinktype
        destroygloballist
        destroywi
        destroywitd        exportgloballist
        exportglobalworkflow
        exportlinktype
        exportwitd
        help
        importcategories
        importgloballist
        importglobalworkflow
        importlinktype
        importwitd
        indexfield
        listfields
        listgloballist
        listlinktypes
        listwitd
        reactivatelinktype
        rebuildcache
        renamewitd

Step 2

Using the “witadmin” tool, export the categories to an XML file:

C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE>witadmin exportcategories /collection:https://tfs.test.com/tfs/myCollection /p:myProject
/f:c:\temp\Categories.xml

Operation complete.

Step 3

Make a copy of the XML file (e.g. “CategoriesBlank.xml”) and remove all the categories and re-import the modified file (i.e. remove all the “CATEGORY” nodes).

C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE>witadmin importcategories /collection:https://tfs.test.com/tfs/myCollection /p:myProject
/f:c:\temp\CategoriesBlank.xml
Operation complete.

Step 4

Now it’s time to remove the specific work item type to avoid duplicates, in this case “User Story.”

C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE>witadmin destroywitd /collection:https://tfs.test.com/tfs/myCollection /p:myProject /n:"User Story"

Are you sure you want to destroy the User Story work item type as well as its 0 work item(s)? This action is not recoverable. (y/n)?y

Note: If you receive the following error then most likely step 3 was not completed correctly.

Unable to destroy work item type User Story

TF237055 : You cannot destroy a work item type that is being used. Verify that the work item type is not being used in any categories.

Operation failed.

Step 5

Import the new customized version of the “User Story” work item type using the Process Editor via Visual Studio. This can be accomplished within Visual Studio by going to the menu and selecting “Tools -> Process Editor -> Work Item Types -> Import WIT.

Step 6

Import the original category XML file to restore all previously removed categories.

C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE>witadmin importcategories /collection:https://tfs.test.com/tfs/myCollection /p:myProject
/f:c:\temp\Categories.xml
Operation complete.

Summary

While not being as straightforward as it should it (ever try deleting a work item?), this problem can be solved with just a few steps.