VSTS - Workitem Architecture, Design Considerations and Customization: Part 3

Posted by: Subodh Sohoni , on 5/20/2008, in Category VSTS & TFS (Azure DevOps)
Views: 25794
Abstract: In Part 1 of this article we discussed about the general architecture of a workitem type and listed all the sections and their options which go into defining a workitem type. In Part 2 we covered the architectural and design considerations related to customization of workitem type. In Part 3 now, we will go to the brass tacks to know how this customization can be actually achieved.
VSTS - Workitem Architecture,  Design Considerations and Customization: Part 3
In Part 1 of this article we discussed about the general architecture of a workitem type and listed all the sections and their options which go into defining a workitem type. In Part 2 we covered the architectural and design considerations related to customization of workitem type. In Part 3 now, we will go to the brass tacks to know how this customization can be actually achieved.
Workitem types are stored in the database used by Team Foundation Server. Any modification for customization should be propagated to the database. Since it is not possible to make modifications directly in the database, the structure of workitem type is possible to be exported in to XML file.
Target of customized workitem type can be either in the existing team project or in the process template. Let us treat these two cases separately.
To modify workitem type in the existing team project we need to first export the workitem type in XML file. This step is not required if we are going to create a new workitem type from the scratch. Work involved to do so is nontrivial and very rarely will we be required to do it. For this article we will presume that we are going to modify the existing workitem type. We may modify the workitem type and retain the same name after modification. For example we need to make a small modification in the ‘Task’ workitem type to add a new state called ‘OnHold’. We can export that workitem type and import it back with the same name so that all the tasks in that team project will have this new state. Another option, if the modifications are many and we want to retain the existing workitem type as it is, is to change the name of the workitem type to, say ‘Test Execution’ and import it back so that now we will have ‘Task’ as well as ‘Test Execution’ in the team project. 
The XML file is generated using a command line tool named ‘WitExport.exe’. This command takes arguments: /t TFS Name, /p Team Project name, /n Name of the workitem type to be exported and /f Path with the name of the xml file which will be used for exported workitem type. The command which is available from Visual Studio Command prompt may look like:
> WitExport.exe /f C:\task.xml /t TFS_Name /p TeamProject_Name /n Task
Once the xml file representing the workitem type is available, we can make the necessary modifications in it. We can do it using as simple as notepad or use a special tool downloadable from Microsoft / Codeplex site. It is called Team Foundation Power Tool (tfpt.exe). It integrates with Visual Studio 2008 and provides a simple GUI where we can choose to do modifications which are validated by the tool itself. This can reduce the chances of any errors occurring in either setting the rules for fields or any typos. Refer to Part 2 of this article to read more about the design considerations for making the modifications.
 Work Item Type
After the modifications are saved back (tfpt saves them in a file with extension .wit) we can import it or the xml file back in the TFS database using a tool WitImport. The command may look as follows:
>WitImport.exe /t TFS_Name /p TeamProject_Name /f C:\task.xml
After the import is successful, we may need to refresh the Team Explorer to get the new definition of the workitem type loaded. If the name has been changed then a workitem type with new name will appear when we try to create a new workitem.
The scope of the modification that we made is that team project in which we imported the modified workitem type. Neither any other existing team project nor any team projects created later will have these changes. If we want to target all future projects to have modified workitem type then it is necessary to customize the process template itself. The usual process is to first make changes of customized workitem type in a dummy project, check the success of it and then finally customize the process template.
For modification of process template we begin by downloading the process template which needs to be customized. This is done using the Process Template Manager which is available in the context menu of the TFS -> Team Foundation Server Settings in the Team Explorer.
Process Template manager
For more details please refer to article on process template customization on the same site.
Once the process template is downloaded we can replace the existing workitem type XML file with the modified one. If it is a new workitem type we copy the file (for example Code Review.xml) in the \WorkItem Tracking\TypeDefinitions subfolder of the process template and add an entry for that file in the WorkItems.xml file as follows:
 <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Bug.xml" />
 <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Task.xml" />
 <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Qos.xml" />
 <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Scenario.xml" />
 <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Risk.xml" />
As a last step we upload the customized process template either with the same name or a different name. Any new team project now created using the customized process template will have the customized or newly created workitem type.
One care which needs to be taken if we have modified existing ‘Task’ workitem type to remove existing states and replace them with some new states. Process template provides the initial tasks which need to be created to the Team Project Creation wizard. The list of those tasks contain the setting for initial state of the workitem which needs to be modified as per the new state that should be the initial state of the tasks.
In the Part 3 of this article we have seen how to customize the workitem type in the existing team project as well as in the process template. The customization is done in the XML file which represents the workitem type and then either imported in the team project or placed in the process template which is then uploaded on the TFS.  I hope this article was useful and I thank you for viewing it.
If you liked the article,  Subscribe to my RSS Feed.

This article has been editorially reviewed by Suprotim Agarwal.

Absolutely Awesome Book on C# and .NET

C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.

We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).

Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.

Click here to Explore the Table of Contents or Download Sample Chapters!

What Others Are Reading!
Was this article worth reading? Share it with fellow developers too. Thanks!
Share on LinkedIn
Share on Google+


Subodh is a Trainer and consultant on Azure DevOps and Scrum. He has an experience of over 33 years in team management, training, consulting, sales, production, software development and deployment. He is an engineer from Pune University and has done his post-graduation from IIT, Madras. He is a Microsoft Most Valuable Professional (MVP) - Developer Technologies (Azure DevOps), Microsoft Certified Trainer (MCT), Microsoft Certified Azure DevOps Engineer Expert, Professional Scrum Developer and Professional Scrum Master (II). He has conducted more than 300 corporate trainings on Microsoft technologies in India, USA, Malaysia, Australia, New Zealand, Singapore, UAE, Philippines and Sri Lanka. He has also completed over 50 consulting assignments - some of which included entire Azure DevOps implementation for the organizations.

He has authored more than 85 tutorials on Azure DevOps, Scrum, TFS and VS ALM which are published on www.dotnetcurry.com.Subodh is a regular speaker at Microsoft events including Partner Leadership Conclave.You can connect with him on LinkedIn .

Page copy protected against web site content infringement 	by Copyscape

Feedback - Leave us some adulation, criticism and everything in between!