Field Calculation Map

Purpose and Use Cases

This map is typically used when:

• You want to calculate Custom.EstimatedCost as EstimatedHours × HourlyRate
• You need to convert days to hours or apply rounding
• You wish to assign weights to different numeric fields and store a computed score
• Your source project uses different naming or units, and you want to normalise during migration

Options

How NCalc Expressions Work

The NCalc engine supports:

• Standard arithmetic: +, -, *, /
• Logical operations: &&, ||, ==, !=
• Functions: Pow(a, b), Min(a, b), Max(a, b), Abs(x), etc.
• Conditional evaluation using if(condition, trueValue, falseValue)

Example Expression:

[effort] * [rate]

This multiplies the values of the two fields Custom.EstimatedHours and Custom.HourlyRate.

Behaviour and Execution

• The field map executes during work item migration and before saving to the target.
• It applies to the latest revision only unless otherwise configured.
• The calculated value overwrites any existing value in targetField.

Field Resolution Rules

• Each variable in the expression (e.g. [effort]) must be defined in parameters.
• Values are pulled from the source work item using the mapped reference names.
• If a referenced field is missing or null, the expression evaluation may fail.
• Non-numeric fields will cause an evaluation error.

Practices

• Use consistent naming conventions for parameters to avoid confusion.
• Log intermediate values when troubleshooting expression evaluation.
• Always test with a sample dataset using run-local before production use.
• Use ApplyTo to limit the map to only relevant work item types.

Limitations

• Only works with numeric source fields.
• Errors during evaluation are not recoverable mid-run unless caught at validation.
• Does not support cross-work-item calculations.

Samples

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "CommonTools": {
      "FieldMappingTool": {
        "FieldMaps": [
          {
            "ApplyTo": [
              "Bug",
              "Task"
            ],
            "expression": "[effort] * [rate]",
            "FieldMapType": "FieldCalculationMap",
            "parameters": {
              "effort": "Custom.EstimatedHours",
              "rate": "Custom.HourlyRate"
            },
            "targetField": "Custom.EstimatedCost"
          }
        ]
      }
    }
  }
}

Defaults

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

Classic

{
  "$type": "FieldCalculationMapOptions",
  "expression": "[effort] * [rate]",
  "parameters": {
    "effort": "Custom.EstimatedHours",
    "rate": "Custom.HourlyRate"
  },
  "targetField": "Custom.EstimatedCost",
  "ApplyTo": [
    "*",
    "Bug",
    "Task"
  ]
}

Metadata