Field Merge Map

Overview

The Field Merge Map combines values from multiple source fields into a single target field using a configurable format template. This powerful field map enables you to consolidate related information, combine separate data elements, or create formatted composite fields during migration.

This is particularly useful when migrating from systems where related information is stored in separate fields but needs to be combined in the target system, or when creating summary fields that incorporate multiple data points.

How It Works

The Field Merge Map follows a straightforward merging process:

1. Source Field Collection: Retrieves values from all specified source fields
2. Null Value Handling: Replaces null or missing values with empty strings
3. Value Array Creation: Builds an array of string values in the order of source fields
4. Format Application: Applies the format expression using standard string formatting
5. Target Assignment: Sets the target field with the formatted result

Use Cases

This field map is commonly used for:

• Contact Information: Combining separate name fields into full names
• Address Consolidation: Merging address components into complete addresses
• Description Enhancement: Combining multiple descriptive fields into comprehensive descriptions
• Summary Fields: Creating summary information from multiple data points
• Legacy Data Migration: Consolidating fields that were separate in legacy systems
• Reporting Fields: Creating formatted fields for reporting purposes
• User Display Names: Combining user information into display-friendly formats

Configuration Structure

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "FieldMaps": [
          {
            "FieldMapType": "FieldMergeMap",
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "formatExpression": "{0} \n {1}",
            "sourceFields": [
              "Custom.FieldA",
              "Custom.FieldB"
            ],
            "targetField": "Custom.FieldC"
          }
        ]
      }
    }
  }
}

Defaults

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

Basic Examples

Simple Name Combination

{
  "FieldMapType": "FieldMergeMap",
  "ApplyTo": ["*"],
  "sourceFields": [
    "Custom.FirstName", 
    "Custom.LastName"
  ],
  "targetField": "Custom.FullName",
  "formatExpression": "{0} {1}"
}

Detailed Description Merge

{
  "FieldMapType": "FieldMergeMap",
  "ApplyTo": ["Bug"],
  "sourceFields": [
    "System.Description",
    "Custom.StepsToReproduce", 
    "Custom.ExpectedResult"
  ],
  "targetField": "System.Description",
  "formatExpression": "{0}\n\nSteps to Reproduce:\n{1}\n\nExpected Result:\n{2}"
}

Address Consolidation

{
  "FieldMapType": "FieldMergeMap",
  "ApplyTo": ["*"],
  "sourceFields": [
    "Custom.Street",
    "Custom.City",
    "Custom.State",
    "Custom.ZipCode"
  ],
  "targetField": "Custom.FullAddress",
  "formatExpression": "{0}, {1}, {2} {3}"
}

Contact Information

{
  "FieldMapType": "FieldMergeMap",
  "ApplyTo": ["*"],
  "sourceFields": [
    "Custom.Email",
    "Custom.Phone"
  ],
  "targetField": "Custom.ContactInfo",
  "formatExpression": "Email: {0} | Phone: {1}"
}

Format Expression Syntax

The format expression uses standard .NET string formatting:

Basic Placeholders

• {0} - First source field value
• {1} - Second source field value
• {n} - nth source field value (zero-indexed)

Common Patterns

Simple Concatenation

formatExpression: "{0} {1}"

Labeled Format

formatExpression: "Name: {0}, Department: {1}"

Multi-line Format

formatExpression: "{0}\n\nAdditional Info:\n{1}"

Conditional-like Format

formatExpression: "{0} (Priority: {1}, Severity: {2})"

Data Handling

Null and Empty Values

• Null source field values are converted to empty strings
• Empty strings are preserved in the formatting
• Missing fields are treated as empty strings

Field Order

• Source fields are processed in the order specified in the sourceFields array
• Format placeholders correspond to array positions (0-indexed)
• Ensure format expression matches the number of source fields

Target Field Considerations

• Target field must be able to accept string values
• Consider target field length limitations
• Large merged content may be truncated

Best Practices

Format Design

• Use clear, readable format expressions
• Include appropriate separators and labels
• Consider how the merged content will be displayed

Field Selection

• Choose source fields that contain related information
• Ensure source fields exist on the specified work item types
• Consider field data types and content

Content Length

• Be aware of target field length restrictions
• Test with realistic data to ensure content fits
• Consider truncation strategies for long content

Performance Considerations

• Field merging is performed for each work item
• Complex format expressions may impact performance
• Consider the number of fields being merged

Common Scenarios

Legacy System Migration

When migrating from systems with separate contact fields:

{
  "FieldMapType": "FieldMergeMap",
  "ApplyTo": ["*"],
  "sourceFields": [
    "Custom.ContactFirstName",
    "Custom.ContactLastName",
    "Custom.ContactEmail",
    "Custom.ContactPhone"
  ],
  "targetField": "Custom.ContactInformation",
  "formatExpression": "{0} {1} - {2} | {3}"
}

Requirements Documentation

Combining multiple requirement fields:

{
  "FieldMapType": "FieldMergeMap",
  "ApplyTo": ["User Story"],
  "sourceFields": [
    "Custom.UserStory",
    "Custom.AcceptanceCriteria",
    "Custom.Notes"
  ],
  "targetField": "System.Description",
  "formatExpression": "User Story:\n{0}\n\nAcceptance Criteria:\n{1}\n\nNotes:\n{2}"
}

Error Handling

Field Validation

• Missing source fields are treated as empty strings
• No error is thrown for non-existent fields
• Target field must exist or assignment will fail

Format Validation

• Invalid format expressions may cause runtime errors
• Ensure placeholder count matches source field count
• Test format expressions with sample data

Schema

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