For flows that have multiple imports, response mappings allow you to define actions based on the API response from an import. For example, you can use response mapping to define an action based on the success or fail value of a field for records sent to an import.
Results mappings merge data returned from a lookup into the original export’s data, so that the new data can be used in steps later on in the flow. For lookups, 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:
- Export a customer record from Shopify.
- Import the record into NetSuite.
- Use a lookup to find the customer's parent company in NetSuite.
- Perform another import to create a sales order for the parent company in NetSuite.
- Perform a final import step to catch errors.
Note: If you rename a field label in NetSuite and want to reflect the same label name in integrator.io, refresh the metadata on your connection and check the mapping field. To refresh metadata, go to Connections > NetSuite Connection > Actions > Refresh metadata.
Contents
- Configure response mappings
- Retrieve customer ID
- Configure lookup
- Catch errors
- Additional lookup steps
Configure response mappings
Once you import the customer into NetSuite for the first time, configure the response mappings. Click the mappings (
) button immediately after the import step to create or modify response mappings. Click + within the step to add it if it isn’t visible.
The response mappings for NetSuite imports allow the following 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 data as new fields (or replaces existing fields). Choose a field from the Source record field on the right to hold the values that will be merged back into the source data 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, 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 it in 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
NetSuite lookup steps require you to create a saved search within NetSuite. In this case, the search retrieves all customers, and then uses the "netsuite_id" from the previous step to find the customer that was just created with that internal ID.
- Set up the saved search in NetSuite, and add it to the lookup step.
- Set the Record type to Customer.
- Set the Saved search type to Public or Private depending on how you've configured it in NetSuite
- Click Launch under Additional search criteria and use a handlebars expression on the NetSuite internal ID. The handlebars expression populates the ID field value for each record imported.
Lookup steps always require results mappings to merge the lookup data into the source data for use later in the flow. Lookups differ from import steps in that they have one additional data option for results 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 record of source data. The saved search for “All Customers” returns the results for a single record in an array.
You can access all items in the array with data[0]. data[0] is bracket notation that selects the first item of the data array. If more than one record returns in a lookup step, select data from the drop-down menu rather than data[0], so that the newly created field contains multiple 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. Errors don’t usually require response mappings because they can be reviewed and resolved on the integration dashboard, but if you want to import errors into a custom record in NetSuite (or in a CSV file in an FTP), you must configure response mappings.
Each error the sales order import encounters is written to a new field called “so_errors”.
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.
Failed record flow behavior
Pause here until someone can fix the error
When a record causes an error, by default, the Pause here until someone can fix the error option is selected to stop the flow from sending the failed record to any subsequent flow steps until the error is fixed. The failed record will be held here so that you can fix and retry it. Upon a successful retry, the record will then proceed to any additional flow steps.
Proceed to the next application regardless
Click Proceed to the next application regardless to push records that contain errors to subsequent flow steps regardless of whether or not the record produces an error during this flow step. The failed record can still be fixed and retried for this flow step, but if it didn't fail on any additional flow steps, it won't be pushed to those additional steps upon successful retry. This is the preferred choice if, for example in NetSuite use cases, you are sending inventory update records to multiple webstores or marketplaces. If the record fails on this step, you might still want that record to proceed to any subsequent steps in the flow so that the other stores and marketplaces can get the update.
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.
Comments
7 comments
The text of this says:
"Lookup steps always require response mappings to be useful later in the flow."
What does it mean for the response mapping to be "useful"? That I have to use the output as the source in a mapping or filter? And if I don't have it included yet, what will the consequences be? will it a) not show up in the SOQL query inputs of the next step, or the filter inputs b) not show up as a picklist value, or c) not show up in the retry data, or d) all of the above?
Hi, METER Group power user.
The answer to all of the above is yes, as you inferred. To add the records returned in the lookup step to your flow's data, you must map the response. And then, you'll have access to them in all of the flow steps/options mentioned.
We'll see what we can do to remove any ambiguity. To paraphrase a subject-matter expert here, "It's not that the response mapping will be useful, it's that the lookup step will have no use without response mapping."
Oh. I understand now.
"Lookup steps always require response mappings in order to be useful later in the flow."
That said, I was actually unclear in my question - I was trying to figure out some rhyme or reason to response mappings. Some values in the 'Lookup Response Field' work for me, and some don't. I was hoping that the answer was that the 'Source Record Field (New/Existing field)' actually had to be _used_ in a subsequent mapping in order to get populated by the response mapping. In my write bubble (to Salesforce), here are the response mappings I used, with the results:
body[0].id -> SFOpportunitybodyID_KW appears in the retry data (only)
id -> SFOpportunity_id_KW appears in the filter/SOQL data (only)
body[*].id does not show up anywhere
In an ensuing lookup bubble (looking up Opportunity Products in Salesforce):
data -> opportunitydata_kw works for the filter/SOQL data, Retry data
body.id does not show up anywhere
body[0].id does not show up anywhere
id does not show up anywhere
METER Group, I'm going to submit that question as a support ticket for you. body[0] might be a little suspect, instead of data[0], but it's not ideal to try to troubleshoot the mapping and subsequent flow steps in this format.
Hi, Stephen Brandt. Could you share here the solution for this matter? I'm facing the same problem. I'm trying to use the data coming from a lookup, name "Rateio", in the next lookup, but it's not return the value of {{Rateio[*].u_carteira}} This expression was selected among the mapping available, I did the response mapping.
Message:
"Failed to generate request url from template: https://xxxxxx.service-now.com/api/now/table/x_jam_special_oppo_x_carteira/{{{Rateio[*].u_carteira}}}.
Details: Parse error on line 1:\n..._oppo_x_carteira/{{{Rateio[*].u_carteira\n-----------------------^\nExpecting 'ID', 'STRING', 'NUMBER', 'BOOLEAN', 'UNDEFINED', 'NULL', 'DATA', got 'INVALID'."
Thanks
Thanks for this search and comment, Andre Flaeschen. I pored through Kenneth's ticket above, and I didn't see a resolution or a problem statement that would help with the error you're getting. Can I suggest bringing up your flow in Office Hours, and entering a support ticket if you don't get resolution there?
the Help Desk was pretty helpful to me on this. There are some things that play into it like 'one to Many', and others that I still might not fully understand; and, what you are trying to do makes a difference e.g. Are you trying to pull out an array, or just a single value?
One suggestion they gave me was to use the variable name _json instead of data (I saw no effect from this one)
Holly did some testing:
- data is used in Response mapping from the Lookup step and can be used in input filters
- id is used in Response mapping from the Import step and can be used in input filters
- body is only available on the retry data and has only the following values:
"testbody": [ {
"id": "xxxxxxxxx",
"success": true,
"errors": []
}
]
-- to get the body id, use body[0].Id
I did some more testing and found that data.0.Id is the same as data[0].Id
Hopefully that helps some.
Please sign in to leave a comment.