Handling Strange Work Item Field Friendly Names after a TFS 2012 Upgrade

By | 2013-05-22T11:00:07+00:00 May 22nd, 2013|Team Foundation Server|2 Comments

After upgrading to Team Foundation Server 2012, you may find some fields that have unexpected friendly names. For instance, System.VSTS.Common.BacklogPriority field may have a friendly name of “Backlog Priority – Microsoft Visual Studio Scrum 2_2” instead of the expected (and out-of-the-box) “Backlog Priority”.

This isn’t a bug, but the way that Microsoft handles conflicts when upgrading a Team Project Collection that contains a friendly name that clashes with a new field they are introducing. For instance, in the case above, a “Backlog Priority” custom field was created in TFS 2010 (or earlier). During the upgrade, this conflicted with the newly added Backlog Priority field used by the Scrum 2.2 template. (As a side note, both the Reference Name and the Friendly Name for a field have to be unique to the entire TPC. It’s a common misconception that only the Reference Name need be unique.)

Steve's post 1

Figure 1: The Backlog Priority field has a non-standard friendly name

One way to check to see if there is a conflict with the friendly name is to open up a Query Editor, and look through the friendly names. If you see two, one with and one without the suspicious suffix, then you know you have a conflict.

steve post 2

Figure 2: Two fields in the query editor with similar friendly names 

At this point, you need to make a decision. If the prior friendly name (Backlog Priority, in this case), was heavily used, then you’d likely not want to change it. However, you still may want to change the new Backlog Priority to something less verbose, and more understandable. Alternatively, you may prefer to rename the old one, then rename the new one back to the standard form (to keep consistency with the new process templates). In either case, you’ll need to rename one or both of them. If you don’t, your TFS end users will be faced with some relatively ugly column names in their day to day work.

Steve's post 3

Figure 3: Ugly friendly names make day-to-day operations into a bad experience

To rename the fields, you use the witadmin changefield command from the Developer Command Prompt. In the following example, the friendly name of the old Backlog Priority field (NWC.BacklogPriority) is changed first. Then the field added during the upgrade (with the complex suffix) is renamed back to the name that a clean TFS 2012 install would have.

steve's post 4

Figure 4: Using witadmin changefield to modify the friendly name

That’s it. The friendly name is now changed, and you’re on your way to a less confusing end user experience.

As a quick additional thought, if you’d like to see if there are any other fields that were impacted, or you simply want to verify that none of your fields were impacted, it’s very straightforward. You simply use the witadmin listfields command to output all the existing fields, then search for “ – “. The “space-dash-space” is automatically inserted into the friendly name by the upgrade process, followed by the suffix (which may be different than the one seen in my examples.) To do so, you pipe the output to a text file, then search the text file. The following commands in the Developer Command Prompt, followed by a Ctrl-F in Notepad, will do the trick.

witadmin listfields /collection:http://localhost:8080/tfs/FabrikamFiberCollection >> AllFieldsInCollection.txt

notepad AllFieldsInCollection.txt

steve's post 5

Figure 5: Using witadmin listfields to ensure you’ve found all the changes

About the Author:


  1. Hari Krishna February 3, 2014 at 4:12 am

    Hi Steven,

    Thanks alot for sharing valuable information. I am very new to SSRS and TFS reporting. Actually i am searching for TFS “UserDefinedFields” in SSRS report. After reading your article i understand that how to find the reference names by using “witadmin listfields” command. i tried your query and found the reference name of “UserDefinedField” but i am not getting the value of the TFS “UserDefinedField” in my SSRS report.

    Highly appreciate your help.


  2. James Tupper February 9, 2014 at 7:52 pm

    Hi Hari –

    Have you added a reporting attribute to the field? The default attribute is none, so it wouldn’t be propagated to the warehouse or OLAP cube to be able to report off of. Here is the MSDN article on the reportable attribute for a field in TFS:


Leave A Comment