編輯

Share via

Validate and prepare server environment for migration

  • 發行項

Validation involves preparing your upgraded Azure DevOps Server environment for migration. This article assists you in troubleshooting common issues. If there were no errors and all the validation checks passed, then your team project collection is ready and you can move on to the next phase. Look through the log files to find any errors if not all checks passed.

Diagram of highlighted Validate stage of the seven stages of migration.

Prerequisites

Download the latest Data Migration Tool.

Learn process validation types

During validation, the Data Migration Tool determines the target process model for each project. It automatically assigns one of the following two process models to each project in the collection:

  • Inherited process model: If the project was created with the Agile, Scrum, or Capability Maturity Model Integration (CMMI) process template and was never customized.
  • Hosted XML process model: If the project process appears to be customized. A customized process contains custom fields, work item types, or other types of customizations.

When the Hosted XML process is the targeted process model, the Data Migration Tool validates if the customizations can be migrated. The Data Migration Tool generates two files during the validation:

  • DataMigrationTool.log: Contains the set of process validation errors found in the collection. Fix all process errors found to proceed with your migration.
  • TryMatchOobProcesses.log: Lists for each project the target process model - Inheritance or Hosted XML. For projects that are set to target the Hosted XML process model, it explains why they're considered to be customized. You don't have to fix these errors, but they give you guidance what to do in case you want to migrate to the Inheritance process model. Once a collection gets migrated, you can migrate a project to an Inheritance process model.

Validate a team project collection

Since each team project collection corresponds to its own SQL database, the validation process examines various aspects of your collection, including:

  • Size of your collection database
  • Collation of the SQL database
  • Identities of users in the collection
  • Template customizations (process)

To start validation, use the migrator tool. We recommend running the migrator tool from one of the application tier (AT) servers in your Azure DevOps Server environment.

For specific command-line options, request help text using the following command:

	Migrator validate /help

The most common way to start validation is by specifying the URL of the team project collection with the following structure:

	Migrator validate /collection:http://localhost:8080/tfs/DefaultCollection

View validation warnings and errors

When the migrator tool completes, it generates log files and results displayed on the command prompt screen. If no errors occur and all validation checks pass, your team project collection is ready for the next phase. In case validation checks fail, review the log files to identify errors, and then address them.

Focus on the Migrator.log file, which contains essential details about the validation checks and helps you preserve customization. The other files correspond to specific validation errors based on their names. Search for the string "Validation - Starting validation of project 1." Each project is validated. Scan through all the projects and search for any lines that contain a prefix of [Error...

Also, the TryMatchOobProcesses.log lists errors related to projects that use Out-of-Box (OOB) processes (such as Agile, Scrum, or CMMI). If a project uses an OOB process without customizations, the project is included in the inherited model. Importantly, errors in this file don’t hinder the migration process.

Screenshot of the DataMigrationTool.log file generated by the Data Migration Tool.

For a list of validation errors, see Resolve validation errors. For each validation error, we provided the error number, description, and the method to resolve. Various error types might appear in the validation check logs. Seek assistance from your trained DevOps Partner, Microsoft Consulting Services, or Microsoft Premier Support for resolving encountered errors.

Resolve process template errors

The primary errors we find are process template issues. These issues stem from either outdated team projects not incorporating Azure DevOps Server's latest features or unsupported customizations by Azure DevOps Services. But, Azure DevOps Services does support a range of customizations, and the validation only flags those requiring resolution premigration. The Data Migration Tool performs a comprehensive check of your templates for Azure DevOps Services compatibility, but some modifications might be necessary.

  • Customized process templates or outdated templates might cause process validation errors during migration.
  • If you use an OOB Agile, Scrum, or CMMI process, check the TryMatchOobProcesses.log for errors. Error-free projects map to OOB processes.
  • Some customizations don’t work in Azure DevOps Services. Review the supported customization list.
  • For projects using older templates, run the Configure Features Wizard to update templates with recent features and reduce error count.
  • Ensure witadmin is available on the machine where you fix process errors. It’s essential for making changes to process templates.

Consider the following tools for resolving process errors:

  • Utilize the witadmin.exe command-line tool included with Visual Studio installations. Detailed technical documentation on addressing these errors is available at this link.
  • Automate exporting process templates for each team project using an undocumented migrator tool command: Migrator validates /collection:http://localhost:8080/tfs/DefaultCollection /SaveProcesses.
  • Explore the TFS Team Project Manager on GitHub (link). It allows you to compare team projects with known process templates, including out-of-the-box templates.

To fix the errors, change the XML syntax and apply the changes back to the project.

Tip

We recommend that you modify the XML manually, rather than using TFS Power Tools.

To get the process template from the project, add the /SaveProcesses parameter when you run the Data Migration Tool command.

Migrator validate /collection:{collection URL} /tenantDomainName:{name} /region:{region} /SaveProcesses

This command extracts the XML from the project and places it into the same folder as the logs. Extract the zip files to your local machine so that you can edit the files.

Now, fix the XML. Use the logs from the DataMigrationTool.log file to determine the errors for each project.

Screenshot of Process logging file generated by the Data Migration Tool.

Some errors require you to do use a witadmin changefield command. Changing a field name is the most common example. To save yourself some time, we recommend you run the witadmin changefield command and then rerun the Data Migration Tool. Doing so re-exports the XML with the corrected names. Otherwise, manually fix the fields in the XML syntax as well.

Once you make a fix, apply the changes back to the Azure DevOps Server. Depending on the changes you made, you need to run one or more witadmin commands. We created a PowerShell script to automate this process. The script contains all of the witadmin commands needed to confirm the entire process.

You can get the scripts at Process Customization Scripts. Use the import/ConformProject.ps1 script.

.\conformproject.ps1 "<collection url>" "<project name>" "<process template folder>"

When the script completes, rerun the Data Migration Tool to validate the collection. Follow steps 1 through 3 until the Data Migration Tool generates no more validation errors.

Screenshot of conform project process in PowerShell.

Tip

If you're new to XML and witadmin, we suggest you make one fix at a time and then conform. Continue this loop until all errors are resolved.

Update to a system process

If you began with an older version of Azure DevOps Server, your projects likely use an older process template. If these projects weren't updated using the Configure Features Wizard, the Data Migration Tool detects process errors. In rare cases, even the wizard might not resolve old process-related issues.

You might receive some of the following sample error messages:

Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element PortfolioBacklog is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element BugWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackRequestWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackResponseWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Team.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField RemainingWork.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Order.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Effort.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Activity.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationStartInformation.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationLaunchInstructions.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationType.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF400572: The Project Process Settings must be configured for this feature to be used.

If you didn't customize your project (for example, added fields, work item types, and so on.), fixing these errors is straightforward. But, if you customized your process, this approach doesn't suffice. You need to manually adjust the process templates to preserve your customizations from being overwritten.

Do the following steps, for each project, to align your process:

  1. Identify the initial process your project started with (Scrum, Agile, or CMMI).
  2. Visit the Process Customization Scripts on GitHub and download the repository.
  3. Focus on the contents in the Migration folder.
  4. Utilize the following ConformProject.ps1 script to align a project of your choice with the Agile system process. This action updates the entire project to be Agile.
.\ConformProject.ps1 "<collection url>" "<project name>" "c:\process-customization-scripts\import\agile"

Common validation errors

VS402841: Field X in work item type Bug has syncnamechanges=false but has rules making it an identity field. Identity fields must have syncnamechanges=true. Please update your process template to include this change.

In Azure DevOps Services, we added a rule so that every identity field must have the syncnamechanges=true attribute. In Azure DevOps Server that rule doesn't apply. Therefore, the Data Migration Tool identifies this as an issue. Making this change on Azure DevOps Server on-premises doesn't cause any harm.

Run the witadmin changefield command. Syntax for the command looks like the following example.

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /syncnamechanges:true

For more information on the witadmin changefield command, see Manage work item fields.

TF402556: For field System.IterationId to be well defined, you must name it Iteration ID and set its type to Integer.

This error is often associated with outdated process templates. To address it, you can run the Configure Features Wizard for each project. Alternatively, you might execute the following command to automate the process.

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /name:newname

TF402571: Required element BugWorkItems is missing from Process Configuration.

This error is commonly seen when a process wasn't updated for some time. To fix it, run the Configure Features Wizard for each project.

TF402564: You've defined XX global lists. Only 64 are allowed

Azure DevOps Services natively supports 64 global lists. This error typically arises when there's an extensive number of build pipelines, as each new pipeline creates a global list named Builds - TeamProjectName. To resolve this error, remove any outdated global lists.

Repeat validation checks

In each iteration, address errors and conduct validation checks to resolve them, as indicated by the validation log files. Persist with this cycle until all errors are rectified and you receive confirmation that the collection validation checks are successful.

Next steps

Prepare for test run