Changing Work Item Templates on Team Foundation Service

This article originally appeared on my personal blog.

Introduction
If there is one thing that Team Foundation Service (TFS) does really well, it is the use of work items. A work item can be a lot of different things. For example, it can be a bug, a task, a user story, an epic, or a test case. It can even be a request for a code review.

You can define relations and dependencies between work items and you can assign work items to changesets (commits). The possibilities seem endless.

The work items available to you are decided by the template that your admin chooses for you when she creates a so-called team project.

At work we have been using TFS since the dinosaurs walked the earth. Back then TFS was a whole lot different than it is today which means that the templates looked a lot different. For example, the template used for the team project we are using on my team is based on some old Microsoft Foundation framework which only allows bugs and tasks. I does not allow us to create cool things like user stories or code review requests.

So I decided to upgrade the templates. There is not built-in way to upgrade so you have to do it manually. I am no TFS expert but I found out that the process is:Â

1. Export the work item templates from TFS.
2. Edit the templates if necessary.
3. Import the templates to TFS.

Sounds easy, right? Well, it's not hard but it is kind of cumbersome.

Changing the work item templates is only possible on on-premise TFS. Don't try this on Visual Studio Team Services (at visualstudio.com).

Exporting Templates

Work item templates (WITs) are defined as XML-files so first you want to export the XML-files that you want to use from TFS. The export is done through Visual Studio and the tricky part is that you need to do it from a Visual Studio version that corresponds to your TFS version. So, in my case we are on TFS 2015 so I need to do the export from Visual Studio 2015.

To export the WITs go to the menu Team –> Team Project Collection Settings –> Process Template Manager. Here you need to decide which template you wish to upgrade to. If you want to upgrade to the "Agile" template, then that is the one you should download.

Click the “Download” button to download the XML-files.

If you chose to download the “Agile” process template, the files will be placed in a subfolder called “Agile”. The interesting files for WITs are located under “Agile\WorkItem Tracking”.

If you take a look at the files in the folder “Agile\WorkItem Tracking\TypeDefinitions” you will see that there is an XML-file for each work item type, for example Bug, UserStory, Task, TestCase, CodePreviewRequest. The files define the fields and states for the work items. These are the files that you need to import to our legacy team project to upgrade it to a newer process template.

Importing Templates
For the import you need to use the witadmin.exe tool from the command prompt. You have to use witadmin.exe for the right version of Visual Studio and TFS. For Visual Studio 2015 and TFS 2015, witadmin.exe is located at

%programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE

So let's start importing the work item templates. Unfortunately, I have been unable to find a way to batch import all the files in one shot so you have to do it one file at a time.

witadmin importwitd /collection:"http://mytfsserver/tfs/MyCollection" /p:"MyTeamProject" /f:"C:\downloadedtemplates\Agile\WorkItem Tracking\TypeDefinitions\Bug.xml"
witadmin importwitd /collection:"http://mytfsserver/tfs/MyCollection" /p:"MyTeamProject" /f:"C:\downloadedtemplates\Agile\WorkItem Tracking\TypeDefinitions\CodeReviewRequest.xml"
witadmin importwitd /collection:"http://mytfsserver/tfs/MyCollection" /p:"MyTeamProject" /f:"C:\downloadedtemplates\Agile\WorkItem Tracking\TypeDefinitions\CodeReviewResponse.xml"
...

You may encounter errors when trying to import. I ran into a number of renaming errors:

TF26177: The field Microsoft.VSTS.Common.BusinessValue cannot be renamed from '
Business Value - Microsoft Visual Studio Scrum 1_0' to 'Business Value'.

If fixed the errors by manually editing the XML-files. In the above case I searched for "Business Value" in the XML-file that failed and changed it to "Business Value - Microsoft Visual Studio Scrum 1_0". It didn't seem to matter anywhere in TFS after the import.

After all the WITs have been imported (without errors!) the final step is to import the categories. For example, the file categories.xml define which work items can be created directly by the user in TFS, and which work items are hidden, such as code preview requests that are created indirectly through code review requests in Visual Studio.

witadmin importcategories /collection:"http://mytfsserver/tfs/MyCollection" /p:"MyTeamProject" /f:"C:\downloadedtemplates\Agile\WorkItem Tracking\Categories.xml"

And that's it! Now you should be able to create all the fancy Agile work items from within TFS, and you should be able to request code reviews from Visual Studio.