Skip to the content.

Server Configuration and Requirements

There are some requirements that you will need to meet in order to use the tool against your TFS or VSTS server. The VSTS Bulk Data Editor uses 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 TFS 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 VSTS targets.

Migration State

In order to store the state for the migration you need to use a custom field, the ReflectedWorkItemId field. The way you add this depends on the platform you are using.

Azure DevOps

  1. Create a custom field called ReflectedWorkItemId of type Text (single line) by following this guide
  2. 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.

See MSDN for more details

Visual Studio Team Services (VSTS)

With the advent of the VSTS Migration Tool 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 VSTS Migration Tool that already had customisations then it will not allow creating an inherited process. You have to exit you customisation in a different manner:

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

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:

{
	"ChangeSetMappingFile": null,
	"Source": {
		...
		"ReflectedWorkItemIDFieldName": "TfsMigrationTool.ReflectedWorkItemId",
		...
	},
	"Target": {
		...
		"ReflectedWorkItemIDFieldName": "TfsMigrationTool.ReflectedWorkItemId",
		...
	},

    	...... other stuff

 	"Processors": [
		{
			...
			"WIQLQueryBit": "AND [TfsMigrationTool.ReflectedWorkItemId] = '' AND  [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] IN ('Shared Steps', 'Shared Parameter', 'Test Case', 'Requirement', 'Task', 'User Story', 'Bug')"
			...
		}
	],
	
	...... other stuff
    
}