Field Literal Map

Overview

The Field Literal Map is one of the simplest and most straightforward field maps available in the Azure DevOps Migration Tools. It assigns a predefined static value to a target field on all work items that match the specified criteria, regardless of the source field values.

This field map is particularly useful when you need to standardize certain field values across all migrated work items or when the target system requires specific values that don’t exist in the source system.

How It Works

The Field Literal Map operates with simple logic:

1. Configuration: Defines a static value and target field during setup
2. Execution: For each matching work item, sets the target field to the specified literal value
3. Overwrite: Replaces any existing value in the target field with the configured literal value

Use Cases

This field map is commonly used for:

• Default State Assignment: Setting all migrated work items to a specific state (e.g., “New” or “Imported”)
• Organizational Standards: Applying company-specific field values across all work items
• Process Compliance: Ensuring required fields have valid default values in the target system
• Batch Tagging: Adding consistent tags or labels to identify migrated work items
• Field Initialization: Setting default values for custom fields that don’t exist in the source
• Area Path Defaults: Assigning work items to a specific area when source areas don’t map directly

Configuration Structure

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "FieldMaps": [
          {
            "FieldMapType": "FieldLiteralMap",
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "targetField": "Custom.SomeField",
            "value": "New field value"
          }
        ]
      }
    }
  }
}

Defaults

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

Basic Examples

Setting a Default State

{
  "FieldMapType": "FieldLiteralMap",
  "ApplyTo": ["Bug", "Task", "User Story"],
  "value": "New",
  "targetField": "System.State"
}

Adding Migration Tags

{
  "FieldMapType": "FieldLiteralMap",
  "ApplyTo": ["*"],
  "value": "Migrated-2024",
  "targetField": "System.Tags"
}

Setting Default Area Path

{
  "FieldMapType": "FieldLiteralMap",
  "ApplyTo": ["*"],
  "value": "MyProject\\Imported Items",
  "targetField": "System.AreaPath"
}

Assigning Default Priority

{
  "FieldMapType": "FieldLiteralMap",
  "ApplyTo": ["Bug"],
  "value": "2",
  "targetField": "Microsoft.VSTS.Common.Priority"
}

Data Type Support

The Field Literal Map can work with various data types:

String Values

• Text fields, states, area paths, iteration paths
• Tags (note: tags are typically additive, so consider existing values)

Numeric Values

• Priority, severity, effort, and other numeric fields
• Values should be provided as strings in the configuration

Boolean Values

• True/false fields should be specified as “True” or “False” strings

Date Values

• ISO 8601 format recommended for date fields
• Example: “2024-01-15T00:00:00Z”

Best Practices

Value Validation

• Ensure the literal value is valid for the target field type
• Verify that state values exist in the target work item type definition
• Check that area paths and iteration paths exist in the target project

Strategic Application

• Use ApplyTo to target specific work item types when appropriate
• Consider the impact of overwriting existing field values
• Test with a small subset before applying to all work items

Field Compatibility

• Verify target fields exist in the destination work item types
• Ensure field values comply with any validation rules in the target system
• Consider field length limitations for string values

Considerations and Limitations

Value Overwriting

The Field Literal Map always overwrites the target field value, regardless of existing content. If you need to preserve existing values, consider using conditional field maps instead.

Field Validation

The target system’s field validation rules still apply. Invalid values will cause migration errors.

Performance

Field Literal Maps are highly performant since they don’t require complex logic or data transformation.

Error Handling

The field map includes basic validation:

• Configuration Validation: Ensures the target field is specified
• Runtime Execution: Direct field assignment with minimal error handling
• Field Existence: Target field must exist on the work item type

Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://devopsmigration.io/schema/schema.fieldmaps.fieldliteralmap.json",
  "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"
    }
  }
}