Values Mapping.

This feature allows to automatically modify certain source values according to the given mapping table before updating the Target.

Table of Contents

• Feature overview.
• Regex replacement.
• Js eval replacement.

Feature overview. ⇧

In some cases we get a source CSV file that could not be loaded directly into the target Org, because it contains raw data that need to be transformed into uploadable format prior the actual upload. Or sometimes you can have a source org contains data that should be transformed prior to writing to the Target.

The good example is when our CSV file contains picklist translated labels instead of their values, so we have to replace labels with values in order to construct well formatted source CSV.

For this use case the Plugin provides feature for automatic replacement of the source values before upload to the Target. It is optional feature that can be enabled for certain sobject by setting to true the parameter useCSVValuesMapping (for CSV file source) and useValuesMapping (for org source).

The value replacement is being performed according to the mapping table stored in the configuration CSV file called ValueMapping.csv. Put this file in the same directory as the export.json file.

The file should contain 4 predefined columns:

This single file provides mapping table for all sObjects and fields included in the current migration package, that they should be transformed before actual loading.

Only raw values that found in the mapping table will be replaced, but the rest of the source values remains unchanged.

Use #N/A RawValue to map an empty source record to another Value.

Regex replacement. ⇧

You can also use regex to replace values. Following is the example of value mapping configuration using JS RegExp:

It is equivalent to this JS code:

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

which will produce the result: 'REPLACE_TheRawFieldValue'

Considerations about the regex option:

• To make your regex correctly recognized by the Plugin, you have to put the expression between two slashes /YOUR_REGEX_EXPRESSION/.

• You can also freely mix regex expression with other regular replacement definitions.

• Make sure that you have only one regex expression definition per field.

Js eval replacement. ⇧

You have also an option to make a replacement based on the native js eval() function which can execute any js expression.

For example you have the source field value 'DDMM' which should be replaced with the today's date and month number.

For that you can use the following value mapping:

Source value: 'DDMM'.
Output value: '1011'

In more complex scenarios you can also extend a use of eval() in conjunction with regex replacement, e.g.:

Source value: 'Date=DDMM'
Output value: 'Date=1011'

To use the original field value in your expression, put the reserved word RAW_VALUE in the expression and it will be replaced with the original field value from the source record, e.g.:

Source value: 'Source value'
Output value: 'Source value was replaced'

Considerations about the eval() replacement option:

• To make your replacement working as expected, you have to include the js expression to evaluate into the function eval() like below: eval(ANY VALID JS EXPRESSION).

• Don't put the expression into single or double quotes only put it as is between the brackets.

• To use the original field value in your expression, put the reserved word RAW_VALUE in the expression and it will be replaced with the original field value from the source record, e.g.:

  Source value: 'Source value'.
  Eval expression: eval('RAW_VALUE was replaced')
  Output value: 'Source value was replaced'