Field Value To Tag Map

The Field Value To Tag Map adds a tag to the target work item when a source field’s value matches a regular expression, formatted the way you choose.

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

Overview

The Field Value To Tag Map turns a source field’s value into a tag on the target work item, but only when the value matches a pattern. Use it to keep a meaning that the target process has no field for, such as a Blocked flag, as a tag you can query.

missing XML code comments

top

How It Works

For each work item it applies to:

  1. If the source work item does not have sourceField, or its value is null, nothing happens. An empty string is not skipped.
  2. If pattern is set, the value must match it as a regular expression. If pattern is empty, any non-null value matches, including an empty string: with formatExpression set to Blocked, an empty field still adds the Blocked tag. Use a pattern such as .+ to skip empty values.
  3. The tag is formatExpression with the value in place of {0}. If formatExpression is empty, the tag is the value itself.
  4. The tag is added to the target work item’s existing tags. Duplicate tags are removed, and the tags are only written if they changed.

In configuration, set FieldMapType to FieldValueToTagMap.

top

Use Cases

  • Flags: tag work items whose Microsoft.VSTS.CMMI.Blocked is Yes.
  • Selected states or categories: tag only the values you care about, for example Status: Active and Status: Resolved.
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:
formatExpression
Type:
String
Required:
false
Description:
missing XML code comments
Default:
missing XML code comments
Parameter:
pattern
Type:
String
Required:
false
Description:
missing XML code comments
Default:
missing XML code comments
Parameter:
sourceField
Type:
String
Required:
false
Description:
missing XML code comments
Default:
missing XML code comments
top

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "FieldMaps": [
          {
            "FieldMapType": "FieldValueToTagMap",
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "sourceField": "Microsoft.VSTS.CMMI.Blocked",
            "pattern": "Yes",
            "formatExpression": "{0}"
          }
        ]
      }
    }
  }
}
top

Defaults

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

Basic Examples

top

Tag blocked work items

{
  "FieldMapType": "FieldValueToTagMap",
  "ApplyTo": ["*"],
  "sourceField": "Microsoft.VSTS.CMMI.Blocked",
  "pattern": "Yes",
  "formatExpression": "Blocked"
}
top

Tag selected values with a prefix

{
  "FieldMapType": "FieldValueToTagMap",
  "ApplyTo": ["Bug"],
  "sourceField": "System.State",
  "pattern": "(Active|Resolved)",
  "formatExpression": "Status: {0}"
}
top

Good Practices

  • Anchor the pattern (^Yes$) when a partial match would tag too much: the pattern matches anywhere in the value, and the match is case-sensitive.
  • To tag every value of a field, use the Field To Tag Field Map instead.
top

Troubleshooting

  • No tag appears: check that the field reference name in sourceField is the source’s, that the work item type is in ApplyTo, and that the value matches pattern.
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.fieldvaluetotagmap.json",
  "title": "FieldValuetoTagMap",
  "description": "missing XML code comments",
  "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"
    },
    "formatExpression": {
      "description": "missing XML code comments",
      "type": [
        "string",
        "null"
      ]
    },
    "pattern": {
      "description": "missing XML code comments",
      "type": [
        "string",
        "null"
      ]
    },
    "sourceField": {
      "description": "missing XML code comments",
      "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