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: July 28, 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
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:
FieldMaps
Type:
List
Description:
Gets or sets the list of field mapping configurations to apply.
Default Value:
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

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.fieldmappingtool.json",
  "title": "FieldMappingTool",
  "description": "Tool for applying field mapping transformations to work items during migration, supporting various field mapping strategies like direct mapping, regex transformations, and value lookups.",
  "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"
    },
    "fieldMaps": {
      "description": "Gets or sets the list of field mapping configurations to apply.",
      "type": "array",
      "prefixItems": {
        "anyOf": [
          {
            "title": "FieldCalculationMap",
            "description": "Performs mathematical calculations on numeric fields using NCalc expressions during migration.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "expression": {
                "description": "Gets or sets the NCalc expression to evaluate. Variables in the expression should be enclosed in square brackets (e.g., \"[x]*2\").",
                "type": "string",
                "default": "null"
              },
              "parameters": {
                "description": "Gets or sets a dictionary mapping variable names used in the expression to source field reference names.",
                "type": "object",
                "default": "{}"
              },
              "targetField": {
                "description": "Gets or sets the target field reference name where the calculated result will be stored.",
                "type": "string",
                "default": "null"
              }
            }
          },
          {
            "title": "FieldClearMap",
            "description": "Clears a target field by setting its value to null, useful for removing data from specific fields during migration.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "targetField": {
                "description": "Gets or sets the name of the target field to be cleared/set to null during work item migration.",
                "type": "string"
              }
            }
          },
          {
            "title": "FieldLiteralMap",
            "description": "Maps a literal (static) value to a target field, useful for setting constant values across all migrated work items.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "targetField": {
                "description": "Gets or sets the name of the target field that will be set to the specified literal value.",
                "type": "string"
              },
              "value": {
                "description": "Gets or sets the literal value that will be assigned to the target field during migration.",
                "type": "string"
              }
            }
          },
          {
            "title": "FieldMergeMap",
            "description": "Merges values from multiple source fields into a single target field using a specified format template.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "formatExpression": {
                "description": "missing XML code comments",
                "type": "string"
              },
              "sourceFields": {
                "description": "missing XML code comments",
                "type": "array"
              },
              "targetField": {
                "description": "missing XML code comments",
                "type": "string"
              }
            }
          },
          {
            "title": "FieldSkipMap",
            "description": "Skips field mapping for a specific target field, effectively leaving the field unchanged during migration.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "targetField": {
                "description": "Gets or sets the name of the target field that should be skipped during migration, resetting it to its original value.",
                "type": "string"
              }
            }
          },
          {
            "title": "FieldToFieldMap",
            "description": "Maps the value from a source field to a target field directly, with optional default value substitution for empty or null values.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "defaultValue": {
                "description": "Gets or sets the default value to use when the source field is empty or null.",
                "type": "string"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "sourceField": {
                "description": "Gets or sets the name of the source field to copy data from during migration.",
                "type": "string"
              },
              "targetField": {
                "description": "Gets or sets the name of the target field to copy data to during migration.",
                "type": "string"
              }
            }
          },
          {
            "title": "FieldToFieldMultiMap",
            "description": "missing XML code comments",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "sourceToTargetMappings": {
                "description": "missing XML code comments",
                "type": "object"
              }
            }
          },
          {
            "title": "FieldToTagFieldMap",
            "description": "missing XML code comments",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "formatExpression": {
                "description": "missing XML code comments",
                "type": "string"
              },
              "sourceField": {
                "description": "missing XML code comments",
                "type": "string"
              }
            }
          },
          {
            "title": "FieldValueMap",
            "description": "Maps field values based on a lookup table, allowing specific source values to be translated to different target values.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "defaultValue": {
                "description": "Gets or sets the default value to use when no mapping is found for the source field value.",
                "type": "string"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "sourceField": {
                "description": "Gets or sets the name of the source field to read values from during migration.",
                "type": "string"
              },
              "targetField": {
                "description": "Gets or sets the name of the target field to write mapped values to during migration.",
                "type": "string"
              },
              "valueMapping": {
                "description": "Gets or sets the dictionary that maps source field values to target field values. Key is the source value, value is the target value.",
                "type": "object"
              }
            }
          },
          {
            "title": "MultiValueConditionalMap",
            "description": "missing XML code comments",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "sourceFieldsAndValues": {
                "description": "missing XML code comments",
                "type": "object"
              },
              "targetFieldsAndValues": {
                "description": "missing XML code comments",
                "type": "object"
              }
            }
          },
          {
            "title": "RegexFieldMap",
            "description": "Applies regular expression transformations to map values from a source field to a target field using pattern matching and replacement.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "pattern": {
                "description": "Gets or sets the regular expression pattern to match against the source field value.",
                "type": "string"
              },
              "replacement": {
                "description": "Gets or sets the replacement pattern that defines how matched groups should be used to construct the target value.",
                "type": "string"
              },
              "sourceField": {
                "description": "Gets or sets the name of the source field to read data from and apply regex pattern matching.",
                "type": "string"
              },
              "targetField": {
                "description": "Gets or sets the name of the target field to write the regex-transformed data to.",
                "type": "string"
              }
            }
          },
          {
            "title": "TreeToTagFieldMap",
            "description": "Maps work item area path or iteration path hierarchies to tags, allowing tree structures to be represented as flat tag collections.",
            "type": "object",
            "properties": {
              "applyTo": {
                "description": "A list of Work Item Types that this Field Map will apply to. If the list is empty it will apply to all Work Item Types. You can use \"*\" to apply to all Work Item Types.",
                "type": "array"
              },
              "enabled": {
                "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                "type": "boolean"
              },
              "timeTravel": {
                "description": "Gets or sets the number of months to travel back in time when looking up historical area path values. Use 0 for current values.",
                "type": "integer"
              },
              "toSkip": {
                "description": "Gets or sets the number of levels to skip from the root when converting area path hierarchy to tags. For example, if set to 2, \"ProjectName\\Level1\\Level2\\Level3\" would skip \"ProjectName\\Level1\" and start from \"Level2\".",
                "type": "integer"
              }
            }
          }
        ]
      }
    }
  }
}
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