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