Tag Mapping Map

The Tag Mapping Map renames tags on the target work item from a list of source and target pairs, and keeps every other tag unchanged.

Last updated: November 18, 2026 | Edit this page | Discuss this page
top

Overview

The Tag Mapping Map renames tags on the way to the target: Bug-Bash can become BugBash, and every v1.x tag can become Legacy.

Renames tags on the target work item from a list of source → target pairs; tags that match no pair are kept unchanged.

top

How It Works

For each work item revision it applies to, after the tags have been copied:

  1. The target work item’s tags are split on ;. Spaces at the ends of each tag are trimmed, and empty or duplicate tags are removed.
  2. Each tag is checked against mappings in order. The first entry whose source matches renames it to target.
  3. A tag that matches no entry is kept unchanged.
  4. If a rename gives a tag that is already there, the duplicate is removed.

A source matches a tag in one of two ways:

  • Exact name: Bug-Bash matches the tag Bug-Bash only. Matching is case-sensitive, so it does not match bug-bash.
  • Pattern: a source starting with regex: is a .NET regular expression. The part of the tag it matches is replaced with target, so target can use groups such as $1. Anchor the pattern with ^ and $ to replace the whole tag.

An invalid pattern, an empty source or an empty target stops the migration at start-up with a message naming the entry. To remove tags, use the Tag Filter Map .

In configuration, set FieldMapType to TagMappingMap.

top

Use Cases

  • Tidying names: merge spellings such as Bug-Bash and Bugbash into one tag.
  • Restructuring: turn Sprint 12 into S12, or every v1.x release tag into Legacy.
top

Configuration Structure

top

Options

Parameter
Type
Required
Description
Default Value
Parameter:
ApplyTo
Type:
List
Required:
false
Description:
A list of Work Item Types that this Field Map will apply to. Use “*” to apply it to all Work Item Types. A field map with an empty list applies to no Work Item Types and never runs.
Default:
missing XML code comments
Parameter:
Enabled
Type:
Boolean
Required:
false
Description:
Not used: every configured field map runs for the work item types in ApplyTo. To turn a field map off, remove it from FieldMaps.
Default:
missing XML code comments
Parameter:
mappings
Type:
List
Required:
false
Description:
The renames, applied in order; the first source that matches a tag wins.
Default:
[]
top

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "FieldMaps": [
          {
            "FieldMapType": "TagMappingMap",
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "mappings": [
              {
                "source": "Bug-Bash",
                "target": "BugBash"
              },
              {
                "source": "regex:^v1\\..*$",
                "target": "Legacy"
              }
            ]
          }
        ]
      }
    }
  }
}
top

Defaults

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "FieldMaps": [
          {
            "FieldMapType": "TagMappingMap",
            "ApplyTo": [
              "*"
            ]
          }
        ]
      }
    }
  }
}
top

Basic Examples

top

Rename tags

{
  "FieldMapType": "TagMappingMap",
  "ApplyTo": ["*"],
  "mappings": [
    { "source": "Bug-Bash", "target": "BugBash" },
    { "source": "Bugbash", "target": "BugBash" }
  ]
}
top

Rename with a pattern

{
  "FieldMapType": "TagMappingMap",
  "ApplyTo": ["*"],
  "mappings": [
    { "source": "regex:^Sprint (\\d+)$", "target": "S$1" },
    { "source": "regex:^v1\\..*$", "target": "Legacy" }
  ]
}
top

Good Practices

  • Run the Tag Mapping Map before the Tag Filter Map , so the approved list only needs the new names. Maps with ApplyTo ["*"] run before type-specific maps whatever their configuration order, so give both maps the same ApplyTo; within one scope they run in configuration order.
  • A regex: rename that would give an empty tag (for example $1 when the group is empty) keeps the original tag.
  • Put specific entries before general patterns: the first entry that matches wins.
top

Troubleshooting

  • A tag is not renamed: check the spelling and case of source, and that no earlier entry matches the tag first. Renames are logged at Debug level as TagMappingMap: renamed tag.
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.fieldmaps.tagmappingmap.json",
  "title": "TagMappingMap",
  "description": "Renames tags on the target work item from a list of source → target pairs; tags that match no pair are kept unchanged.",
  "type": "object",
  "properties": {
    "ApplyTo": {
      "description": "A list of Work Item Types that this Field Map will apply to. Use \"*\" to apply it to all Work Item Types. A field map with an empty list applies to no Work Item Types and never runs.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      }
    },
    "Enabled": {
      "description": "Not used: every configured field map runs for the work item types in `ApplyTo`. To turn a field map off, remove it from `FieldMaps`.",
      "type": "boolean"
    },
    "mappings": {
      "description": "The renames, applied in order; the first `source` that matches a tag wins.",
      "type": [
        "array",
        "null"
      ],
      "default": [],
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "target": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}
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