Architecture
  • 23 Sep 2022
  • 5 Minutes To Read
  • PDF

Architecture

  • PDF

Let's take a look at how the Lookup Adaptor works from a technical perspective.

Architecture

lookup-adapter-arch.svg

From a high-level, the Lookup Adaptor functions like this:

Auto-Linking, Basic Search and Detailed Lookup requests

  1. Each of these requests is sent as a POST request over HTTPS to the Lookup Adaptor(s) you configured, with a JSON body of a specific format.
  2. When a Lookup Adaptor receives these POST requests, it must parse and process them (e.g.: search your OMS for orders associated with this Customer).
  3. The Lookup Adaptor must then respond back to Gladly with a JSON body of a specific format so Gladly can present that information to Agents & use it for routing purposes.
  4. Gladly stores information returned by your Lookup Adaptor under certain scenarios (e.g.: a Detailed Lookup's valid response).
Watch Out - Implementing Actions

Actions build on top of a Detailed Lookup, so if you'd like to build Actions, you'll first need to build a Lookup Adaptor capable of processing and responding to Auto-Linking, Basic Search, and Detailed Lookup requests.

Actions

  1. Actions may be returned as part of a response to a Detailed Lookup request.
  2. Actions on the Profile level display as part of the Gladly + button on the bottom of the Customer Profile screen. Actions on the transaction level will display as buttons underneath a transaction.
  3. When an Agent clicks these buttons, Gladly issues a GET request to your Lookup Adaptor asking it to provide information on what form fields Gladly should display for the Agent to fill in before performing this Action.
  4. When the Agent fills in the form fields and submits the Action, Gladly will issue a POST request to your Lookup Adaptor with information on their form entries. Your Lookup Adaptor must then process this Action and then respond back to Gladly with a status.
  5. Upon completion of an Action, Gladly will then issue another Detailed Lookup request.
Tip - Transaction-level Actions

Actions at the transaction-level are only available for ORDER type transactions.

Gladly Requests Made

IP Addresses

Gladly requests will be made from these set of IP addresses.

Request Headers and Authentication

Every request that Gladly makes to your Lookup Adaptor will come with a set of headers, some of which you can configure.

Headers may include the following:

Header Name Value Is Always Sent?
content-type application/json yes
accept application/json yes
gladly-time timestamp of request. format is YYYYMMDDTHHMMSSZ yes
gladly-correlation-id A string indicating the Gladly request ID yes
user-agent Go-http-client/1.1 yes
content-length The POST body content length yes, if a POST request is made
gladly-authorization Gladly-signed authorization string. More information on how requests are signed can be found here. yes
authorization OPTIONAL Basic auth header that can be set when configuring Lookup Adaptor in Gladly no - can be configured in app settings
www-authenticate OPTIONAL Basic Auth realm that can be set when configuration Lookup Adaptor in Gladly no - can be configured in app settings
CUSTOM_HEADER OPTIONAL custom headers whose names and values can be set when configuring the Lookup Adaptor in Gladly no - can be configured in app settings
Note - Authentication

Gladly currently supports sending Basic Auth headers, custom static headers, and the gladly-authorization signed string in requests.

Requests Sent

Tip - Where are requests made?

All Auto-Linking, Basic Search and Detailed Lookup requests are made to the URL you configured in the App page on Gladly. The Action Button Clicked and Action Form Submitted URLs can be lightly customized, which we will delve into in the Actions tutorial.

Event Name HTTP Method Purpose When Agent Experience Developer Experience Code Samples
Auto-Linking POST Automaticaly link a Profile in Gladly with another Profile in your system without Agent intervention Triggered when a new Contact comes in on an unlinked Profile

Triggered when an Agent loads an unlinked Profile

Triggered when an Agent makes an update to Profile

Triggered when Self-Service Threads are turned on for Sidekick and an unlinked Profile successfully authenticates

Exception: only triggered on a profile when it has never previously been unlinked
If successful, the Gladly customer profile will display detailed information returned from your system. Lookup Adaptor will receive a POST request from Gladly. If Lookup Adaptor responds with correctly formatted response, Gladly will automatically link the Profile and then issue a Detailed Lookup request. Sample
Basic Search POST If auto-linking is not successful (or is turned off), an Agent can use Basic Search to search your system and manually choose a customer record to link to a Gladly Customr Profile Triggered when Agent manuallly searches for another Profile in your system to link to within Gladly Agent populates search fields and clicks "Search." If successful, results display for Agent to link. Lookup Adaptor will receive a POST request for a Basic Search. If Lookup Adaptor responds with correctly formatted responses, Gladly will display a set of results to Agent to select from. If Agent selects a profile to link to, Gladly will issue a Detailed Lookup request Sample
Detailed Lookup POST Show extended information about a linked Customer Profile on Gladly Triggered when Profile is linked

Triggered after an Action is performed

Triggered when an Agent makes an edit on a linked Customer profile

Triggered when a non Phone Contact comes into a linked Profile or Agent views Profile after accepting Call

Triggered when Self-Service Thread is turned on in Sidekick, user successfully authenticates, and Profile is linked

Triggered when Agent manually clicks on Refresh Data button on linked Profile
Agent sees extended information/actions Lookup Adaptor will receive a POST request for a Detailed Lookup. If Lookup Adaptor responds with correctly formatted response, Gladly will display extended information for Agents Sample
Action Button Clicked GET Display form that Agent can enter custom values into to perform an Action on the Profile within Gladly

This is only available after the Profile has been linked!

Actions at the transaction level are only available for ORDER-type transactions
Triggered when an Agent clicks on an Action button in Gladly Form displays for Agent to fill in and submit Lookup Adaptor will receive a GET request asking for form settings to display. If response is correctly formatted, form will display for Agent. Sample
Action Form Submitted POST Perform an Action on Gladly on behalf of Customer (e.g.: cancel an order; award loyalty points)

This is only available after Profile has been linked!

Actions at the transaction level are only available for ORDER-type transactions
Triggered when an Agent submits Action form on Gladly Action status / results shown to Agent in Gladly Lookup Adaptor will receive a POST request with values Agent submitted in the form generated by "Action Button Clicked" event to process. Lookup Adaptor needs to return back status, after which a Detailed Lookup request will be issued. Sample

Was this article helpful?

What's Next