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 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:

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.