Walkthrough: Configuring the Sitecore Content Hub to Sitecore Commerce connector

Version: 10.0

You configure the Content Hub to Sitecore Experience Commerce (XC) connector to enable synchronization of product updates in Content Hub to the Commerce Engine. Configuration is required in both Sitecore Content Hub, and in Sitecore XC.

This walkthrough describes how to:

Prerequisites

The exchange of information between Sitecore Content Hub and Sitecore XC relies on Microsoft Azure Service Bus messaging service hosted on the Azure platform. You must create the Azure Service Bus Service topic before you proceed with Sitecore Content Hub to Sitecore Experience Commerce connector configuration.
Create an account to access and set up Content Hub Nuget feeds.

Configure triggers and actions in Content Hub

The connector relies on a specific Sitecore Content Hub triggers and actions configuration to automatically push updates to Content Hub product properties and related images to Azure Service Bus messaging.

Note

Content Hub product properties used in the following configuration examples are based on the product properties defined in the ProSaas template included with Sitecore Content Hub 3.2.203.

You must change the values of configuration properties to match the definitions of the Content Hub template you are using.

Create an Azure Service Bus action

Create an action in Content Hub to define connection parameters used to establish connectivity to the Azure Service Bus.

To create an action:

In Content Hub, on the Manage tab, in the Search box, type Actions , and then click the Actions tile.
In the Actions page, click New Action.
In the New Action dialog box, define the following parameters:
- Name - Provide an action name.
- Label - Define a label.
- Type - In the drop-down list, click Azure Service Bus.
- Connection string - Enter the Service Bus connection string, for example, Endpoint=sb://msb-xc-ch-integration.
  
  Note
  
  Refer to this Microsoft Azure Service Bus documentation for a procedure to get the connection string.
- Destination Type - In the drop-down list, click Topic.
- Destination - Enter the name of the Service Bus topic.
Click Save.
Click TEST CONNECTION to make sure that the connection to Azure Service Bus is successful.

Create a trigger

The trigger defines the conditions and user's actions to which the trigger reacts. In this case, you configure the trigger to react to an entity modification event, for example, when a user updates an existing product property.

To create the trigger:

In Content Hub, on the Manage tab, click the Triggers tile.
On the Triggers page, click New Trigger .
On the General tab, define the following trigger settings:
- Name - Provide a name for the trigger.
- Description - Provide a short description of the trigger.
- Objective - Specify the events to which the trigger reacts (when the conditions are met). In the drop-down list, select the Entity creation check box, and the Entity modification check box.
- Execution type - In the drop-down list, click In background. This indicates that the action takes place in an asynchronous way.
On the Conditions tab, in the Match drop-down, click the logical operator Any (to match on any of the three defined entity definitions and conditions).
Click ADD DEFINITION and, in the search field, type product, and then select Product (M.PCM.Product).

Note

In Sitecore Content Hub 3.2.203, the entity Product (M.PCM.Product) maps to a SellableItem Commerce entity in Sitecore XC.

Repeat to add definitions for the following entity types:
- Asset (M.Asset)
  
  Note
  
  The asset entity definition is required to trigger synchronization of changes to the AlternateText property of an image asset related to a product.
- Public link (M.PublicLink)
Add matching conditions for the Product (M.PCM.Product) entity. In the Product (M.PCM.Product) definition area, click ADD CONDITION for each of the following conditions:
- Name (ProductName) has changed
- Long description (ProductLongDescription) has changed
- Master asset (PCMProductToMasterAsset) has changed
Note

You must use the OR logical operator from the option list.

The conditions configuration for the Product (M.PCM.Product) entity should now look like the following:
Add a condition for the Asset (M.Asset) entity type. In the Asset (M.Asset) definition area, click ADD CONDITION, and then add the following condition: AlternateText has changed.
Add a condition subgroup. At the end of the line AlternateText has changed, click the + sign to add each of the following conditions to form a subgroup:
- Product (PCMProdcutToAsset) added item is not empty
- Product (PCMProdcutToAsset) removed item is not empty
- Product (PCMProductToAsset) has changed
Note

You must use the the OR logical operator from the option list.

The configuration should look like the following:
Add matching conditions for Public link (M.PublicLink) entity type. In the Public link (M.PublicLink) definition area, click ADD CONDITION to add the following condition: Relative url (RelativeUrl) has changed .
At the end of the line Relative url (RelativeUrl) has changed, click the + sign to add each of the following conditions to form a subgroup:
- Asset links (AssetToPublicLink) added item is not empty
- Asset links (AssetToPublicLink) removed item is not empty
- Asset links (AssetToPublicLink) has changed
Note

You must use the OR logical operator from the option list.

The configuration should look like the following:

Configure the Content Hub to Commerce XC connector on the Commerce Engine

To configure the Content Hub to Commerce XC connector for data synchronization, you make the configuration changes on the instance of the Commerce Engine that is running the Commerce minions service. The PlugIn.ContentHub.PolicySet-1.0.0.json file exposes the policies you use to configure and enable the Content Hub to Sitecore XC connector. The default path to the JSON file is C:\inetpub\wwwroot\<CommerceMinions_Sc>\wwwroot\data\Environments\PlugIn.ContentHub.PolicySet-1.0.0.json.

Configure connectivity to the Azure Service Bus

The Plugin.Sample.ContentHub.AzureServiceBusPolicy policy contains configuration properties that are necessary to establish connectivity with the Azure Service Bus.

To configure connectivity to the Azure Service Bus:

In the Plugin.Sample.ContentHub.AzureServiceBusPolicy section, replace the values prefixed with "PlaceholderFor..." with the relevant values for your deployment:

RequestResponse

 {
   "$type": "Plugin.Sample.ContentHub.AzureServiceBusPolicy, Plugin.Sample.ContentHub",
       "ConnectionString": "PlaceholderForASBPrimaryConnectionString",
       "TopicName": "PlaceholderForASBTopicName",
       "SubscriptionName": "PlaceholderForASBSubscriptionName"
 },

Configure the synchronization policy

The synchronization policy ("Sitecore.Commerce.Plugin.ContentHub.SynchronizationPolicy") defines Content Hub entities that the synchronization is based on. In the configuration, this is represented by the ProductEntityType value. In the Commerce Engine, this property corresponds to the SellableItem entity type.

The synchronization of data between Content Hub and Sitecore XC relies on a one-to-one relationship between an entity key in Content Hub and a unique Sellable item ID key in Sitecore XC. This is represented in the following code sample by "EntityForeighKey".

The "DefaultCulture" attribute provides support for product property localization. The value of the "DefaultCulture" corresponds to the culture in Content Hub that is mapped to the Commerce Engine default language.

Important

To avoid inconsistent behavior, you should not map a non-localizable Content Hub property to a localized sellable item property in the Commerce Engine.

To change the synchronization policy configuration:

In the SynchronizationPolicy section, replace the default property values shown in the following sample, with actual values from your Content Hub implementation:

RequestResponse

{
   "$type": "Sitecore.Commerce.Plugin.ContentHub.SynchronizationPolicy, Sitecore.Commerce.Plugin.ContentHub",
   "DefaultCulture": "en-US",
   "EntityForeignKey": "ProductNumber",
   "ProductEntityType": "M.PCM.Product",
   "AssetEntityType": "M.Asset",
   "PublicLinkEntityType":"M.PublicLink"
},

Configure a Content Hub client service on the Commerce Engine

To establish connectivity between Sitecore Content Hub and the Commerce Engine, you must configure a Content Hub client service on the Commerce Engine.

To configure a Content Hub client:

In the ContentHubClientPolicy section, replace the property values prefixed with "PlaceholderFor..." with the values used in your Content Hub deployment:

RequestResponse

{
   "$type": "Sitecore.Commerce.Plugin.ContentHub.ContentHubClientPolicy, Sitecore.Commerce.Plugin.ContentHub",
   "EndpointUrl": "PlaceholderForContentHubEndpointUrl",
   "UserName": "PlaceholderForContentHubUserName",
   "Password": "PlaceholderForContentHubPassword",
   "ClientId": "PlaceholderForContentHubClientId",
   "ClientSecret": "PlaceholderForContentHubClientSecret",
   "KnownSSORedirects": "PlaceholderForContentHubKnownSSORedirects",
   "TimeoutInSeconds": 90,
   "RetryCount": 3
},

Define Content Hub product entity properties to XC sellable item property mappings

The ProductSynchronizationPolicy policy defines mappings (in the "PropertyMapping" section) that the synchronization process uses to determine which PCM entity property maps to which XC sellable item property.

To change the default product property to sellable item property mappings:

Use the "FromProperty" property to specify the PCM product property used in your Content Hub deployment, and use the "ToProperty" property to specify the corresponding XC sellable item property to synchronize. You can add as many mappings as required, based on the property values you want to synchronize. The following example shows the default property mappings:

RequestResponse

{
   "$type": "Sitecore.Commerce.Plugin.ContentHub.ProductSynchronizationPolicy, Sitecore.Commerce.Plugin.ContentHub","PropertyMapping":{
      "$type": "System.Collections.Generic.List`1[[Sitecore.Commerce.Plugin.ContentHub.PropertyMap, Sitecore.Commerce.Plugin.ContentHub]], mscorlib",
      "$values": [
        {
         "type": "Sitecore.Commerce.Plugin.ContentHub.PropertyMap, Sitecore.Commerce.Plugin.ContentHub",
         "FromProperty": "ProductName",
         "ToProperty": "Name"
        },
        {
         "$type": "Sitecore.Commerce.Plugin.ContentHub.PropertyMap, Sitecore.Commerce.Plugin.ContentHub",
         "FromProperty": "ProductName",
         "ToProperty": "DisplayName"
        },
        {
         "$type": "Sitecore.Commerce.Plugin.ContentHub.PropertyMap, Sitecore.Commerce.Plugin.ContentHub",
         "FromProperty": "ProductLongDescription",
         "ToProperty": "Description"
        }
     ]
   }
 },

Configure digital asset synchronization

The ContentHub.AssetSynchronizationPolicy policy contains configuration properties that are used to synchronize changes to an asset image when the asset public link is either added, changed, or deleted.

By default, the connector configuration assumes that product images are managed as assets in Content Hub (and not in the Sitecore Media Library).

To disable the synchronization of product images:

Remove the following configuration block from the policy set file:

RequestResponse

{
   "$type": "Sitecore.Commerce.Plugin.ContentHub.AssetSynchronizationPolicy, Sitecore.Commerce.Plugin.ContentHub",
   "EntityToMasterAssetRelationName": "PCMProductToMasterAsset",
   "EntityToAssetRelationName": "PCMProductToAsset",
   "AssetToPublicLinkRelationName": "AssetToPublicLink",
   "AssetsAlternateTextFieldName": "Title"
}

Note

When using product images from DAM, you must ensure that the Storefront is configured to use the appropriate source for catalog images.

Enable or disable the connector configuration

By default, the policy set file JSON is disabled (PlugIn.ContentHub.PolicySet-1.0.0.json.disabled).

To enable or disable the configuration:

Rename the file:
- to PlugIn.ContentHub.PolicySet-1.0.0.json to enable the configuration,
- to PlugIn.ContentHub.PolicySet-1.0.0.json.disabled to disable the configuration.
Bootstrap the Commerce Engine to save the configuration to the Commerce Engine.

Configure the Authoring environment to display DAM assets in the Business Tools

When you use DAM to manage product images, you must add a policy to the Authoring environment configuration so that DAM assets related to products managed in Content Hub are displayed with the corresponding sellable items in the Sitecore XC Business Tools, and more specifically in the Merchandising user interface. The following shows an example of how DAM image assets are displayed for a sellable item in the Merchandising tools:

To configure the Authoring environment to display DAM assets in the Business Tools:

Open the Commerce Authoring environment JSON file. In the Sitecore.Commerce.Engine.SDK folder, the default path to this file is src/Sitecore.Commerce.Engine/wwwroot/data/Environments/PlugIn.Habitat.CommerceAuthoring-1.0.0.json).

Note

If you are using the Adventure Works catalog, you must add the policy to the Adventure Works authoring environment: PlugIn.AdventureWorks.CommerceAuthoring-*.*.*.json file.
In the "Policies collection, add the bizFxPolicy to the JSON file as shown in the following example:
RequestResponse
```
{
  "$type": "Plugin.Sample.ContentHub.BizFxPolicy, Plugin.Sample.ContentHub"
}
```
Bootstrap the Commerce Engine to save the configuration to the Commerce Engine.

Do you have some feedback for us?

If you have suggestions for improving this article,