My client's lead flow includes capturing form data into a custom database. Each record contains an xDB Contact ID to correlate the data with the data captured in xDB directly. We had a scenario where we had hundreds of records in the custom database where the xDB contact ID was missing, likely due to a networking issue between the CD and xConnect.
I needed a way to match users captured in the custom database against the data in xDB to obtain an existing xDB contact ID. Luckily, Sitecore's documentation provides some sample code to help get me started: xConnect Client API (C#) (sitecore.com)
Thus was born, the...
🧰 xDB Contact Lookup Utility
The utility is your standard .aspx file that can be dropped into the/sitecore/admin folder or at the root of CM instance. It combines a series of xConnect API calls to search for contact information in the xDB. Applicable parameters include email address, first name, last name, or xDB contact ID.
It can be used in two ways:
First, through the UI (as shown above), you have the ability to populate text boxes to obtain parameters and view the result list on the page.
Secondly as a simple rest endpoint, with the ability to pass parameters into the URL and return a JSON response containing a matching xDB contact ID.
For example:
/xDB-Contact-Lookup.aspx?email=test@test.com&firstName=test&lastName=test
👨💻 Code Breakdown
Page_Load
The Page_Load event checks if a query parameter named "email," "lastName," or "firstName" are present in the URL.
If at least the "email" parameter is present, the method calls the SearchForContactIdByEmail .If the lastName and firstName parameters accompany the email parameter, the SearchForContactIdByName method is also used to search for a contact. The search results are returned as a JSON response which contains an xDB contact ID of the first match or "NoMatch" if no match was found. The JSON string is written to the HTTP response, ending the response. If the "email" query parameter does not exist, the method does nothing and loads the UI.
btnLookup_Click
This button click handler retrieves user input from four text boxes for known contact ID, email, last name, and first name. If the user input is for a known contact ID, it calls the SearchForContactById method to retrieve the contact's information and displays it in an HTML table.
If there is no matching contact, it displays a message saying that no contact was found.
If the user input is for email, last name, and/or first name, it calls SearchForContactIdByEmail and/or SearchForContactIdByName methods to retrieve contact information and displays it in an HTML table.
If there are no matching contacts, it displays a message saying that no contact was found.
There are three methods implemented for using the xConnect API:
SearchForContactById
This method searches for a Contact object in xDB using a known contact ID. The method SearchForContactById takes a string parameter knownContactId and returns a Contact object. The method first converts the knownContactId string to a Guid, creates an instance of Sitecore.XConnect.Client.XConnectClient, and uses the Get method of the client object to retrieve a Contact object using a Sitecore.XConnect.ContactReference object created from the Guid.
It also uses a Sitecore.XConnect.ContactExpandOptions object to specify which facets of the Contact object to retrieve.
If the Get method throws an XdbExecutionException, the method catches the exception and returns null.
SearchForContactIdByName
This method searches for a list of Contact objects by their LastName and FirstName facets of PersonalInformation.
SearchForContactIdByName takes two string parameters, lastName and firstName, and returns a list of Contact objects.
Inside the Sitecore.XConnect.Client.XConnectClient using block, the method creates an IAsyncQueryable object named queryableLastName that represents a xConnect API query to xDB. The query retrieves all contacts where the LastName and FirstName facets of PersonalInformation match the values of the lastName and firstName parameters.
The query then sorts the results in descending order of LastModified. The WithExpandOptions method is used to specify which facets of the Contact object to retrieve. The method then retrieves the query results using a batch enumerator, which is added to a List<Contact> object named idsList.
If the query throws an XdbExecutionException, the method catches the exception and returns null.
SearchForContactIdByEmail
This method searches for a list of Contact objects by their EmailAddress and optionally their LastName and FirstName facets of PersonalInformation.
SearchForContactIdByEmail takes three string parameters, email, lastName, and firstName, and returns a list of Contact objects.
Inside the using block, the method creates an IAsyncQueryable object named queryable that represents a xConnect API query to the xDB. The query retrieves all contacts where the PreferredEmail facet of EmailAddressList matches the email parameter value.
The query then sorts the results in descending order of LastModified. The WithExpandOptions method is used to specify which facets of the Contact object to retrieve. The method then retrieves the query results using a batch enumerator, which is added to a List<Contact> object named idsList.
If the firstName and lastName parameters are not empty, the method checks if the FirstName facet of PersonalInformation and LastName facet of PersonalInformation match the values of the firstName and lastName parameters respectively for each Contact object retrieved.
If both match, the Contact object is added to idsList. If the firstName and lastName parameters are empty, all Contact objects retrieved are added to the idsList.
If the query throws an XdbExecutionException, the method catches the exception and returns null.
Final Result
The full code can be copied here. Add the content to a .aspx file and place it where you need it.As always, feel free to modify or build on top of this to satisfy your own requirements.
