Mapping Calculated Fields in Visual Data Mapper

Calculated Field Mappings in Visual Data Mapper are a way to programmatically assign data to a field.

Step 1: Open the Visual Data Map

Visual Data Mapper is opened from within Workflow Designer.

See our step-by-step walkthrough: Opening a Visual Data Map.

Step 2: Optionally drag source fields to the target

If any source data is needed in the script, relevant fields may be included in the Calculated Field Mapping as follows:

1. Select the target field on the right that will be Calculated.

   

2. Drag the desired left-hand source field onto the target field.

   

Step 3: Set the field mapping to Calc

Once source fields are added to the target (or if none are required), set the target field mapping type to “Calc” to indicate that it’s a Calculated Field Mapping.

Step 4: Update the mapping

Apply changes using the Update button, this will not save the changes but will allow them to be tested.

Step 5: Apply custom script

A custom script may be written in javascript which performs advanced business logic.

This example generates a new date based on an initial date (when a customer placed the order) plus an offset (based on which shipping method the customer chose).

// Express shipping 1 day fulfillment
// Standard shipping 5 day fulfillment
// Direct shipping 8 day fulfillment
var offset = 8; // default Ground
if ($processing_method == 'express'){
  offset = 1;
}
else if ($processing_method == 'standard'){
  offset = 5;
}
else if ($processing_method == 'direct') {
  offset = 8;
}
else {
  throw 'Validation error: Unknown processing method \"' + $processing_method + '\"';
}

var fulfillmentDate = new Date($created_at);
fulfillmentDate.setDate(fulfillmentDate.getDate() + offset);

var b1FormattedDate = fulfillmentDate.toISOString().substring(0,10).replace(/-/g,'')

return b1FormattedDate;

Refer to mapped variables directly

In the above script, $created_at and $processing_method are mapped directly from the source.

Optionally refer to source data using $root

Instead of mapping a field and referencing its shortcut, we may use the root variable to reference source data directly.

Instead of $created_at, this would be: $root.Shopify.orders.created_at

Instead of $processing_method, this would be: $root.Shopify.orders.processing_method

This type of direct reference is handy when conditional logic would require different source data.

Optionally throw exceptions to fail the mapping

To force a mapping to fail (for example, if the data does not conform to the expected format), an exception can be thrown.

Best practice is to provide sufficient detail to allow someone to troubleshoot the error on their own.

In the example above, an exception is thrown when the shipping method ($processing_method) is not one of three known values. It’s prefixed with the type of error (Validation error), and provides details including relevant data.

Return the mapped field result

To generate a result for the mapped field, return the desired data from the script, for example, the script above returns the value of b1FormattedDate - which is a formatted date string.

Data must be in a valid format and cannot be objects. For example, a formatted date string as opposed to a date object.

Step 6: Update and Save changes

Once desired changes are updated, they are ready to be saved. Changes are tracked in file history and may be rolled back if desired.