When upgrading from TFS 2008 or TFS 2010

Last Update: 4/5/2017

TFS 2015

Feature availability: This topic applies only to team projects hosted on an on-premises Team Foundation Server (TFS). Team projects on Visual Studio Team Services update automatically with each service upgrade.

Each version of Team Foundation Server (TFS) typically introduces one or more changes to work item tracking. To gain access to the new features that rely on these changes, your existing team projects must be updated.

The Configure Features wizard is designed to make the update process pain free, however, customized team projects may prevent the wizard from being successful. If you're upgrading from TFS 2008 or TFS 2010, you have some additional steps.

Option 1:

This option is simpler, but will result in more downtime, especially if your TFS databases are very large. It may not work if you have customized your team projects heavily.

Option 2:

This option is more work, but it will work with customized team projects and it reduces dowbtime because you don't have to upgrade twice.

Updating team projects based on earlier versions of MSF process templates

If you upgrade your TFS instance to TFS 2015 and your existing team projects were created with MSF version 5.0 or earlier process templates, you may have to apply a few updates manually. Two specific problems can occur having to do with a missing field or workflow state.

Value Area field missing

The following message reported by the Configure Features wizard indicates that the Value Area field is missing from either the User Story or Requirement WIT definition:

[Error] TF400654: Unable to configure Planning Tools. The following element contains an error: RequirementBacklog/Columns. TF400529: This element defines the columns that appear on the backlog. You must set all values to fields that exist in at least one of the work item types belonging to the category. The following fields do not exist in any of the work item types: Microsoft.VSTS.Common.ValueArea.

You can resolve this error by (1) adding the following syntax to the FIELDS section of the User Story or Requirement definition:

<FIELD name="Value Area" refname="Microsoft.VSTS.Common.ValueArea" type="String">
   <REQUIRED />
   <ALLOWEDVALUES>
     <LISTITEM value="Architectural" />
     <LISTITEM value="Business" />
   </ALLOWEDVALUES>
   <DEFAULT from="value" value="Business" />
   <HELPTEXT>Business = delivers value to a user or another system; Architectural = work to support other stories or components</HELPTEXT>
</FIELD>

and the following syntax to the FORM section:

<Control FieldName="Microsoft.VSTS.Common.ValueArea" Type="FieldControl" Label="Value area" LabelPosition="Left" />

Or (2) removing the following entry from the ProcessConfiguration RequirementBacklog section:

<Column refname="Microsoft.VSTS.Common.ValueArea" width="100" />

See Add features using a manual update process for more information about updating these files manually.

New workflow state missing

The following message reported by the Configure Features wizard indicates that the New workflow state is missing for the Bug WIT definition:

[Error] TF400654: Unable to configure Planning Tools. The following element contains an error: BugWorkItems/BugWorkItems. TF400506: This element defines the states for work items that represent Bugs or Defects. Each state must exist in at least one of the work item types that are defined in: BugWorkItems. The following states do not exist in any of the work item types: New.

To resolve this error, you must add the New workflow state to the Bug definition as described in Add features using a manual update process.