| REQUIRED USER ROLE Administrator | PERMISSION OVERVIEW View permissions by role |
Use the Basic + Detailed Workflow debugger tool to understand what happens when Agents manually link a Customer to an external system. Using this tool, you can look up specific Customer Profiles to test, check for errors, view custom attributes, show query attributes, and more.
Before you start
Before you use the Basic + Detailed Workflow debugger tool, we recommend you first review the following:
Users with only the Developer role cannot create or search Customer Profiles. Assign either the Task User with the Developer role to inherit this permission.
Review What is the Lookup Adaptor Debugger for information on when to use the debugger, access requirements, and more.
See the Lookup Adaptor Basic Search FAQs for common issues experienced with Basic Search.
How to use the debugger
Click
.svg)
on the top left corner of the screen.Click Settings.
Under the App Developer Tools category, click Lookup Adaptor Debugger.
From the Lookup Adaptor Debugger page, under Basic + Detailed Workflow, click Test Workflow.
Here, you can search and detect issues that may prevent manually linking a Customer to an external system.
Search for a Customer
First, enter the Customer's email address and/or phone number to find them in Gladly.
Enter the Customer's email address and/or phone number (country code + area code + phone number) in the Search for Customer in Gladly section. This helps search and ensure the Customer exists in Gladly.
If you enter both the Customer's email address and phone number when searching, Gladly will attempt to find the Customer first by email, then by phone, and then fail if the Customer can't be found.
From the Debug Lookup Adaptor section, select the Lookup Adaptor (e.g., Shopify, a custom Lookup Adaptor) you want to search.
Depending on the Lookup Adaptor selected, other lookup fields may appear specific to each Lookup Adaptor, which can be used as additional search attributes to test. For example, you can enter the Customer's email address as a query to test the Lookup Adaptor.
Attributes (and the labels) that appear depend on the configured Search Query Attributes. For example, if in your Custom Lookup Adaptor Search Query Attribute, the attribute/label shows searchLoyalty / Loyalty Number and searchMemberID / Member ID, then the additional attributes that appear in the Debug Lookup Adaptor section search are Loyalty Number and Member ID.
Click Test.
What happens next depends on whether a Customer matches your search.
Timed out/Unexpected response
Lookup Adaptor search requests times out in 15 seconds if it receives no response from your external system. "The Lookup Adaptor returned an unexpected response" error may also appear. Possible causes include a slow internet connection or a large payload. If you continue to experience timeout issues, something improperly configured with their Lookup Adaptor might prevent the search from completing.
Customer not found
If the Customer is not found in Gladly using the email address you entered, the error "Customer not found in Gladly. Please try again with a different email" and a toast notification indicating "There was an error fetching debug data" appears. Check to ensure the attribute you entered is correct, and try again.
If the Customer is not in Gladly, you can create a new Customer Profile and try searching again. Note that this requires having additional permissions through another role beyond Developer.
Customer found
Gladly tests the Basic Search Workflow and provides results if a matching Customer is found based on the search attributes you used for the query.
You'll see the following if a Customer is found.
[A] – Shows the parameters (attributes) used to query the Customer. Click Expand the request to see the full request payload sent to the Lookup Adaptor.
Note – The debugger adds searchEmail and searchPhone to the query object. These values will not be included in the production lookup requests.
[B] – Click Expand the response to see the detailed response from the Lookup Adaptor, along with any errors found.
[C] – Select the Customer you want to continue testing.
From [C], select the Customer to continue testing, then click Continue.
Gladly proceeds to test the Detailed workflow for the Customer selected and provides results.
Next, check to see if there are errors found or not.
Check for errors
No errors found
If no errors are found, this confirms that the Lookup Adaptor can find the Customer attributes.
Errors found
If there are errors, the tool provides which query parameters were used to search and attributes that do not match that could be causing the error.
You'll see the following if an error is found.
[A] – Shows the query parameters used to create a Detailed lookup request. Click Expand the request to see the full request payload sent to the Lookup Adaptor.
[B] – Displays errors encountered with the Detailed Lookup. These are attributes configured in the Lookup Adaptor used to search and link to custom attributes in your external system. Use this information to troubleshoot if you have issues manually linking a Customer Profile from Gladly. Click Expand the request to see the full response payload returned from the Lookup Adaptor.
Common errors and suggested actions
Below are common errors that may appear and suggested steps you can take to fix the error.
An unexpected error occurred
What you should do:
This means we encountered an unexpected error with processing the Lookup Adaptor response. Make sure that custom attribute values are sent as strings. For example, make sure you’re sending:
ExternalCustomerId is missing from result %d. This must be included in each result.
What you should do:
Note that this warning could mean that the attribute comes from a different Lookup Adaptor. However, if you expect this custom attribute to be updated from this Lookup Adaptor, expand the response to check for spelling mistakes and update your Lookup Adaptor to ensure you are sending the attribute.
The results array should be the first element in the JSON. Expand the response to verify the structure error
What you should do:
Occurs during any lookup where the response does not contain an array of results, with results being the only key in the response. Make sure your response is structured correctly. All of your results should be returned in an array (even if only one match is returned). For example, the structure should look like this:
The email field must be plural.
What you should do:
Validate that the email field in your adapter is labeled emails (plural).
Custom attribute object must be a set of single-level-key-value pairs.
What you should do:
Ensure the custom attribute object uses the correct format (ex., an array).
Unreadable JSON.
What you should do:
Validate that you are sending us valid JSON.
Custom attribute X is not configured in the Profile but is included in the response.
What you should do:
The custom attribute is sent from your Lookup Adaptor but won’t be displayed in the Customer Profile because it is not configured in Gladly. Use the Custom Attributes tool to confirm. To add missing attributes, contact Gladly Support.
Double-check the spelling of the custom attribute in the configuration and in your Lookup Adaptor response.
Customer not found in Gladly. Please try again with a different email.
What you should do:
Try again with a different email for a Customer that does exist.
Create a Customer Profile in Gladly for the email you are trying to use.
Customer attribute X is displayed in the Profile but is not in the response. This attribute will not be updated when data is refreshed from this adapter.
What you should do:
Note that this warning could mean that the attribute comes from a different Lookup Adaptor. However, if you were expecting this custom attribute to be updated from this Lookup Adaptor, expand the response to check for spelling mistakes and update your Lookup Adaptor to ensure you are sending the attribute.
Custom attribute X is invalid. Custom attributes must be sent as strings.
What you should do:
All custom attribute values should be sent as strings. For example, make sure you’re sending:
%d results returned. Detailed Lookup allows only one result.
What you should do:
For lookupLevel: DETAILED, only one result should be returned from your Lookup Adaptor. Update your Lookup Adaptor.
The response must return an array of JSON objects.
What you should do:
Validate your results array only contains JSON responses. Results should return an empty array if no Customer data is returned from the lookup results:[]}.
.svg)
on the top-left corner, then click Contact Gladly Support. Gladly Support's primary operating hours are Monday through Friday, 6 AM to 6 PM Pacific Time but you can submit a request anytime.