Test Auto-linking + Details Workflow
  • 14 Apr 2022
  • 6 Minutes To Read
  • PDF

Test Auto-linking + Details Workflow

  • PDF

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 who only have the Developer role cannot create or search Customer Profiles. Assign the Task User along with the Developer role to inherit this permission.
  • Searching for a Lookup Adapter that doesn't have an Auto-Linking field attribute activated prevents any lookup attempt.
  • Review What is the Lookup Adapter Debugger for information on when to use the debugger, access requirements, and more.
  • See the Lookup Adapter Autolinking Search FAQs for common issues experienced with Autolinking Customers.

How to use the debugger

  1. Click the menu icon on the top left corner of the screen.
  2. Click Settings.
  3. Under the App Developer Tools category, click Lookup Adapter Debugger
  4. From the Lookup Adapter Debugger page, under Autolinking + Detailed Workflow, click Test Workflow.

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.

  1. 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 both the Customer's email address and phone number when searching, Gladly will attempt first to find the Customer by email, then by phone, then fail if the Customer can't be found.
  2. From the Debug Lookup Adapter section, select the Lookup Adapter (e.g., Shopify, a custom Lookup Adapter) you want to search.
  3. Click Test.

What happens next depends on whether a Customer is matching 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. Check to make sure 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.

Note - Customer Profiles with two email addresses
When a Customer has two email addresses in their Customer Profile, and both email addresses are not associated in your external system, you may get the error the "No customers were returned from the lookup adapter." This happens because the lookup details must match, so missing an email could cause the search not to find a match. If this is the case, remove the email address from the Customer Profile not associated with an external system, and search again.

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

Lookup Adapter search requests times out in 15 seconds if it receives no response from your external system. Possible causes include slow internet connection or there's a large payload. If you continue to experience timeout issues, there might be something improperly configured with their Lookup Adapter preventing the search to complete.

Check for errors

No errors found

If there are no Autolinking and Detailed lookup errors, this confirms that the Lookup Adapter 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 Adapter.
    • [B] Checks search query parameters like email and phone number used to automatically link Customer data to an external system for errors. Click Expand the response to see the full response payload from the Lookup Adapter.
  • [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 Adapter.
    • [D]Displays errors encountered with the Detailed Lookup. These are attributes configured in the Lookup Adapter 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 Adapter.

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.

X 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 Adapter returned more than one result. If you want auto-linking to take place, you need to fix the data in your external system or update your Lookup Adapter 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 Adapter did not return any results, so auto-linking will not take place. 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 is coming from a different Lookup Adapter. However, if you were expecting this custom attribute to be updated from this Lookup Adapter, expand the response to check for spelling mistakes and update your Lookup Adapter to make sure 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 Adapter but won’t be displayed in the Customer Profile because it is not configured in Gladly. Use the Custom Attributes tool to confirm.
  • Make sure to double-check the spelling of the custom attribute in the configuration and in your Lookup Adapter 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 Adapter 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:

  • 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:

Was this article helpful?