Deep Dive on Configure Features

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.

Validate

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.

(*) 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">
      <States>
        <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" />
      </States>
    </RequirementWorkItems>
  

(*) 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.

Finally

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.