Use the xDB to CDP migration tool

Version: 10.4

This topic outlines the steps involved in installing, configuring, and running the xDB to CDP migration tool in Sitecore Connect.

Before you begin

Make sure you have:

  • A Sitecore Experience Platform (XP) license and an XP instance version 9.0 or later with customer data.

  • A Sitecore CDP license and a CDP instance.

  • An active Sitecore Connect instance.

This walkthrough describes how to:

Install the package in Sitecore Connect

To install the package, you must import it into your xConnect account.

To install the package in Sitecore Connect:

  1. Download the migration package.

  2. Go to the Sitecore Connect portal.

  3. Navigate to Tools > Recipe lifecycle management.

    Recipe lifecycle management in Sitecore Connect

  4. Click the Import tab, and then click Import.

    The Import tab under Recipe lifecycle management in Sitecore Connect

  5. Select the package you downloaded in step 1. The following recipes are displayed:

    An example of imported recipes in Sitecore Connect

    • [XCM] REC001 | Processing Recipe Trigger

    • [XCM] REC002 | Load and Transform Contacts From xDB

    • [XCM] REC003 | Upload Contacts to CDP

    • [XCM] REC004 | Migrate Contacts by ID

    Note

    You will also see the Sitecore XP Connection and Sitecore CDP Connection connections. To connect to your instances, first you need to update their configurations.

Now you have successfully imported the migration package into your Sitecore Connect account.

Establish connection to your XP instance through xConnect

After importing the package, you establish a connection to xDB in your XP instance through xConnect.

Before you establish a connection, you need to get the certificate and key from the .pfx file.

To get the certificate and key:

  1. Start OpenSSL. If you have Git installed, you can find openssl in the following folder:

    cd 'C:\Program Files\Git\mingw64\bin\'

  2. Run the following command in Powershell:

    .\openssl.exe pkcs12 -info -in C:\Users\<YOUR_CERTIFICATE_LOCATION>\Downloads\myCert.pfx

To establish the connection:

  1. In Sitecore Connect, go to Assets > Connections.

  2. Open the Sitecore XP Connection that you imported previously.

  3. Fill in the following information to connect to xConnect:

    • Connection Name - a name that you define for the connection to xConnect.

      This parameter helps identify and manage multiple connections within your Workato account.

    • Certificate - use the value from the xConnect certificate.

      Important

      You must include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

      This is the SSL certificate required for secure communication with the xConnect service. This certificate ensures the confidentiality and integrity of data exchanged between Workato and xConnect.

    • Key - use the value from the xConnect certificate.

      Important

      You must include the ----- ENCRYPTED PRIVATE KEY ----- and ----- END ENCRYPTED PRIVATE KEY ----- lines.

      This is the private key associated with the SSL certificate. This key is used for encryption and decryption purposes during the SSL handshake process.

    • Passphrase - use the value from the xConnect certificate.

    • URL - enter the URL endpoint of the xConnect service.

      This parameter specifies the location where the xConnect service is hosted and accessible.

      • If you have an on-prem instance of XP: go to the <ROOT>\App_Config folder, open the ConnectionStrings.config file, copy the value of xconnect.collection field and paste it into the URL field.

      • If your instance of XP is running on Azure, and you have an XP0 instance, use the URL of the xc-single App service. The URL will have this format:

        https://<YOUR_INSTANCE>-xc-single.azurewebsites.net

      • If your instance of XP is running on Azure, and you have an XP1 instance, use the URL of the xc-search App service. The URL will have this format:

        https://<YOUR_INSTANCE>-xc-search.azurewebsites.net

  4. Click Connect. If connecting is successful, your screen will look similar to this:

    When connecting to XP (xDB) in Sitecore Connect is successful
Note

Depending on your setup, firewalls might prevent Sitecore Connect from connecting to your XP instance. To resolve this issue, consider using IP whitelisting by adding IPs allowed by Workato to your whitelist.

You are now successfully connected to your XP instance.

Establish connection to CDP through xConnect

After connecting to your XP instance, you establish the connection to your CDP instance through xConnect.

  1. In the Sitecore Connect, go to Assets > Connections.

  2. Open the Sitecore CDP Connection that you imported previously.

  3. In the Location field, select the project or folder where you want to store the connection, and then fill in the remaining fields following the instructions on the page.

  4. You can skip Client ID and Client secret.

  5. Click Connect. If connecting is successful, your screen will look similar to this:

    When connecting to CDP in Sitecore Connect is successful

You are now successfully connected to your CDP instance.

Configure the [XCM] REC002 | Load And Transform Contacts From xDB recipe

The [XCM] REC002 | Load And Transform Contacts From xDB recipe already has a built-in filter so that only known contacts are migrated. You can add one additional filter.

If you want to migrate custom facets, you need to manually create mappings for the custom facets before configuring the recipe.

To add a filter to the recipe:

  1. In Sitecore Connect, open the [XCM] REC002 | Load and Transform Contacts From xDB recipe.

    Example of a recipe in Sitecore Connect

  2. In step 5 of the recipe, click Get all contacts from xConnect that contain at least one known contact identifier.

    Example of a step in a recipe in Sitecore Connect

  3. In the upper-right corner, click Edit.

    Example of a recipe step in edit mode in Sitecore Connect

  4. In the Enable Filters list, select Yes.

  5. In the Filter Property list, select the facet, operator, and value.

    Set filter properties for a recipe in Sitecore Connect

  6. In the upper-right corner, click Save to save your changes.

You have now configured the recipe.

Run the migration tool

To migrate contacts with the option of using filters, you need to run the first three recipes in the sequence stated below.

To migrate contacts based on your ID, you only run the fourth recipe.

Before you start

If you have custom facets, you need to configure the mappings before running the recipes. Only built-in facets are mapped to guest data extensions in CDP.

If you have changed the default identity rule in your CDP tenant, or added new rules, you need to configure the guest identifiers before running the recipes.

To migrate contacts with filtering options:

  1. In Sitecore Connect, open the [XCM] REC002 | Load and Transform Contacts From xDB recipe and click Start Recipe.

  2. Open the [XCM] REC003 | Upload Contacts to CDP recipe and click Start Recipe.

  3. Open the [XCM] REC001 | Processing Recipe Trigger and click Test Recipe.

To migrate specific contacts based on their ID:

  • In Sitecore Connect, open the [XCM] REC004 | Migrate Contacts by ID recipe and click Test Recipe.

Tip

Workato provides real-time feedback on the status of each step and indicates whether it succeeded, failed, or encountered warnings. To monitor the execution of a job, click the Jobs tab, and then click the individual job.

In Sitecore Connect, monitor the execution of a job.

You have successfully migrated contacts and contact information from your XP instance to your CDP instance.

Do you have some feedback for us?

If you have suggestions for improving this article,