Quick Tip on Debugging TFS30139 Issues

by Angela 12. December 2013 17:27

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.


These are a few of my favorite things about TFs 2013: Part 2

by Angela 12. November 2013 07:53

So hopefully you already caught part 1 where I extolled the virtues of Work Item Reporting. This time, I have moved into new territory!  I am in the middle of a big, slightly nasty, TFS upgrade and TPC consolidation project.  First thing is first. Attaching a legacy Team Project (TP) to TFS 2013 “upgrades it” but only in the sense that it works on TFS 2013. So you get everything you had before, but not necessarily ALL of the new stuff in 2013.  You probably have very little of the new features in terms of the “agile planning tools”. There were changes made to the underlying TP Process Templates to support new features like, the “Feature” feature :)

I apparently had been taking the TFS Configure Features Wizard (CFW) for granted. “The what?” you say…  Yeah, the thing that gets launched when you upgrade to TFS 2013 and you try to open something like the Product Backlog while connected to a legacy (pre-2012) TP. So if you’ve seen this message, the link at the bottom launches the CFW:


Often if you have an older, customized template (like modified CMMI 4.2), you can run into issues with the wizard.  You may be familiar with errors like this “[Error] TF400654: Unable to configure Planning Tools. The following element contains an error: RequirementBacklog” or “[Error] TF400654: Unable to configure Planning Tools. The following element contains an error: TypeFields/TypeField[type='Order']“. Makes sense, there are some HUGE deltas between older templates and those in 2013.


So the CFW is super easy to use if you can upgrade with the OOB templates, especially if you’re just upgrading one version behind. And how often does THAT happen in the real world? Right. In our case we have TPs coming from TFS 2005, TFS 2008, AND TFS 2010 and all the templates are customized versions of CMMI. Oy. I decided to begin by upgrading the 2010 TPs since they were the most straight-forward and had the least amount of differences as compared to CMMI 2013. So, that is the main focus of THIS post.  I will share experiences IRT other template versions later.  So if you start with MSDN you’ll see a tangle of different articles when it comes to upgrading to new templates. A few important points about process templates:

  1. A) In case you did not know, you can’t just swap templates out once you have created a Team Project and started using it, you HAVE to upgrade the underlying template of a team project itself to make changes ::opens giant can of worms:: OR if it’s a major change, like going from CMMI to Agile, just trust me on this -- migrate to a new Team Project.
  2. B) Template upgrades can be scripted but at the end of the day it is very manual, and fairly time consuming because of all of the testing required.  XML can be tricky for even the saltiest of us developers.  In the old days it was ALL manual all the time and all command line, but over the years a host of helpful add-ons have become available like the process template editor in the TFS Power Tools, and the TFS Team Project manager tool.
  3. C) Changes to a base process template (so at the TFS Collection level) do not automatically filter down to TPs created with that template, wouldn’t that be awesome and terrible at the same time?!  You must manually apply any template changes to all TPs that used that template, if you want them to remain consistent.  I bet now you really regret spinning up new TPs for every single one-off project your IT group dreamed up huh?


But now there is another way, the Configure Features Wizard ::duh duh DUUHHHH:: I will admit, I did not thoroughly RTFM the first time through and missed out on the full power of this little tool myself. To be fair, the last time I had a massive mutli-version TFS consolidation this tool didn’t even exist.  Of course now that I know what to search for, I turned up this AMAZING post of Edwald’s on how the wizard works, as well as this MSDN article that details how it is working its beautiful magic under the covers.  To sum up why it is so awesome, it allows you to specify your template changes once, and then easily rinse and repeat with a click of a button. No scripting or command line necessary. Unless you like that sort of thing, or have a bajillion TPs, then have at it, but use this handy script to iterate through all of your projects.

So how does it work? I still contend there is some black magic involved, but more likely it was a lot of late nights by some wicked smart TFS dudes. Essentially, you need to create a new copy of the legacy template that was used to create the team projects that you wish to upgrade to 2013, and then retrofit some new shinies from both 2012 and 2013 into it. I first downloaded CMMI v5.0 (which they had customized and re-uploaded without renaming – ACK!). Next I had to do things like add in a handful of work item types (Code Review and Feedback for 2012, Features for 2013), update my WIT categories, as well as add the Process Configuration file specific to 2013.  For all other work items I was able to simply replace the 5.0 WIT definitions with the 2013 versions, and then retrofit the client’s customizations back in. I used the heck out of the Team Project Manager Tool to compare them and see exactly what was customized.  Be careful here and read both the 2012 changes AND the 2013 changes that need to be incorporated, so you don’t duplicate effort.  For instance, the 2012 changes have you add 2 configuration files, but then both of those files are replaced by the single Process Configuration file for 2013. When I was done, I had a new version of the process template (with a new name!) that I could use with the wizard to convert the old TFS 2010/CMMI 5.0 TPs to 2013. It also contained all of the customizations that were done on the template before the TPs were created.  Last, I uploaded that bad boy to the TFS Server, navigated to my legacy TPs one-by-one, and launched the Configure Features Wizard. I ignored the recommendation of CMMI 2013, and picked my updated CMMI 5.0 template:


When the wizard runs, the super-simplified explanation is that it performs a DIFF on the team project and the modified process template, and applies the changes to the TP so it now matches the template. I KNOW!! So update the template once, run as many times as you need.


Now, if after the team projects were created off of that old template, you had some template cowboys who went in customized the crap out of team projects in an inconsistent manner, or did not also make that change to the underlying base template as well, you may end up needing to upgrade those team projects by hand and/or resolve any issues encountered during the wizard to upgrade them to 2013 completely. No easy button there. And maybe start being more careful about who you let customize process templates and team projects going forward! ;)

Now you have a simple way to upgrade all of the team projects created off of that old, custom template up to 2013.  At least for 2010.  Next we tackle all of the 2008 TPs.  And my understanding is that if you have 2005 TPs, just play some Taps and migrate what you need to a fresh, new 2013 TP.


Application Lifecycle Management | ALM | Power Tools | SDLC | Team Foundation Server | TFS | TFS 2013 | TFS 2012 | TFS Administration | TFS Power Tools | TFS Upgrade | Visual Studio 2013 | Work Item Tracking

Powered by BlogEngine.NET
Original Design by Laptop Geek, Adapted by onesoft