Working with XConnect Client API - Configuration - Part 1


Introduction

Before we go deep into this topic, lets understand what xConnect is? And the basic terminologies around it. 

xConnect is a service layer, which is actually sitting between xDB collection database and the external systems. The external system could be any API or Web Application which can connect to xConnect.

 

 

Now if you see closely to the databases which are being created while installing Sitecore, then it includes databases with name like {InstanceName}_Xdb.Collection.Shard0 and {InstanceName}_Xdb.Collection.Shard1. 

 

These 2 databases comprises of xDB collection and ShardMapManager is a central database that manages the mapping between sharding keys and the corresponding shard databases I.e Shard0 and Shard1 in our case. 

If you checkout the tables in one of the shard database, then it will consists below list of tables, showing few of them:


 The highlighted tables are the important ones. Sitecore stores all data related to contacts, interactions, campaigns, and other experience-related information in these tables.

So what we are doing?

In this blog, I will basically show you how you can retrieve Sitecore Interactions and Contacts by creating an external application through a trusted channel. 

This application will help you to understand the steps involved while connecting to xConnect API, that may help at some part of your journey in Sitecore.

Configuration

For the implementation, I have created an Asp.Net MVC application and installed Sitecore.XConnect version 10.1.4 from Nuget Package Manager in Visual Studio.

Step 1: Adding the Keys in Web.config 

In my case the the hosting url of xConnect is https://localsc10xconnect.dev.local 

<connectionStrings>

  <add name="sitecore.reporting.client" connectionString="" />

  <add name="sitecore.reporting.client.certificate" connectionString="StoreName=My;StoreLocation=LocalMachine;FindType=FindByThumbprint;FindValue=ac6947554c4a0409dddee7d251f75ec154a8a386" />

  <add name="XConnectClient" connectionString="https://localsc10xconnect.dev.local/odata" />

  <add name="XConnectclientConfig" connectionString="https://localsc10xconnect.dev.local/configuration" />

</connectionStrings> 

Thumbnail value is the xConnect ssl certificate thumbprint. 

You can extract it from your xconnect site's basic settings from IIS or opening the site url in browser and extract the certificate thumbprint from there 

Step 2: Create a base class called MigrationSettings

public class MigrationSettings

{

    public MigrationSettings()

    {

        XConnectClient = System.Convert.ToString(ConfigurationManager.ConnectionStrings["XConnectClient"].ConnectionString);

        XConnectClientConfig = System.Convert.ToString(ConfigurationManager.ConnectionStrings["XConnectclientConfig"].ConnectionString);

        SitecoreReportingClientCertificate = System.Convert.ToString(ConfigurationManager.ConnectionStrings["sitecore.reporting.client.certificate"].ConnectionString);

    } 

    public string XConnectClient { get; }

    public string XConnectClientConfig { get; }

    public string SitecoreReportingClientCertificate { get; }

} 

Step 3: Create XConnectClientReader Class 

public static async Task<XConnectClientConfiguration> GetClient(XConnectSettings settings)

{

    CertificateHttpClientHandlerModifierOptions options =

        CertificateHttpClientHandlerModifierOptions.Parse(

            settings.SitecoreReportingClientCertificate);

    options.AllowInvalidClientCertificates = "true";

 

    // Optional timeout modifier

    var certificateModifier = new CertificateHttpClientHandlerModifier(options);

 

    List<IHttpClientModifier> clientModifiers = new List<IHttpClientModifier>();

    var timeoutClientModifier = new TimeoutHttpClientModifier(new TimeSpan(0, 0, 20));

    clientModifiers.Add(timeoutClientModifier);

 

    // This overload takes three client end points - collection, search, and configuration

    var collectionClient = new CollectionWebApiClient(new Uri(settings.XConnectClient), clientModifiers, new[] { certificateModifier });

    var searchClient = new SearchWebApiClient(new Uri(settings.XConnectClient), clientModifiers, new[] { certificateModifier });

    var configurationClient = new ConfigurationWebApiClient(new Uri(settings.XConnectClientConfig), clientModifiers, new[] { certificateModifier });

 

// Including all Models, You can add your custom models here like I did for CustomContactModel.UserModel.Model

 

    XdbModel[] objModels = new XdbModel[2] { CollectionModel.Model, CustomContactModel.UserModel.Model };

    var cfg = new XConnectClientConfiguration(

        new XdbRuntimeModel(objModels), collectionClient, searchClient, configurationClient, true); 

    try{

        await cfg.InitializeAsync();

    }

    catch (XdbModelConflictException ce)

    {

        LogHelper.Error(ce.Message, ce, "XConnectClient_CriticalError");

        throw;

    }

    catch (Exception ex)

    {

        LogHelper.Error(ex.Message, ex, "XConnectClient_CriticalError");

        throw;

    }

    return cfg;

} 

In above class, some of the settings are very important to understand. 

options.AllowInvalidClientCertificates = "true"; 

In my preprod environment, the value for AllowInvalidClientCertificates was set to true, BUT in prod environment, I was getting error related to thumbprint, so in that case I need to set it false to proceed.

If your configuration are correct, you must be able to connect to xConnect API:

 



Conclusion:

In this blog, we understood what xConnect Client API is and how we can configure our app to initiate the direct connection with it. 

In my next blog we will see how we can extract the contacts and interaction from xDB using the same application.

Comments

Post a Comment

Popular posts from this blog

Working with Device Detection Module in Sitecore

Image
  What is Device Detection in Sitecore? Sitecore has an in-built feature called Device Detection which helps to detect at which device the content is shown into. When I say in-built that means its included as a standard feature in Sitecore XP 9.0 and later. This feature is also present in Sitecore XM Cloud , hence you do not need to buy a separate add-on or module to utilize device detection features.   The information gather from Device Detection Module can help content makers, allowing them to tailor the website experience based on the device type they are accessing it with, such as by displaying different layouts or content depending on screen size and capabilities. For Example, An iPhone and Android users might be looking at different content on same page.   Moreover, developers uses the same mechanism to personalize the components based on the device specific audience. They can setup Device Layout based on specific device parameters or can use the in-built rules...
Read more

Setup A/B Testing in Sitecore - Part 1

Image
  Setup A/B Testing in Sitecore - Part 1 In this article we will understand What is A/B Testing, Types of Testing in Sitecore, Actual Use Case and later we will see how we can setup A/B Testing in Sitecore XP solution with Rendering having different data source items.   Before we go further, lets understand WHAT IS A/B Testing ? A/B testing, also known as split testing, is a method used in marketing and product development to compare two versions of something to determine which one performs better. In an A/B test, two versions, A and B, are created, with one varying element between them. This element could be anything from the wording of an email subject line, the design of a web page, the placement of a button, or even the pricing of a product.   The versions, A and B, are then randomly  shown to similar audiences or users, and their responses are measured and compared. The version that performs better in terms of predefined metrics (such as click-through rate, conv...
Read more

Working with Webhooks in Sitecore - Part 1

Image
  Working with Webhooks in Sitecore - Part 1 In this blog we will understand the concept of Webhooks and how we can use them in Sitecore. So before jumping into Webhooks in Sitecore, first lets understand what webhooks are?   What is a Webhook? They are typically created to connect/link different applications. They are much like API but different from them. Webhooks are one way that apps can send automated messages or information to other apps.   Consider an example below:     Suppose, there is a user facing front application which showcase the product catalogs to its customers. This application is responsible for booking an order from its users. BUT the logistics is handle by different application.   The second application (logistic app) has setup a webhook which is exposed over http and waiting to receive any confirmed orders. Once someone place any order which can be called as an event for the first application, then along with its operation it is passin...
Read more