Tfs User Mapping Tool

The TfsUserMappingTool is used to map users from the source to the target system. Run it with the ExportUsersForMappingContext to create a mapping file then with WorkItemMigrationContext to use the mapping file to update the users in the target system as you migrate the work items.

Last updated: July 28, 2025 | Edit this page | Discuss this page

The TfsUserMappingTool is used to map users from the source to the target system. Run it with the ExportUsersForMappingContext to create a mapping file then with WorkItemMigrationContext to use the mapping file to update the users in the target system as you migrate the work items.

top

Options

Parameter
Type
Description
Default Value
Parameter:
Enabled
Type:
Boolean
Description:
If set to true then the tool will run. Set to false and the processor will not run.
Default Value:
missing XML code comments
Parameter:
IdentityFieldsToCheck
Type:
List
Description:
This is a list of the Identiy fields in the Source to check for user mapping purposes. You should list all identiy fields that you want to map.
Default Value:
missing XML code comments
Parameter:
MatchUsersByEmail
Type:
Boolean
Description:
By default, users in source are mapped to target users by their display name. If this is set to true, then the users will be mapped by their email address first. If no match is found, then the display name will be used.
Default Value:
missing XML code comments
Parameter:
ProjectCollectionValidUsersGroupName
Type:
String
Description:
This is the regionalized “Project Collection Valid Users” group name. Default is “Project Collection Valid Users”.
Default Value:
missing XML code comments
Parameter:
SkipValidateAllUsersExistOrAreMapped
Type:
Boolean
Description:
When set to true, this setting will skip a validation that all users exists or mapped
Default Value:
missing XML code comments
Parameter:
UserMappingFile
Type:
String
Description:
This is the file that will be used to export or import the user mappings. Use the ExportUsersForMapping processor to create the file.
Default Value:
missing XML code comments
top

Samples

top

Sample

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "TfsUserMappingTool": {
        "Enabled": "True",
        "IdentityFieldsToCheck": [
          "System.AssignedTo",
          "System.ChangedBy",
          "System.CreatedBy",
          "Microsoft.VSTS.Common.ActivatedBy",
          "Microsoft.VSTS.Common.ResolvedBy",
          "Microsoft.VSTS.Common.ClosedBy"
        ],
        "UserMappingFile": "C:\\temp\\userExport.json"
      }
    }
  }
}
top

Defaults

Defaults

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "TfsUserMappingTool": {
        "Enabled": "False",
        "IdentityFieldsToCheck": [
          "System.AssignedTo",
          "System.ChangedBy",
          "System.CreatedBy",
          "Microsoft.VSTS.Common.ActivatedBy",
          "Microsoft.VSTS.Common.ResolvedBy",
          "Microsoft.VSTS.Common.ClosedBy"
        ],
        "UserMappingFile": "C:\\temp\\userExport.json"
      }
    }
  }
}
top

Classic

Classic

{
  "$type": "TfsUserMappingToolOptions",
  "Enabled": true,
  "IdentityFieldsToCheck": [
    "System.AssignedTo",
    "System.ChangedBy",
    "System.CreatedBy",
    "Microsoft.VSTS.Common.ActivatedBy",
    "Microsoft.VSTS.Common.ResolvedBy",
    "Microsoft.VSTS.Common.ClosedBy",
    "System.AssignedTo",
    "System.ChangedBy",
    "System.CreatedBy",
    "Microsoft.VSTS.Common.ActivatedBy",
    "Microsoft.VSTS.Common.ResolvedBy",
    "Microsoft.VSTS.Common.ClosedBy"
  ],
  "UserMappingFile": "C:\\temp\\userExport.json",
  "MatchUsersByEmail": false,
  "ProjectCollectionValidUsersGroupName": "Project Collection Valid Users"
}
top

Metadata

top

Schema

This is the JSON schema that defines the structure and validation rules for this configuration.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://devopsmigration.io/schema/schema.tools.tfsusermappingtool.json",
  "title": "TfsUserMappingTool",
  "description": "The TfsUserMappingTool is used to map users from the source to the target system. Run it with the ExportUsersForMappingContext to create a mapping file then with WorkItemMigrationContext to use the mapping file to update the users in the target system as you migrate the work items.",
  "type": "object",
  "properties": {
    "enabled": {
      "description": "If set to `true` then the tool will run. Set to `false` and the processor will not run.",
      "type": "boolean"
    },
    "identityFieldsToCheck": {
      "description": "This is a list of the Identiy fields in the Source to check for user mapping purposes. You should list all identiy fields that you want to map.",
      "type": "array"
    },
    "matchUsersByEmail": {
      "description": "By default, users in source are mapped to target users by their display name. If this is set to true, then the users will be mapped by their email address first. If no match is found, then the display name will be used.",
      "type": "boolean"
    },
    "projectCollectionValidUsersGroupName": {
      "description": "This is the regionalized \"Project Collection Valid Users\" group name. Default is \"Project Collection Valid Users\".",
      "type": "string"
    },
    "skipValidateAllUsersExistOrAreMapped": {
      "description": "When set to true, this setting will skip a validation that all users exists or mapped",
      "type": "boolean"
    },
    "userMappingFile": {
      "description": "This is the file that will be used to export or import the user mappings. Use the ExportUsersForMapping processor to create the file.",
      "type": "string"
    }
  }
}
Project Information
Azure DevOps Marketplace
YouTube Channel
Maintainer

Created and maintained by Martin Hinshelwood of nkdagility.com

Getting Support
Community Support
Questions & Discussions

The first place to look for usage, configuration, and general help.

Commercial Support

We provide training, ad-hoc support, and full service migrations through our professional services.

Azure DevOps Migration Services
Documentation