I’ve had a few people I know run into this recently, and there does not seem to be a lot of guidance out there about process template customization, in terms of troubleshooting or tips and tricks. While running through process template updates to move clients from TFS 2005/2008/2010 to TFS 2013 I would occasionally encounter one of the annoyances of working with XML by hand:
Oh THAT is helpful. And if you’ve ever seen the contents of a process template you know this could be one of about a million different problems in hundreds of files.
Now if you do a lot of template customizations, well just stop it, right now, please. The more you customize the more you need to maintain, the more you potentially have to upgrade by hand when you move to a new version of TFS. There are times when heavy customization is necessary, but I often find people customize without understanding what the OOB template does in the first place. Unless you are checking your templates into source control, being very methodical about isolating changes and testing, and commenting your changes just like you do with your application code, you’re going to run into problems during upgrading. But chances are you’ve already gone down the path and here you are…
Enter TFS consultants. I prefer to do most of my process template editing directly against the XML using Notepad when I can. I know, it’s a bit old school, but there are a lot of us out there so I figured why not share? Inevitably, you misspell something, miss a closing bracket, enter an errant blank space where it does not belong, the common XML “bugs” that can be really difficult to track down. And as you know, Notepad does not have a debugger. So like me, I’m sure at some point you’ve tried to upload an updated process template using the TFS Process Template manager and seen the dreaded “TFS30139: The process template is not configured properly.” ::SIGH:: Now what? Well, if you followed my previous advice and were methodically checking in distinct changes, you know what you last changed. Kind of like CI for process templates :)
Enter the power tools. The TFS Power Tools contains a great process template editor that you can use in place of a lot of the command line tools for importing and exporting work item type definitions. You’ll need to install it on a machine running Visual Studio Professional or better, FYI.
It gives you some great visualization tools, allowing you to edit fields, configure the forms, visualize and edit workflows, states, and transitions, and an easy way to open and dig through all the nitty gritty details of everything else that a process template entails too. As an added bonus, it will give you MUCH better error diagnosis information if something is wrong. So for the previous error, I attempted to open the process template. But this time I got a much more friendly message, pointing me at the issue:
Because I knew that the last thing I changed before my last successful upload of the template was the ProcessTemplate.xml file. I knew exactly where to look and lo and behold, I’d left off a closing bracket at the exact location specified by Visual Studio. So I made the quick fix, successfully imported the updated template to the collection, and checked in the updated template file to SCM. Much better!
There are lots of potential tools and editors out there for process template editing, and everyone develops their own style. I often find myself leveraging several different tools in conjunction during a process template upgrade, it can be a lot of trial and error. They all have advantages and disadvantages, I’ve tripped over a few myself (like this little quirk with the Team project Manager extension if you’re trying to compare 2008 and 2013 templates). I should blog about some of those adventures too :)
Hopefully this gave you some new options you may not have been aware of before.