Server Configuration and Requirements
Article
4 minutes to read
2024-09-06 09:35:04 +0100
production
This page is in production and may include errors or omissions. Please check the discussions for any pending updates and changes to the content or to suggest your own changes.
There are some requirements that you will need to meet in order to use the tool against your TFS or VSTS server. The Azure DevOps Migration Tools use a flag to Bypass the Work Item rules engine and write data into TFS\VSTS that may not comply with the rules. For example you can write data directly into the Closed
state without starting at New
. This is very useful for migrations but requires some pre-requisites.
Bypass Rules
For on-premises instances you need to be part of the Project Collection Service Accounts
group. You can do this by calling the following command:
tfssecurity /g+ "Project Collection Service Accounts" n:domainusername ALLOW /server:http://myserver:8080/tfs
This is not required for Azure DevOps Service targets, but you do need to be a Collection Admin on the Target.
Migration State
In order to store the state for the migration you need to use a custom field, the ReflectedWorkItemId
field which needs added to the Target only. The way you add this depends on the platform you are using.
Azure DevOps
- Create a custom field called
ReflectedWorkItemId
of typeText (single line)
by following this guide - Add this custom field to all work item types to be migrated (e.g. Bug, User Story, Task, Test Case, etc)
Team Foundation Server (TFS)
Use the witadmin exportwitd
command to export each work item and add:
<FIELD name="ReflectedWorkItemId" refname="TfsMigrationTool.ReflectedWorkItemId" type="String" />
to the Fields section.
Then use witadmin importwitd
to re-import the customized work item type template.
Visual Studio Team Services (VSTS)
With the advent of the data migration tool for Azure DevOps there are potentially two ways you need to consider when customising a VSTS process template. It all depends how the Team Project was created.
Inherited Templates - the future
If you created the Team Project via the web based VSTS UI. You need to add a custom field through the VSTS UI to be able to use the tool.
The name you should use for the custom field on a VSTS instance is not TfsMigrationTool.ReflectedWorkItemId
as .(period) are not valid characters for field name. Instead just use ReflectedWorkItemId
but note that in the configuration.json
file the name you need to enter is NameOfYourCustomisedTemplate.ReflectedWorkItemId
. WhereNameOfYourCustomisedTemplate
is the name of your customised template, any spaces in the name will be replaced by _ (underscore).
Custom Templates
If you migrated a TPC to VSTS using the data migration tool for Azure DevOps that already had customisations then it will not allow creating an inherited process. You have to exit you customisation in a different manner:
- Export the current process (this is done from the same Account > Settings page where you do any process customisation in VSTS); this downloads the current customised process as a .ZIP file.
- Once you have the .ZIP file, unpack it and edit the work item type definitions as detailed above for an on-premises installation.
- Once the fields have been added then zip up the folder structure again and re-import it into your VSTS instance, where it will be applied to the Team Project it was exported from.
TIP: Checking the actual ‘ReflectedWorkItemIDFieldName’
If you are in any doubt over the full name in use for the ReflectedWorkItemIDFieldName
on either the source or target systems, it can vary based on the type of customisation, use the following process to confirm it
- Open Visual Studio, connect to the customised Team Project
- Via Team Explorer > Work, create a new work item query. Make sure the
ReflectedWorkItemId
is one of the output columns - Save the work item query as a file on your local PC
- Open the resulting file in a text editor and check the actual name, it should be in the form
NameOfYourCustomisedTemplate.ReflectedWorkItemId
orTfsMigrationTool.ReflectedWorkItemId
Editing the configuration
Once you have created the ReflectedWorkItemId
field and confirmed you have the correct full name for both, the Source and the Target, you will need to edit configuration.json
to match your values:
{
"Source": {
...
"ReflectedWorkItemIDFieldName": "TfsMigrationTool.ReflectedWorkItemId",
...
},
"Target": {
...
"ReflectedWorkItemIDFieldName": "TfsMigrationTool.ReflectedWorkItemId",
...
},
...... other stuff
],
...... other stuff
}