Tray Embedded / Advanced Topics / Data Mapping (Embedded) / Hardcoded example

Hardcoded example

The following workflow shows an example of setting the basis for an Embedded Data Mapping system, which imagines a scenario that periodically synchronizes Stripe accounts with Salesforce accounts:

This example uses a 'List Records' type of operation and therefore employs a loop connector. (Pagination might also be necessary in this case if large batches of results are being returned)

Note that it is likely you will wish to use a 'Create Record' type of operation (create a Salesforce account, create an Asana project, create a Dropbox folder etc.). In which case you would not need to use a loop connector.

The steps involved here are:

  1. Loop through the accounts being returned
  2. Create a Mapping Script which uses the dataMappings config data variable to set the mappings chosen by your End User (required - this is the key step!)
  3. Make any final adjustments before inputting to the second service. This example shows transforming results into Key/Value pairs (optional - only necessary for connectors such as Salesforce which demand key/value formatting for certain operations)

Creating the workflow

1 - Loop through Stripe Accounts

Having used the Stripe 'List accounts' operation we can use the Loop connector to loop through them one-by-one:

2 - Add the config variable and create the mapping script

The Mapping Script then uses 2 variables:

  1. The config data variable which we have called dataMappings
  2. In this example we have created a variable called stripeFields which pulls in the fields from the loop step:

The key to getting the whole mapping system working is the script itself, which makes use of dataMappings and stripeFields:

exports.step = function (input) {
  // The mappings that will eventually be added by your end user:
  var mapping = input.dataMappings;
  // The new object we will use to create an entity to insert:
  var newEntity = {};
  // For each field in the mapping, add a field into `newEntity`
  // where the name is the key from the right side of the mapping
  // and value from the initial object, using the key from left side of the mapping
  for (var field in mapping) {
    newEntity[mapping[field]] = input.stripeFields[field];
  }
  return newEntity;
};

Note that, unlike in the main Tray Platform Data Mapping documentation, we do not specify the actual fields to be mapped in this script.

We use var mapping = input.dataMappings; to pull in the fields which are set by the End User when they run the Config Wizard, as will be shown below.

This will produce a result whereby you can see the full list of fields that are input to the script (from the loop step), with only the fields selected by the End User as output:

3 - Final transformation step (optional)

For some operations you will be able to just directly pull in the mapped data using jsonpaths.

However, some services may require data to be input in a certain format. In this example we are using the 'Create Record' operation in Salesforce, which expects data to be input as key/value pairs.

So in this case we use a second script step to pull in the results from the first mapping script and transform it with the Lodash _.map function:

exports.step = function (input) {
  const result = _.map(input.fields, (value, key) => ({ key, value }));
  return result;
};

4 - Input mapped data to Salesforce

The final step of this example is to use the output of the second script step to create the record in Salesforce:

Create the project and solution

The next step is to create your project and solution, as per the Tray Embedded Interface Guide

When in the Soluton Editor, you can then configure the Data Mapping fields that are available for the end user to select when they are using the Config Wizard. In order to do this you must first enable Data Mapping on your new configuration item in the Solution Editor:

Once you enable data mapping you will be presented with the data mapping settings dialog:

Service 1 setup will allow you to configure the field list for the left side of your Data Mapping component, i.e.the service you want to map from. There are several options for generating field lists:

Hardcoding your field list

Selecting "Hardcoded List" from the field list type, you can then set the title and value of the fields within your field list. This must be done for Service 1 and Service 2.

So in the case where we want to set the list of Stripe fields in Service 1 to be mapped from we would enter them as such:

On the left you set the field titles that will be visible to your End Users in the Config Wizard dropdown list (note the good practice of indicating the service name in brackets so it is clear to your End User!). On the right you enter the raw field names which are actually used by the service. Some investigation is required to tell you what these fields are. In this case we can look at the debug output of the List customers operation for the Stripe connector to find that 'name', 'id', 'phone' and 'currency' are what is used by Stripe:

To determine the fields that need to be mapped to in Salesforce we inspect the output for the Create Record (Account) operation:

Note that Stripe_ID__c and Currency__c are custom fields added specifically for mapping from Stripe (remember from the explanation above that we needed to use a second script connector to map the results to the above key/value format expected by Salesforce).

You can then use this to build the list for Service 2:

You can also then set the Default Mapping which can be used to prompt the user to select the correct mapping before they save their configuration: