TFS Process Template Upgrade

When I first started using TFS processes, using on-premises TFS 2010, I selected the MSF for Agile Software Development v5.0 template.

After the upgrade of TFS to 2017, the process template was not working as expected. When attempting to upgrade the process templates in the web portal, the system performed upgrade checks against the Agile template, and failed with the following errors:

[Warning] TF400609: Cannot add the action 'Microsoft.VSTS.Actions.StartWork' to the work item type 'Task' because the state 'New' does not exist.

[Warning] TF400609: Cannot add the action 'Microsoft.VSTS.Actions.StopWork' to the work item type 'Task' because the state 'New' does not exist.

[Warning] TF400609: Cannot add the action 'Microsoft.VSTS.Actions.StartWork' to the work item type 'Bug' because the state 'New' does not exist.

[Warning] TF400609: Cannot add the action 'Microsoft.VSTS.Actions.StopWork' to the work item type 'Bug' because the state 'New' does not exist.

[Warning] VS402404: Bugs On TaskBoard: Bug does not have the Microsoft.VSTS.Common.Activity field defined. Some charts will not include these work item types.

[Warning] VS402404: Bugs On TaskBoard: Bug does not have the Microsoft.VSTS.Scheduling.RemainingWork field defined. Some charts will not include these work item types.

[Warning] TF400607: Category 'Microsoft.HiddenCategory' will be overwritten.

[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.

[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.

The Microsoft documentation outlines what is necessary to perform the manual steps prior to the upgrade: https://docs.microsoft.com/en-us/azure/devops/reference/add-features-manually?view=azure-devops-2019

Other pages show how to download the relevant items that need to be updated.

The target process template is downloaded using Visual Studio, Team->Team Project Collection Settings->Process Template Manager… This will show the template manager with installed templates. Since my project was closest to Agile I downloaded the Agile template.

Since the upgrade check flagged errors for the Task and Bug work item types, I tried to upgrade these using the Visual Studio TFS 2017 tools, but encountered an error:

c:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer>witadmin importwitd /collection:https://<tfsserver>/<collection> /p:<project> /f:"C:\Agile\Agile\WorkItem Tracking\TypeDefinitions\Task.xml"
Error while copying content to a stream.

I never managed to identify the cause of the error, instead, with the help of Google, I identified a work around. When running the commands with Fiddler (https://www.telerik.com/download/fiddler), they succeed. This may indicate an issue with tls/certificates.

c:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer>witadmin importwitd /collection:https://<tfsserver>/<collection> /p:<project> /f:"C:\Agile\Agile\WorkItem Tracking\TypeDefinitions\Task.xml"
The work item type import has completed.

c:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer>witadmin importwitd /collection:https://<tfsserver>/<collection> /p:<project> /f:"C:\Agile\Agile\WorkItem Tracking\TypeDefinitions\Bug.xml"
The work item type import has completed.

After performing these, the upgrade validation was still flagging the error about the RequirementBacklog. Searching through the new Agile process template, I located a dependency on User Story:

<RequirementBacklog category="Microsoft.RequirementCategory" pluralName="Stories" singularName="User Story" workItemCountLimit="1000">

I imported the item definition for User Story:

c:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer>witadmin importwitd /collection:https://<tfsserver>/<collection> /p:<project> /f:"C:\Agile\Agile\WorkItem Tracking\TypeDefinitions\UserStory.xml"
The work item type import has completed.

After this, the upgrade process was successful.