This week we are going to look at REST Lookups and how they can simplify your integrations with REST APIs. We will be investigating several REST API features. We will be showing the configuration in SmartConnect.com, but all the same features are available in SmartConnect 21.
Table of Contents
- What are REST Lookups?
- Adding a Lookup to the REST Connector
- Using a REST Lookup as Mappable Fields
- REST Lookup Options
- REST Lookup as a Restriction
What are REST Lookups?
Lookups are available on all the standard SmartConnect connectors allowing the integration to dynamically retrieve data from the target system prior to sending the data to the target system. REST lookups are the most recent lookup feature added to SmartConnect, allowing users to define custom lookups for REST destination integrations. These lookups can retrieve data that can then be used as a mappable field, part of a calculation or a restriction.
The below video walks through setting up and using a REST Lookup.
Adding a Lookup to the REST Connector
The first step is to add the REST Lookup to the
- Navigate to Maintenance > REST Services > “Your Connector” > Service Lookups
- Type a Name for the lookup column and click the pencil to edit
- Set the endpoint and REST Method as outlines in the REST API documentation
- Switch to the Returnable Fields tab and define at least one returnable field
- Add any Body, Headers, or Parameters that will be used as part of the filter criteria.
- Switch the Filter Criteria tab and check the “Display in filter” option for any variables, headers, or parameters you want to use as the filter criteria
- Save the Lookup setup
Using a REST Lookup as Mappable Fields
Once the REST Lookup has been created, it can be added to the integration process.
- Open the integration process that will use the lookup
- Navigate to Integration > Additional Columns > Add Additional Column
- Add at least one return field and Filter Criteria
- Save the lookup and map the REST Lookup fields as needed
REST Lookup Options
When configuring the additional column there are two check boxes.
- Late Bound Lookups: will be run after all data is calculated, which means this lookup can use a calculation as the filter criteria column
- Include lookup result in scripting: will run the lookup before other additional columns, which means the result can be used in a calculation
- Neither checkbox is used: will allow the lookup to be used as a restriction
In the “If No Data” drowdown there are 6 options. The below table describes each of the options in the dropdown and if they can be used in combination with the two check boxes.
|Option||Description||Late Bound Lookups||Result in Scripting|
|Continue||If the lookup does NOT return data, the integratin will continue to process||Allowed||Allowed|
|Restrict line out if data exists||If lookup DOES return data, the integration will not send any lines that use this lookup||Not Allowed||Not Allowed|
|Restrict line out if no data exists||If the lookup does NOT return data, the integration will not send any lines that use this lookup||Not Allowed||Not Allowed|
|Return failure for current integration line||If the lookup does NOT return data, the current document will fail and the integration will continue processing the next document||Allowed||Allowed|
|Stop processing integrations||If the lookup does NOT return data, the integration will stop processing all documents with an error||Allowed||Allowed|
REST Lookup as a Restriction
A REST Lookup can be used to dynamically restrict data based on if the lookup criteria returns data from the API.
At least one field from the lookup column must be mapped to a target field on the line which should use the lookup as a restriction.
A common use for this feature is to create a single integration capable of performing both Creates and Updates. Without using a lookup the only way to know if a record already exists in the target system is to writeback the target identifier to the source system.
I am importing Items from Business Central into WooCommerce. The WooCommerce API requires separate API endpoints for creating products than for updating products. To accommodate this, I will setup the integration to use two REST destinations in one integration. When querying the item list from Business Central, SmartConnect doesn’t know if the data already exists in WooCommerce. Therefore, I need to use REST Lookups to query WooCommerce to check if the product already exists. The lookups will be setup this way:
- Create a new Lookup named “LKUP_NEW_ITEM”
- Set the lookup to “Restrict line out if data exists”
- Create a new Lookup named “LKUP_EXISTING_ITEM”
- Set the lookup to “Restrict line out if no data exists”
- Map the “LKUP_NEW_ITEM” field to a field on the “Create Product” line
- Map the “LKUP_EXISTING_ITEM” field to a field on the “Update Product” line
If you have any further questions, you can email us at email@example.com.Using REST Connector Lookups