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.
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.
How It Works
For each work item revision it applies to, after the tags have been copied:
- 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. - Each tag is checked against
mappingsin order. The first entry whosesourcematches renames it totarget. - A tag that matches no entry is kept unchanged.
- 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-Bashmatches the tagBug-Bashonly. Matching is case-sensitive, so it does not matchbug-bash. - Pattern: a
sourcestarting withregex:is a .NET regular expression. The part of the tag it matches is replaced withtarget, sotargetcan 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.
Use Cases
- Tidying names: merge spellings such as
Bug-BashandBugbashinto one tag. - Restructuring: turn
Sprint 12intoS12, or everyv1.xrelease tag intoLegacy.
Configuration Structure
topOptions
topSample
{
"MigrationTools": {
"Version": "16.0",
"CommonTools": {
"FieldMappingTool": {
"FieldMaps": [
{
"FieldMapType": "TagMappingMap",
"ApplyTo": [
"SomeWorkItemType"
],
"mappings": [
{
"source": "Bug-Bash",
"target": "BugBash"
},
{
"source": "regex:^v1\\..*$",
"target": "Legacy"
}
]
}
]
}
}
}
}Defaults
{
"MigrationTools": {
"Version": "16.0",
"CommonTools": {
"FieldMappingTool": {
"FieldMaps": [
{
"FieldMapType": "TagMappingMap",
"ApplyTo": [
"*"
]
}
]
}
}
}
}Basic Examples
topRename tags
{
"FieldMapType": "TagMappingMap",
"ApplyTo": ["*"],
"mappings": [
{ "source": "Bug-Bash", "target": "BugBash" },
{ "source": "Bugbash", "target": "BugBash" }
]
}
Rename with a pattern
{
"FieldMapType": "TagMappingMap",
"ApplyTo": ["*"],
"mappings": [
{ "source": "regex:^Sprint (\\d+)$", "target": "S$1" },
{ "source": "regex:^v1\\..*$", "target": "Legacy" }
]
}
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 sameApplyTo; within one scope they run in configuration order. - A
regex:rename that would give an empty tag (for example$1when the group is empty) keeps the original tag. - Put specific entries before general patterns: the first entry that matches wins.
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 asTagMappingMap: renamed tag.
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"
]
}
}
}
}
}
}In this article
Project Information
Azure DevOps Marketplace
Maintainer
Created and maintained by Martin Hinshelwood of nkdagility.com
Getting Support
Community Support
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