Values Mapping.

Table of Contents


Purpose: This feature facilitates the transformation of source field values based on predefined mappings before they are updated in the target system. This capability is crucial for scenarios where source data needs to be adjusted to fit target system requirements, such as data type compatibility, data integrity, or specific business rules.

Use case: In data migration or synchronization, source field values sometimes require transformation to align with the target system's schema or business logic. For example, translated picklist labels in a source system might need to be mapped to their equivalent API values in the target system.

This feature offers two primary functionalities for handling data transformations:

  • useValuesMapping: This setting enables the transformation of field values based on a mapping table before they are updated in the target. It is particularly useful when data from CSV files or organizational sources needs to be transformed to meet the target specifications.

  • useCSVValuesMapping: This setting prepares raw CSV file data for migration by applying foundational transformations prior to the data migration process. This preliminary step is crucial for ensuring that CSV data is ready for subsequent migration activities.

These functionalities are complementary and can be activated simultaneously to perform both foundational and advanced transformations, ensuring a comprehensive and tailored data migration process.

Configuration and Basic Transformation

Transformations are defined in the ValueMapping.csv file, which should be located in the same directory as the export.json file. This file specifies how source values should be transformed before being uploaded to the target system.

Example of ValueMapping.csv Structure:

ObjectName FieldName RawValue Value
Case Reason Вопрос Question

Only values listed in the ValueMapping.csv file are transformed, with all other values remaining unchanged. To transform an empty source record, use #N/A as the RawValue.

Advanced Transformations

Regex Replacement

Regular expressions can be used for dynamic value transformations. Below is an example configuration that employs JS RegExp for value replacement:

ObjectName FieldName RawValue Value
Case TEST__c /(TheRegex)/ $1 has been replaced

JS Code Equivalent:

'TheRawFieldValue'.replace(new RegExp('(TheRegex)', 'gi'), 'REPLACE_$1');


  • TheRawFieldValue has been replaced


  • Ensure regex expressions are enclosed between slashes (e.g., /YOUR_REGEX/).
  • Combine regex expressions with other replacement definitions as needed.

JS Eval Replacement

The JS eval() function allows for executing JavaScript expressions to transform field values:

ObjectName FieldName RawValue Value
Account TEST__c DDMM eval(new Date().getDate() + '0' + (new Date().getMonth() + 1))

For 'DDMM':

  • Output might be '2807' (assuming the date is July 28).


To incorporate the original field value in your transformation, use the RAW_VALUE keyword within your eval() expression:

ObjectName FieldName RawValue Value
Account TEST__c Source value eval('RAW_VALUE was replaced')


  • 'Source value was replaced'


  • Expressions within the eval() function are evaluated as they are written. Ensure the JavaScript expression is correctly placed within the eval() function, using quotes only when necessary. For example:
    • To evaluate a string value: eval('RAW_VALUE is a string value')
    • To evaluate a boolean value: eval(!RAW_VALUE)

Key Considerations

  • When using the Fields Mapping feature along with Values Mapping, you must specify the field API name from the source organization as the FieldName, rather than a mapped one.
Last updated on 20th Apr 2024