The Lookup Adaptor is a piece of middleware you build, host, and maintain that displays additional information about a Customer directly in Gladly from your external sources (e.g., BigQuery). The Lookup Adaptor allows Agents to view extended information and perform actions on a Customer Profile in external systems directly within Gladly.
This introduction and the following articles provide detailed guidelines for rolling everything into one.
Before you start #
- Before you build your own Lookup Adaptor, take a look at Gladly’s suite of app integrations. We may have an app you can utilize without needing a custom Lookup Adaptor.
- To guide your process, we suggest you start with our Developer Guide
on building a Lookup Adaptor.
on building a Lookup Adaptor.Key Concepts #
As with all things Gladly, Customers are the central pillar. Below is some key terminology of our wrap-around Customer care.
Customer System of Record #
Your internal database or application with Customer information.
Customer Profile #
A Customer Profile on Gladly may contain their name, email(s), phone(s), and address. A Lookup Adaptor allows you to extend the profile with custom attributes from your system of record.
Custom Attributes #
Attributes about your Customers from your System of Record (e.g., birthday, lifetime value, loyalty number, shoe size) sent to Gladly via your Lookup Adaptor. They can be included on your Customer Profile and used in other parts of Gladly’s products like People Match, Rules, etc.
Gladly will need to assist you with displaying each attribute your Lookup Adaptor sends to Gladly that you’d like to display on the Customer Profile.
Transactions #
An array of objects consisting of a group of Gladly-defined custom attributes displayed in pre-set cards that can help showcase variable information about the Customer, like orders and flights. You may choose GENERIC, ORDER, FLIGHT, SUBSCRIPTION, and STAY cards. You can implement multiple types of transaction cards.
Actions #
Updates an Agent can perform on a Customer Profile or ORDER type Transaction in your System of Record through Gladly (e.g., offer a discount, refund an order).
External Customer ID #
Unique identifier in your Customer System of Record, stored in Gladly profile as a foreign key.
What Is Lookup? #
Lookup allows Agents on Gladly to link a Gladly Customer Profile to an external profile in another system of record. Upon linking, Gladly can showcase extended information & actions on the Customer Profile that the Lookup Adaptor sends to Gladly.
Once linked, Gladly will display more detailed information about the Customer. For example, Gladly can display the Customer’s most recent orders.
By implementing a Lookup Adaptor, you can send Gladly various data to be viewed in the Customer Profile, such as Customer loyalty points, total lifetime value, historical orders, and more. You can even integrate Actions directly within Gladly, such as returns and refunds.
Building a Lookup Adaptor #
To accomplish the above, you must build a Lookup Adaptor between your system of record and Gladly. You may build as many Lookup Adaptors as you’d like! For example, you might want to build one for your OMS and another for your loyalty points provider.
- Tip – A Customer Profile in Gladly can be linked to multiple Lookup Adaptors. However, the Customer Profile may only be linked to one entry within each Lookup Adaptor.
How does it help Agents? #
A Lookup Adaptor helps Agents by bringing data out of a separate window, tab, or application and putting that information directly in the Gladly Customer Profile. If Gladly identifies multiple matches in the System of Record, it will present Suggestions on the Customer Profile.
Should we build a Lookup Adaptor? #
Gladly has several out-of-the-box apps built using Lookup Adaptors you can connect without any extra coding! For example, here are our documents on BigCommerce and Magento. We recommend you read through those before you decide to invest in Lookup.
How it works #
An unlinked Customer Profile will typically initiate an Auto-Linking request to your Lookup Adaptor upon a new Contact, Profile edit, or Profile load (exception: when the Profile has been previously unlinked). If you’ve set up auto-linking and your Lookup Adaptor responds with a correctly formatted response, Gladly will then initiate a Detailed Lookup request to retrieve more detailed information on the Customer Profile.
If auto-linking is unsuccessful or not configured, an Agent can still click the “Link to external Customer” button underneath the Customer name to manually search for a record to link to within your Lookup Adaptor(s).
Search fields (called Search Query Attributes) you configured in your App settings page are displayed for the Agent to fill in manually. When the Agent clicks on Search, a Basic Search request will be issued to your Lookup Adaptor. Your Lookup Adaptor should return a list of potential matching results. If your Lookup Adaptor responds with a correctly formatted response, Gladly will display these results (called Search Results Attributes) in a table whose format is configured in the App settings page on Gladly.
The Agent can then choose a profile to link with. Once they click on Link, Gladly will issue a Detailed Lookup request to your Lookup Adaptor to retrieve more detailed information on the Customer Profile.
Once linked, a Detailed Lookup request will be issued when a new Contact comes in, when an Agent navigates to the Customer Profile, or when an Agent refreshes the browser while viewing a Customer Profile.
You can use the Detailed lookup to extend the Gladly Customer Profile object in two ways:
- Profile-level custom attributes (e.g., lifetime value)
- A list of transactions (e.g., historical orders) associated with this Profile
In subsequent sections, we’ll delve into the Customer Profile object structure and how to extend it.
When your Lookup Adaptor sends back a Detailed Lookup response, it can also specify a list of Actions the Agent can take on this Profile. These Actions can be specified at the Profile level (e.g., add loyalty points) or the transaction level (e.g., cancel an order) for ORDER type transactions. In subsequent sections, we’ll also delve into Actions and how to build them.
Initial setup #
To activate your Lookup Adaptor, please follow these directions.
Subsequent tutorials will delve deeper into the Lookup Adaptor architecture, request, and response formats.
