Field Mapping Tool

Tool for applying field mapping transformations to work items during migration, supporting various field mapping strategies like direct mapping, regex transformations, and value lookups.

Last updated: June 25, 2025 | Edit this page | Discuss this page

Tool for applying field mapping transformations to work items during migration, supporting various field mapping strategies like direct mapping, regex transformations, and value lookups.

top

Options

Parameter Type Description Default Value
Enabled Boolean If set to true then the tool will run. Set to false and the processor will not run. missing XML code comments
FieldMaps List Gets or sets the list of field mapping configurations to apply. missing XML code comments
top

Samples

top

Sample

Sample 

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "Enabled": "True",
        "FieldMaps": [
          {
            "ApplyTo": [
              "Bug",
              "Task"
            ],
            "expression": "[effort] * [rate]",
            "FieldMapType": "FieldCalculationMap",
            "parameters": {
              "effort": "Custom.EstimatedHours",
              "rate": "Custom.HourlyRate"
            },
            "targetField": "Custom.EstimatedCost"
          },
          {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "FieldMapType": "FieldMergeMap",
            "formatExpression": "{0} \n {1}",
            "sourceFields": [
              "Custom.FieldA",
              "Custom.FieldB"
            ],
            "targetField": "Custom.FieldC"
          },
          {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "defaultValue": "New",
            "FieldMapType": "FieldValueMap",
            "sourceField": "System.State",
            "targetField": "System.State",
            "valueMapping": {
              "Active": "InProgress",
              "Closed": "Done",
              "Resolved": "InProgress"
            }
          },
          {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "defaultValue": "42",
            "FieldMapType": "FieldToFieldMap",
            "sourceField": "Microsoft.VSTS.Common.BacklogPriority",
            "targetField": "Microsoft.VSTS.Common.StackRank"
          }
        ],
        "FieldMapSamples": {
          "FieldCalculationMap": {
            "ApplyTo": [
              "Bug",
              "Task"
            ],
            "expression": "[effort] * [rate]",
            "FieldMapType": "FieldCalculationMap",
            "parameters": {
              "effort": "Custom.EstimatedHours",
              "rate": "Custom.HourlyRate"
            },
            "targetField": "Custom.EstimatedCost"
          },
          "FieldClearMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "targetField": "Custom.FieldC"
          },
          "FieldLiteralMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "targetField": "Custom.SomeField",
            "value": "New field value"
          },
          "FieldMergeMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "formatExpression": "{0} \n {1}",
            "sourceFields": [
              "Custom.FieldA",
              "Custom.FieldB"
            ],
            "targetField": "Custom.FieldC"
          },
          "FieldToFieldMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "defaultValue": "42",
            "sourceField": "Microsoft.VSTS.Common.BacklogPriority",
            "targetField": "Microsoft.VSTS.Common.StackRank"
          },
          "FieldToFieldMultiMap": {
            "ApplyTo": [
              "SomeWorkItemType",
              "SomeOtherWorkItemType"
            ],
            "SourceToTargetMappings": {
              "SourceField1": "TargetField1",
              "SourceField2": "TargetField2"
            }
          },
          "FieldToTagFieldMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "formatExpression": "{0} <br/><br/><h3>Acceptance Criteria</h3>{1}",
            "sourceFields": [
              "System.Description",
              "Microsoft.VSTS.Common.AcceptanceCriteria"
            ],
            "targetField": "System.Description"
          },
          "FieldToTagMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "formatExpression": "ScrumState:{0}",
            "sourceField": "System.State"
          },
          "FieldValueMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "defaultValue": "StateB",
            "sourceField": "System.State",
            "targetField": "System.State",
            "valueMapping": {
              "StateA": "StateB"
            }
          },
          "FieldValueToTagMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "formatExpression": "{0}",
            "pattern": "Yes",
            "sourceField": "Microsoft.VSTS.CMMI.Blocked"
          },
          "MultiValueConditionalMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "sourceFieldsAndValues": {
              "Field1": "Value1",
              "Field2": "Value2"
            },
            "targetFieldsAndValues": {
              "Field1": "Value1",
              "Field2": "Value2"
            }
          },
          "RegexFieldMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "pattern": "PRODUCT \\d{4}.(\\d{1})",
            "replacement": "$1",
            "sourceField": "COMPANY.PRODUCT.Release",
            "targetField": "COMPANY.DEVISION.MinorReleaseVersion"
          },
          "targetFieldsAndValues": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "targetField": "Custom.ReflectedWorkItemId"
          },
          "TreeToTagMap": {
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "timeTravel": "1",
            "toSkip": "3"
          }
        }
      }
    }
  }
}
top

Defaults

Defaults 

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "Enabled": "False",
        "FieldMapDefaults": {
          "ApplyTo": [
            "*"
          ]
        },
        "FieldMaps": null
      }
    }
  }
}
top

Classic

Classic 

{
  "$type": "FieldMappingToolOptions",
  "Enabled": true,
  "FieldMaps": []
}
top

Metadata

Metadata

Class Name
FieldMappingTool
Status
Missing XML Code Comments
Processing Target
missing XML code comments
Type
Tools
Previous Tools
Next String Manipulator Tool
Project Information
Azure DevOps Marketplace
Visual Studio Marketplace Stars View Extension
YouTube Channel
Youtube Subscribers Youtube Views
Maintainer

Created and maintained by Martin Hinshelwood of nkdagility.com

Documentation Versions
Production Azure DevOps Migration Tools Release Version
Preview Azure DevOps Migration Tools Preview Version
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