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

1. What are REST Lookups?
2. Adding a Lookup to the REST Connector
3. Using a REST Lookup as Mappable Fields
4. REST Lookup Options
5. 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

1. Navigate to Maintenance > REST Services > “Your Connector” > Service Lookups
2. Type a Name for the lookup column and click the pencil to edit
3. Set the endpoint and REST Method as outlines in the REST API documentation

4. Switch to the Returnable Fields tab and define at least one returnable field

5. Add any Body, Headers, or Parameters that will be used as part of the filter criteria.

6. 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

7. 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.

1. Open the integration process that will use the lookup
2. Navigate to Integration > Additional Columns > Add Additional Column
3. Add at least one return field and Filter Criteria

4. Save the lookup and map the REST Lookup fields as needed

These lookup fields can now be mapped directly to any target fields, or used in a calcuation.

REST Lookup Options

When configuring the additional column there are two check boxes.

1. Late Bound Lookups: will be run after all data is calculated, which means this lookup can use a calculation as the filter criteria column
2. Include lookup result in scripting: will run the lookup before other additional columns, which means the result can be used in a calculation
3. 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.

Example Scenario

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:

1. Create a new Lookup named “LKUP_NEW_ITEM”
2. Set the lookup to “Restrict line out if data exists”

3. Create a new Lookup named “LKUP_EXISTING_ITEM”
4. Set the lookup to “Restrict line out if no data exists”

5. Map the “LKUP_NEW_ITEM” field to a field on the “Create Product” line
6. Map the “LKUP_EXISTING_ITEM” field to a field on the “Update Product” line

The integration will now dynamically use the Create and Update product endpoints based on if the product already exists in WooCommerce.

If you have any further questions, you can email us at support@eonesolutions.com.

Using REST Connector Lookups