Response mappings merge data returned from a page processor (from an import or a lookup) into the original export’s data, so that the new data can be used in steps later on in the flow.

Contents

• Introduction
• Configure response mappings
  • Response mappings for other data in an import
• Retrieve customer ID
• Configure lookup
• Catch errors
• Additional lookup steps

Introduction

Click the mappings icon immediately after an import or lookup step (that also has another step following it) to create or modify response mappings. Click the plus icon to add it if it isn’t visible.

For example, if you have Shopify customers that require the creation of sales orders from various other parent companies that can already be assigned by customer region in NetSuite, those parent companies are only accessible in the flow with a lookup step and response mappings.

The above example uses the following steps:

1. Export a customer record from Shopify.
2. Import the record into NetSuite.
3. Use a lookup to find the customer's parent company in NetSuite.
4. Perform another import to create a sales order for the parent company in NetSuite.
5. Perform a final import step to catch errors.

Configure response mappings

Once you import the customer into NetSuite for the first time, you must configure the response mappings:

The response mappings for NetSuite imports allow the four options:

• id: exports the internal ID of the record just imported into NetSuite.
• errors: exports any errors from the processed record in this step.
• ignored: exports a “true” or “false” value. The value is "true" if the record processed through this import step was ignored. Otherwise the value is "false".
• statusCode: exports the status code that resulted from processing the record through this import step.

All of this data is merged into the source export’s data object as a new field. The Source record field (New/Existing field) on the right is for choosing a field name to hold the data that will be merged back into the source export for use later on in the flow. If you use a name that is already a field on the top level of the source data’s JSON object, this response mapping overwrites that field. If you use a new name, a new field is added to the source data.

Response mappings for other data in an import

Response mapping for imports into other endpoints (besides NetSuite) may have more options than the record ID available depending on the data fields of the endpoint. Some APIs return the whole object you just imported back to you, and some only give an ID (like NetSuite). If any other fields return when importing a record in the API, you can manually add that field on the left, but it won’t appear in the drop-down menu. For example, HubSpot returns a companyId field when creating a company through the company's API, and a response mapping can be added as shown in the following image.

Retrieve customer ID

The next step in this example retrieves the ID of the imported customer and stores in a a field named "netsuite_id" for use in the following lookup step:

This adds a “netsuite_id” field onto the original export of the Shopify customer. The following image displays the JSON structure for each JSON object of the imported customer (omitting much of the data to see the bottoms of the objects):

To verify that the JSON picked up the response mapping in the next step in the flow, you can examine the new JSON data as retry data when the flow errors in further steps. Also, the response mapping should show up in a drop-down menu in the next import step’s mappings.

Configure lookup

For NetSuite lookup steps, you must create a saved search. In this case, the search retrieves all all customers, and then uses the "netsuite_id" from the previous step as a variable to find just the customer that was just created with that internal ID.

1. Set up the saved search, and add it to the lookup settings:

2. Click Launch under Additional search criteria and retrieve that customer using handlebars to target that field. The field changes dynamically on each lookup for each record imported.

Note: You can add more lookup criteria lines than just Internal ID is netsuite_id, but they will all be linked by AND statements, so all of the criteria must match a record or records for the saved search to return them correctly.

Lookup steps always require response mappings to be useful later in the flow. Lookups differ from import steps in that they have one additional data option for response mappings. 

The data option returns an array of objects: one for each record the “All Customers” search retrieves. But since the search only retrieves a specific internal ID, there should only be one result returned per lookup. The lookup step also adds a new field back onto each original export record. The saved search for “All Customers” can return many things in its results, which can be picked up with data[0] (the first record returned).

Note: If more than one record should return in a lookup step, you can use data from the drop-down menu rather than data[0], so that the newly created field contains an array of objects rather than a single object. You can then target the field in further steps with normal JSON arrays in integrator.io.

In this case, the data option should only return one value (the parent company's ID). This example uses a custom label (parent_id) in the saved search results.

This gets the NetSuite internal ID of the related parent company to the originally exported customer, and adds it back onto the JSON data like before. Now, you can use this data in the following import step’s mappings:

Here you can also map whatever other required information is needed from the original Shopify export to create a sales order successfully.

Catch errors

Using the above mapping will cause errors. If you want to record errors in an external system, you must configure one more response mapping to catch errors.

Any errors the sales order import retrieves are written to a new field called “so_errors”. Errors don’t normally need to response mappings because they can be seen in the integrator.io dashboard, but there may be a case where errors should be imported into a custom record in NetSuite (or in a CSV file in an FTP).

Click the Proceed to the next application regardless radio button to set the flow behavior if errors are encountered. Otherwise, the flow stops and does not execute the final import step to catch the errors that are written back to the original export with the response mapping. You would want to use this default setting for scenarios where the failure of a record does not impact the other records. For example, if you are doing inventory updates on multiple webstores or marketplaces, you wouldn't want the rest of the inventory updates to pause just because one record failed. Any successful records will be moved through, but the failed record will be held here so that you can retry it. 

If you select to send the failed record the next application, then retry it, this will only retry the record on that step of the process. However, if you select to pause the failed record until someone can fix the error, then retry it, the record will be retried on that step and all subsequent steps.

The errors will be merged into the original object in the “so_errors” field.

You can also configure an unlimited number of further lookup or import steps with response mappings as needed to use in further steps.

Additional lookup steps (including HTTPS or other endpoints)

In additional lookup steps, the data will be merged into the original export in whatever field name you choose to store the values in (merging both the customer ID from an import and the parent_id from an export into the source data for use in further steps in the flow).

One difference for HTTPS lookups (and lookups for most other APIs besides NetSuite) is that the lookup step’s variable is often placed in the relative URI instead of a saved search.

This is an example configuration of sales orders exported by NetSuite with a Shipwire lookup to capture order information within Shipwire:

In this case, the handlebars statement is put within the parameters of the API call, and the purchase order ID changes dynamically for each order processed by the flow.