| REQUIRED USER ROLE Developer or Administrator |
Use the Autolinking + Detailed Workflow debugger tool to understand what happens when Customers are automatically linked or unlinked to an external system. Using this tool, you can check for errors, view custom attributes, show query attributes, and more.
Before you start #
Before you use the Autolinking + Detailed Workflow debugger tool, we recommend you first review the following:
- Users with only the Developer role cannot create or search Customer Profiles. To inherit this permission, assign the Task User role along with Developer.
- Searching for a Lookup Adaptor that doesn’t have an Auto-Linking field attribute activated prevents any lookup attempt.
- Review What is the Lookup Adaptor Debugger for information on when to use the debugger, access requirements, and more.
- See the Lookup Adaptor Autolinking Search FAQs for common issues experienced with Autolinking Customers.
How to use the debugger #
- Click
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 Autolinking + Detailed Workflow, click Test Workflow.
on the top left corner of the screen.Here, you can search and find issues that may prevent automatically 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 and/or phone number (country code + area code + phone number) in the Search for Customer in Gladly section.
- If you enter the Customer’s email address and phone number when searching, Gladly will attempt to find the Customer 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.
- Click Test.
What happens next depends on whether a Customer matches your search.
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. 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 #
If a matching Customer is found based on the search attributes you used for the query, Gladly tests the Autolinking Search Workflow and provides results.
Check to see whether there are errors found or not.
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.
Check for errors #
No errors found #
If there are no Autolinking and Detailed lookup errors, this confirms that the Lookup Adaptor can find the Customer attributes and can automatically link attributes from the external system to Gladly.
Errors found #
The Autolinking workflow test looks at two things and may return an error in one or both.
- [A] Shows the query parameters used to create an Autolink request. Click Expand the request to see the request payload sent to the Lookup Adaptor.
- [B] Checks search query parameters like email and phone number to link Customer data to an external system for errors automatically. Click Expand the response to see the full response payload from the Lookup Adaptor.
- [C] Shows the query parameters used to create a Detailed lookup request. Click Expand the request to see the request payload sent to the Lookup Adaptor.
- [D] Displays errors encountered with the Detailed Lookup. These are attributes configured in the Lookup Adaptor used to search custom attributes in your external system. Use this information to troubleshoot if you have issues automatically linking a Customer Profile to an external system. Click Expand the response to see the full detailed response payload 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.
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.
- Work with an admin or agent to create a customer in Gladly for the email you are trying to use.
- Request to be given the Agent or Task User role so that you can manually search for customers in Gladly or create customers yourself.
The Gladly Customer Profile has no data. Add an email or phone to continue the test.
What you should do:
- The Gladly profile you are attempting to test with has no populated data, meaning auto-linking cannot occur. If you want this Profile to be auto-linked, update the Gladly profile with an email or phone number and try testing again with the debug tool.
Customers are a candidate for auto-linking. Auto-linking can only take place when there is one unique match.
What you should do:
- This means that auto-linking will not happen for the Gladly Customer associated with the email you entered because your Lookup Adaptor returned more than one result. If you want auto-linking to occur, you must fix the data in your external system or update your Lookup Adaptor to ensure only one match is returned.
There are no Auto-Linking fields for this app. Select the field that activates auto-linking in the <app name> settings page.
What you should do:
- You need to select which attributes for auto-linking. Select this from an app’s settings page to activate auto-linking.
No Customers were returned from the lookup adapter.
What you should do:
- The Lookup Adaptor did not return any results, so auto-linking will not occur. If you want this Customer Profile to be auto-linked, update the data in your external system or update your lookup adapter to return one match for the emails and/or phone sent in the request query.
The Customer is unlinked. A Customer that has previously been unlinked will not auto-link.
What you should do:
- Once a Customer Profile has been unlinked, we will not auto-link back to an external system. If you want this Customer to be auto-linked again, you need to manually link the Customer again.
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.
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.
- Double-check the spelling of the custom attribute in the configuration and your Lookup Adaptor response.
Unreadable JSON.
What you should do:
- Validate that you are sending us valid JSON.
The lookup adapter returns an expected error: 404
What you should do:
- This may occur when the Customer has pointed their Lookup Adaptor to the wrong URL. Check your App configuration on the Settings page.
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:
The results array should be the first element in the JSON. Expand the response to verify the structure error
What you should do:
- This 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. Your results should be returned in an array (even if only one match is returned). For example, the structure should look like:
