Multi Value Conditional Map

Overview

The Multi Value Conditional Map provides advanced conditional mapping capabilities that allow you to transform field values based on complex criteria involving multiple source fields. This field map enables sophisticated business logic during migration, where the target value depends on combinations of source field values and conditional expressions.

This field map is essential when simple one-to-one mappings are insufficient and you need to implement business rules that consider multiple data points to determine the appropriate target value.

How It Works

The Multi Value Conditional Map evaluates conditions and applies transformations:

1. Condition Evaluation: Examines multiple source fields against defined conditions
2. Logic Processing: Applies conditional logic (AND, OR, NOT operations)
3. Value Determination: Selects the appropriate target value based on condition results
4. Target Assignment: Sets the target field with the determined value
5. Default Handling: Falls back to default value if no conditions match

Use Cases

This field map is ideal for:

• Business Rule Implementation: Applying complex organizational business logic during migration
• Multi-Field Dependencies: Creating mappings that depend on combinations of field values
• Priority Calculations: Determining priority based on multiple factors
• Status Derivation: Computing work item status from multiple source conditions
• Category Assignment: Assigning categories based on complex criteria
• Risk Assessment: Calculating risk levels from multiple input factors
• Compliance Mapping: Ensuring data meets regulatory requirements based on multiple conditions

Configuration Structure

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "FieldMaps": [
          {
            "FieldMapType": "MultiValueConditionalMap",
            "ApplyTo": [
              "SomeWorkItemType"
            ],
            "sourceFieldsAndValues": {
              "Field1": "Value1",
              "Field2": "Value2"
            },
            "targetFieldsAndValues": {
              "Field1": "Value1",
              "Field2": "Value2"
            }
          }
        ]
      }
    }
  }
}

Defaults

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

Basic Examples

Priority Based on Severity and Impact

{
  "FieldMapType": "MultiValueConditionalMap",
  "ApplyTo": ["Bug"],
  "conditions": [
    {
      "expression": "Severity = 'Critical' AND Impact = 'High'",
      "value": "1"
    },
    {
      "expression": "Severity = 'High' OR Impact = 'High'", 
      "value": "2"
    },
    {
      "expression": "Severity = 'Medium'",
      "value": "3"
    }
  ],
  "targetField": "Microsoft.VSTS.Common.Priority",
  "defaultValue": "4"
}

Category Assignment

{
  "FieldMapType": "MultiValueConditionalMap",
  "ApplyTo": ["Task"],
  "conditions": [
    {
      "expression": "AreaPath CONTAINS 'Frontend' AND TaskType = 'Development'",
      "value": "UI-Development"
    },
    {
      "expression": "AreaPath CONTAINS 'Backend' AND TaskType = 'Development'",
      "value": "API-Development" 
    },
    {
      "expression": "TaskType = 'Testing'",
      "value": "Quality-Assurance"
    }
  ],
  "targetField": "Custom.WorkCategory",
  "defaultValue": "General"
}

Condition Syntax

The field map supports various conditional operators and expressions:

Comparison Operators

• = or == - Equality
• != or <> - Inequality
• > - Greater than
• < - Less than
• >= - Greater than or equal
• <= - Less than or equal

Logical Operators

• AND - Logical AND
• OR - Logical OR
• NOT - Logical NOT

String Operations

• CONTAINS - Check if string contains substring
• STARTSWITH - Check if string starts with value
• ENDSWITH - Check if string ends with value

Value Types

• String values in single quotes: 'Active'
• Numeric values: 1, 2.5
• Boolean values: true, false
• Field references: FieldName

Advanced Scenarios

Complex Business Logic

{
  "FieldMapType": "MultiValueConditionalMap",
  "ApplyTo": ["User Story"],
  "conditions": [
    {
      "expression": "StoryPoints > 8 AND BusinessValue = 'High' AND Risk = 'Low'",
      "value": "Epic-Candidate"
    },
    {
      "expression": "StoryPoints <= 3 AND Effort = 'Small'",
      "value": "Quick-Win"
    },
    {
      "expression": "BusinessValue = 'High' AND (Risk = 'Medium' OR Risk = 'High')",
      "value": "High-Risk-High-Value"
    }
  ],
  "targetField": "Custom.WorkClassification", 
  "defaultValue": "Standard"
}

Multi-Criteria Status Mapping

{
  "FieldMapType": "MultiValueConditionalMap",
  "ApplyTo": ["*"],
  "conditions": [
    {
      "expression": "State = 'Closed' AND Reason = 'Completed'",
      "value": "Done"
    },
    {
      "expression": "State = 'Active' AND AssignedTo != ''",
      "value": "In Progress"
    },
    {
      "expression": "State = 'New' OR AssignedTo = ''",
      "value": "To Do"
    }
  ],
  "targetField": "Custom.WorkflowStatus",
  "defaultValue": "Unknown"
}

Performance Considerations

Condition Complexity

• More complex conditions require more processing time
• Consider the number of fields involved in conditions
• Optimize condition order for common cases first

Evaluation Order

• Conditions are evaluated in the order specified
• Place most likely conditions first for better performance
• Use specific conditions before general ones

Field Access

• Each field reference requires data access
• Minimize the number of fields referenced
• Cache field values when possible

Best Practices

Condition Design

• Use clear, readable condition expressions
• Test conditions with sample data before migration
• Document business logic behind each condition

Value Mapping

• Ensure target values are valid for the target field
• Use meaningful names for mapped values
• Test with various input combinations

Error Handling

• Always provide appropriate default values
• Handle null or missing field values gracefully
• Log condition evaluation results for debugging

Troubleshooting

Common Issues

• Field Not Found: Ensure all referenced fields exist
• Invalid Expressions: Verify condition syntax
• Type Mismatches: Check data types in comparisons
• Performance: Optimize complex condition logic

Debugging Tips

• Enable detailed logging to see condition evaluation
• Test with small data sets first
• Validate condition logic with sample scenarios

Integration Patterns

With Other Field Maps

• Use after Field Value Maps to work with transformed values
• Combine with Field To Field Maps for comprehensive mapping
• Coordinate with Field Clear Maps for cleanup operations

Sequential Processing

• Multiple conditional maps can be chained together
• Each map can refine values set by previous maps
• Order matters for dependent mappings

Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://devopsmigration.io/schema/schema.fieldmaps.multivalueconditionalmap.json",
  "title": "MultiValueConditionalMap",
  "description": "missing XML code comments",
  "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"
    },
    "sourceFieldsAndValues": {
      "description": "missing XML code comments",
      "type": "object"
    },
    "targetFieldsAndValues": {
      "description": "missing XML code comments",
      "type": "object"
    }
  }
}