Deep Dive on Configure Features

Deep Dive on Configure Features

Rate This
  • Comments 18

Upgrading is hard. We have heard a lot of comments about the pain that people had to deal with during the upgrade of the team projects from TFS 2008 to TFS 2010. For TFS 2012 we make this upgrade much easier for customers with none to limited customizations with a wizard. This post is in addition to the documentation on MSDN, and will go deeper into how the wizard works. The purpose of this post is to provide you the information that helps you to  modify your team project or process template in case you have added customizations that broke the wizard. If you have corrected the breaking changes the wizard is able to run successfully again.


To be able to configure the new features, the wizard makes use of the process templates installed on the server. The benefit is that we can support localized process templates, but also use settings from customized process templates. The latter is especially beneficial for larger TFS installations that reuse the same process template for  the team projects. So let's take a look how it works.

Listed below are actions the wizard performs and the usage (or dependency) on the artifacts in the process template.

Action category Usage
Add work item type Code Review Response
  Code Review Request
  Feedback Response
  Feedback Request
Add work item category Code Review Response Category
  Code Review Request Category
  Feedback Response Category
  Feedback Request Category
  Hidden Category
  Bug Category
  Task Category
Add tab to work item form (optional) (*) Storyboards tab
Add action to transition (optional) (*) StartWork action
  StopWork action
Add Agile Configuration settings  
Add Common Configuration settings Field mapping
  State mapping
  Category mapping


(*) The optional action categories will only create warnings, and I will not discuss those items in this blog post. To resolve any messages around these warnings see the MSDN documentation.

For each of these actions we need to check whether it

  1. exists in the process template
  2. can be mapped to the existing artifacts in the team project
  3. does not conflict with the existing artifacts in the team project

Validation step 1: Exists in the process template

A good example of items that need to exist in the process template are the code review and feedback work item categories. If the wizard is validating a TFS 2010 process template, the categories are not available and the process template is not valid.

The wizard not only checks for the existence of categories, but on all the following items:

  • Work Item Categories
    • Microsoft.BugCategory
    • Microsoft.CodeReviewRequestCategory
    • Microsoft.CodeReviewResponseCategory
    • Microsoft.FeedbackRequestCategory
    • Microsoft.FeedbackResponseCategory
    • Microsoft.RequirementCategory
    • Microsoft.TaskCategory
  • Work Item Type(s) specified the above Work Item Categories
  • Fields specified in the AgileConfiguration.xml file
  • Fields specified in the CommonConfiguration.xml file (*)
  • All the states specified in the Microsoft.RequirementCategory or Microsoft.TaskCategory must exist in at least of the work item types specified in that category (**)

(*) We have added an exception to make sure it is possible to successfully run the wizard if you have not customized your team project. In TFS 2012 the field Microsoft.VSTS.Scheduling.Size is added to the Requirement work item type in the CMMI process template. That new Size field is used this field to map the Effort. Since this field did not exist in previous version of the CMMI template, there is no upgrade path for CMMI team projects from TFS 2010 to TFS 2012. To fix this a hard coded rule was added says in pseudo code

if (MappedField("Effort") == "Microsoft.VSTS.Scheduling.Size" && !Exist("Microsoft.VSTS.Scheduling.Size") && Exist("Microsoft.VSTS.Scheduling.OriginalEstimate"))
       MapField("Effort", "Microsoft.VSTS.Scheduling.OriginalEstimate");

Because of this rule, CMMI team projects created in TFS 2010 use the Original Estimate as the effort metafield instead of the Size field.

(**) The other exception is to support the successful run for the Agile process template. The "New" state was added to the Task and User Story work item types. This "New" state is used to map "Proposed", but since the state does not exist in the Task and User Story work item type the wizard would fail. To fix this, a rule was added that says in pseudo code

if (!Exist(MappedState("Proposed")) && MappedState("InProgress").Count == 2)
       MapState("Proposed", MappedState("InProgress")[0]);

Because of this the rule, the Task and User Story work item types map the Active state to the Proposed metastate. The consequence of this is that the Task Board will only show two lanes (Active and Closed) and whenever a User Story keeps visible on the Product Backlog until it got resolved. The latter is due to the logic of the product backlog which shows all work item types specified the Requirement category that are either in the root iteration path or are in the InProposed metastate.

Validation step 2: Can be mapped to the existing artifacts in the team project

The result of the previous validation step is a list of candidate process template that might contains the correct settings to be used by the wizard. The next step in the validation of the wizard is to see if the settings of the candidate process templates can be applied to the existing team project. An example of such a check is to see if the field that is mapped in the CommonConfiguration exists in the current team project. Besides this check, the wizard will do all the following checks:

  • For all the TypeFields in the CommonConfiguration file the mapped field exist in the current team project
  • For all the columns in the AgileConfiguration file the mapped field exist in the current team project
  • The work item types specified in the categories (*) exist in the current team project
  • For each category (*) the mapped states specified in the CommonConfiguration file need to exist in at least one of the work item types specified in that category.
    Here is an example to clarify this. Imagine you have a category that has two work item types in it called WIT_A and WIT_B. Those two work item types have different workflow states. WIT_A has the states S_A, S_B and S_C and the states of WIT_B are S_D, S_E and S_F. I can now have the following valid states mapping:

      <RequirementWorkItems category="Microsoft.RequirementCategory" plural="Stories">
          <State value="S_A" type="Proposed" />
          <State value="S_B" type="InProgress" />
          <State value="S_C" type="Complete" />
          <State value="S_D" type="Proposed" />
          <State value="S_E" type="InProgress" />
          <State value="S_F" type="Complete" />

(*) see the previous paragraph for the complete list of categories the wizard cares about

Validation step 3: Does not conflict with the existing artifacts in the team project

The last step of the wizard is to verify whether the work item fields that will be added due to importing work item types are not conflicting with already existing artifacts within your team project. The work item types that the wizard imports are the Feedback and the Code Review work item types. The fields in those work item types are either in the System.* or the Microsoft.* namespace so they will not create a conflict if you have not used those namespaces for your own fields. For each field in those imported work tem types that is already existent (based on refname) in the team project, the wizard verifies whether the following attributes have the same value for the existing field and the field in the process template:

  • name
  • type
  • syncnamechanges
  • reportingrefname
  • reportingname
  • reportable

Another validation is to check whether the combination refname/name is unique. If there is already a field in the team project that uses the name of the imported field, but using a different refname it causes a conflict. For example the feedback work item type adds the field with the name "Rating". Since it is not unlikely that you already added that field with a different refname, the wizard will try to resolve the conflict automatically by adding the name of the process template to the name of the field that we import. It is the same logic that is used when you create a new team project.

Message Severities

During the validation the framework returns a list of messages with different severities for each process template on the server. The severity can either be a warning, an error or a critical error. When there is a critical error (which are the message in the first validation step) in the list, the process template is considered as inappropriate. If all process templates installed on the server have critical errors, you will see the following screen.


The other severities are error and warning and when the validation contains no critical errors, these messages are shown to the user. If there are errors in that list the user cannot configure the team project. On the contrary, if the list of messages only contain warnings the wizard shows these messages and the user can continue configuring the team project.

The errors are in general the result of validation steps 2 and 3. The warnings are a result of the optional configuration steps as stated in the table in the beginning of the post.



I hope you found this post helpful to understand how the wizard works, what the steps are and how you can resolve the errors in the team project or the process template.

Leave a Comment
  • Please add 2 and 2 and type the answer here:
  • Post
  • Hi Ewald,

    Thanks for this post, it really helps to better understand what the wizard actually does. Unfortunately, the process fails for one of our team projects. The wizard tells me that no process template was found. In the event log of the application tier I see this (the project was created using a slightly modified Agile 5.0 template):

    Detailed Message: No valid process template found for project vstfs:///Classification/TeamProject/***

    [Process Template Errors]

    MSF for Agile Software Development 6.0

    [Critical] The given key was not present in the dictionary.

    On the other hand we have team projects that are happily upgraded by the wizard. Even more interesting, the failing and succeeding projects consist of the same work item type definitions (I exported them and verified!). Is there anything I can do to get more detailed information as to what this critical error is? I'm sure it is just a tiny thing that has to be corrected for this project, but I have no idea where else to search for it...

    Many thanks in advance,


  • Hi Daniel,

    Sorry to hear the you have run into troubles with the wizard. I would like to investigate what is causing the problem.

    Could you please send me a copy of your process template so I can investigate further. You can send it to ewald_dot_hofman_at_microsoft_dot_com.

    Thanks in advance.

    Ewald Hofman

  • Hello,

    I've go the same issue here, we have several projects that upgrade without a problem but 2 team projects do not upgrade with these errors.

    Process Template Errors]

    Microsoft Visual Studio Scrum 2.2

    [Critical] TF400613: The work item type 'Task' specified in category 'Microsoft.TaskCategory' does not exist

    [Process Template Errors]

    MSF for Agile Software Development v5.0

    [Critical] TF400614: Category 'Microsoft.CodeReviewRequestCategory' does not exist

    [Process Template Errors]

    MSF for CMMI Process Improvement v5.0

    [Critical] TF400614: Category 'Microsoft.CodeReviewRequestCategory' does not exist

    [Process Template Errors]

    MSF for Agile Software Development 6.2

    [Critical] TF400613: The work item type 'Task' specified in category 'Microsoft.TaskCategory' does not exist

    [Process Template Errors]

    MSF for CMMI Process Improvement 6.2

    [Critical] TF400613: The work item type 'Task' specified in category 'Microsoft.TaskCategory' does not exist

    How can we fix this ?

    Kind regards

  • Hi  Philippe Devaux,

    It seems that you don't have the Task work item type in the team projects. Maybe you have renamed or deleted the work item type, or you might have used a localized version of the process template.

    Could you check the existence of the Task?



  • Hi Ewald,

    We are currently using Scrum for Team System. i have tried to configure TFS 2012 but just get the error:

    Value cannot be null.

    Parameter name: stream

    When trying to access the project via the Test tab functionality, I also get the error:

    TF400572: The Common Project Settings and the Agile Project Settings must be configured for this feature to be used.

    I have tried upgrading templates manually and importing the common project and agile project settings but have had no luck. We have far too many projects to create new projects and start from scratch. Any help you can offer on getting our projects to run in TFS 2012would be greatly appreciated.



  • @Jen, sorry for the late reply. I am sorry to hear that you are experiencing issues while upgrading. Are you still blocked on this issue?

    I would like to dig deeper in this. Could you please contact me at ewald dot hofman at Microsoft dot com?



    TFS Program Manager

  • Hi

    I upgraded TFS2008 to 2012 and then to 2013. When I try to configure features I get "There are no process templates available with valid configuration settings for this team project." and no configure button. It say I must manually update the templates, but how and with what? Is there a step that was missed in upgrading to 2010?

  • @Nik, it is described on MSDN: Update a customized process template to access new features (

  • Thanks for your reply but there are no customised templates, they all come from TFS 2008.

    Could you give me some quick pointers as to the tasks to be executed?  A link would be enough or just some hints as to what to edit, add and how.

    Thanks again.

  • @Nik, you need to apply the steps as described here:

    TFS 2008/2010 -> TFS 2012:

    TFS 2012 -> TFS 2013:

  • Thanks

    That's much more specific than I was able to find. I'll see how I get on.

  • @Ewald -  It took a lot of typing but the new features are all enabled now, thanks.

  • Hello Ewald - we have old TFS collections based on TFS 2008 that were upgraded to 2012 but the new features don't work. The work items have quite some customization. I have installed TFS 2012 on a new server in a different domain and am planning on detaching/attaching collections from old TFS environment to new one.

    The question to how to get the new features working? I tried the wizard in the old environment but it failed. The new environment will have new process template (we plan on using Agile) but the work items are customized. If the wizard fails in the new environment should I use the code above to add features manually?

    Any other suggestions?



  • The wizard only works if you upgrade from TFS 2010 or TFS 2012. In your case, you can refer to the documentation on MSDN to enable the features manually:

  • Thank you Ewald for the quick response. I'll try the manual update. So your application will also not work?

Page 1 of 2 (18 items) 12