Values Mapping.

Table of Contents

• Overview
• Configuration and Basic Transformation
• Advanced Transformations
  • Regex Replacement
  • JS Eval Replacement
  • RAW_VALUE Keyword
• Key Considerations

Overview ⇧

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 uses one active object-level switch:

• useValuesMapping: Enables transformation of field values using mapping rules from ValueMapping.csv before records are written to the target.

This means the mapping behavior is configured per object in export.json, but the actual value rules are stored in a single mapping CSV file. This design helps non-technical users maintain value conversions in one place without modifying script logic repeatedly.

Legacy compatibility:

• useCSVValuesMapping: Deprecated. Kept only for backward compatibility of older script configurations. For new and current configurations, always use useValuesMapping.

Notes:

• If you have older scripts with useCSVValuesMapping, keep them running as-is if needed, but use useValuesMapping in all new configurations.
• During migration from old scripts, update one object at a time and compare output CSV/report results to validate mappings.

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:

Notes:

• Only the values listed in the ValueMapping.csv file will be transformed; all other values will remain unchanged.
• To reset a field value to null, use #N/A as the Value.

Advanced Transformations ⇧

Regex Replacement ⇧

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

JS Code Equivalent:

'This is the longest street'.replace(new RegExp('\b(a|the) long[\w]*\b', 'gi'), 'a short');

Transformation examples using this RegExp:

This is the longest street -> This is a short street

This is a long hairstyle -> This is a short hairstyle

Notes:

• Ensure regex expressions are enclosed between slashes (e.g., /YOUR_REGEX/).
• You can 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:

For 'DDMM':

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

RAW_VALUE Keyword ⇧

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

Result:

• 'Source value was replaced'

Notes:

• 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.