Sitecore OrderCloud Documentation

docs

Portal login

Bidirectional Content Hub Integration

Published by DJ Steinmetz on July 3, 2024

Last updated on July 10, 2024

The bidirectional integration between OrderCloud and Content Hub aims to streamline the process of managing your product data, from content to commerce.

OrderCloud to Content Hub

There are two main cases in which this integration will prove useful. If you have existing product data from another system that you would like to programmatically import into OrderCloud or, you have an existing marketplace with product data in OrderCloud and you would like to begin using Content Hub to manage your product content. It is ideal to leave OrderCloud in charge of commerce and product visibility concerns, while Content Hub manages all of the content and images for a product. Ensure you have the integration configured before you run any import or EntitySync of your product data.

If you have existing product data in OrderCloud, you can make use of EntitySync to export your product data and sync it to Content Hub.

The integration between OrderCloud and Content Hub creates a product shell in Content Hub in your specified schema any time a product is created in OrderCloud. The intent of this integration is to allow seamless editing of product content if you create products in OrderCloud. No additional product changes/updates in OrderCloud will be synced to Content Hub, the integration is only meant to create a record in Content Hub for you.

To enable the integration, create a new DeliveryConfiguration in OrderCloud. You will need your Content Hub API Key that you create in the steps below.

{
  "ID": "contenthub",
  "Name": "ContentHub",
  "Enabled": true,
  "DeliveryTargets": {
    "ContentHub": {
      "ApiKey": "{Your Content Hub API Key}",
      "Endpoint": "{The Base URL of your Content Hub instance}",
      "TargetSchemaName": "{Schema name that products should be created to. e.g. M.PCM.Product}",
      // OPTIONAL. Default behavior syncs ID, Name, and Description properties to fields of the 
      // same name in Content Hub. If left null, ensure your Content Hub target schema contains 
      // properties with the aforementioned names.
      "ConfigData": {
        "Mapper": {
          "ID": {
            "Property": "{The name of your Content Hub unique ID field}",
            "DefaultCulture": null // ID should not be multi-language.
          },
          "Name": {
            "Property": "{The name of your Content Hub Name field}",
            // OPTIONAL. If non-null, set to the name of the DefaultCulture string you wish to sync to 
            // in Content Hub. If null, it is assumed the field is not multi-language.
            "DefaultCulture": null
          },
          "Description": {
            "Property": "{The name of your Content Hub Description field}",
            "DefaultCulture": null
          }
        }
      }
    }
  }
}

Then create a ProductSynchronization record in OrderCloud. Note that the request body field “SyncProductChanged” accounts for both changes and creations. In the case of this integration, we are only syncing products on create.

{
  "SyncProductChanged": true,
  "DeliveryConfigID": "{the ID of your DeliveryConfiguration}" // e.g. contenthub
}

Now that the configuration is complete, if you create a new product in OrderCloud filling out values for ID, Name and Description, you should see a new entity created in Content Hub - ready for you to seamlessly manage content!

Content Hub to OrderCloud

Configuring the necessary Action and Trigger combination in Content Hub enables the creation of a Product record in OrderCloud any time an entity of a specified schema in Content Hub is created or modified. This integration tracks changes to three properties you define as a unique ID, Name and Description on your Content Hub model. These properties mapped to OrderCloud’s Product.ID, Product.Name, and Product.Description will be kept up to date with the values in Content Hub. The integration will also give you the option of syncing flat properties to OrderCloud’s Product.xp (non multi-language/taxonomy fields), and will also sync Content Hub asset Public Links to OrderCloud’s Product.xp.Images as an array of objects containing URLs for the Original, Thumbnail and Preview - depending on the configuration of the assets' public links. This allows for seamless administration of commerce capabilities for the product entities you are already managing in Content Hub.

Your adoption strategy will look slightly different depending on if you are a new or existing Content Hub user. If you are an existing Content Hub user, you need to identify properties you would like to sync to OrderCloud's Product.ID, Product.Name and Product.Description properties. The field you sync to Product.ID needs to be a unique field.

Configure Content Hub to OrderCloud Integration

As an existing Content Hub user, it is likely that you already have your tenant configured in a way that works for your business. With this in mind, we can configure your existing data model to work for the integration, enabling seamless adoption.

OrderCloud Configuration

  • Configure an API Client for the integration

    • Name it anything you like, something descriptive like “Content Hub Integration”

    • Add a ClientSecret

    • Select “AllowAllSellers”

    • Configure the default context user. Make sure this user is assigned a security profile that has ProductAdmin at minimum.

    • Take note of the ClientID and ClientSecret, as you will need these for creating a Content Hub Action.

    • Take note of the BaseURL for your specific region/environment, as you will need this for creating a Content Hub Action.

Content Hub Configuration

  • Identify your target Schema

    • Which of your existing schemas represents your products? Identify which of your schemas represents the entities you would like to be synced to OrderCloud in order to manage commerce functionality, bridging the gap between content and commerce.

    • When choosing your schema, make note of a field that you have designated as unique, you will need a unique field to sync to OrderCloud’s ID property. If you do not have a unique string field in your schema, you can follow the steps below to add one.

If your schema does not have a unique field, use the following steps to add one.

  • Navigate the settings page for that schema

  • Add a new string property member to the schema called ID. This name is just a suggestion, feel free to name it whatever makes sense for you, and make note of the name. Mark the property as unique and click save.

Create an API key for the integration

  • Click on Users from the settings page

  • Either create a new user to be used for the integration as an “API User”, or create a new user

  • Click the key icon for API Token

  • Click New token

  • Save this token, it will never be shown to you in the UI again - so make note of it, you will need it in future steps

Ensure your API User has the correct permissions to be able to view and edit entities.

Configure a new Action

  • You can name this anything you want, make it descriptive something like “OrderCloud Sync”.

  • Select “API Call” in the type dropdown

  • The POST Method should be automatically selected, if it is not, select “POST” as the method.

  • The API URL is dependent on the region of your OrderCloud environment. Find the URL for your respective region and copy it exactly.

Endpoint

Region

https://uswest-integrations.ordercloud.io/api/v1/productsync/contenthub

US West

https://westeurope-integrations.ordercloud.io/api/v1/productsync/contenthub

Europe West

https://useast-integrations.ordercloud.io/api/v1/productsync/contenthub

US East

https://japaneast-integrations.ordercloud.io/api/v1/productsync/contenthub

Japan East

https://australiaeast-integrations.ordercloud.io/api/v1/productsync/contenthub

Australia East

  • Leave the timeout at 30s. We do not need any headers.

  • For Values, use the following table to enter your values. Make sure you copy the keys exactly. Copy and pasting from this document will help prevent typos.

Key

Description

ClientID

The ClientID which was created for the integration

ClientSecret

The ClientSecret which was created for the integration

Endpoint

The base API URL for your specific OrderCloud region and environment. You can get this URL from your OrderCloud Portal API Console screen. The list of possibilities are here: OrderCloud Supported Regions and Environments .

SyncSchemaName

This is the name of the schema that we identified earlier. If utilizing Content Hub's Product module, M.PCM.Product will work.

BaseUrl

BaseUrl is the base URL of your Content Hub API

ApiKey

This is your API Token you created using your user designated as an API User

DefaultCulture

This is optional. If you have multi-language/cultures configured for your Content Hub tenant, and any of your designated sync fields utilize multi-language, you will need to populate this value. Enter the value for which culture you would like to sync to OrderCloud. E.g. "en-US"

Map_ID

Map_ID represents a property on your schema that you wish to use for the ID property in OrderCloud. This is the property that you identified or created in your schema as the unique string property.

Since the integration will need to know both the key name, and the resolved value - use the following format for the value:
PlainTextSchemaKey={PlainTextSchemaKey}

In our example, we simply used "ID", so this value would look like: ID={ID}

This same format is used for all map properties.

Map_Name

Map_Name represents a property on your schema that you wish to use for the Name property in OrderCloud. This will help you identify your OC Products easier.

Map_Description

Map_Name represents a property on your schema that you wish to use for the Description property in OrderCloud.

Map_xp (EXPIREMENTAL)

Map_xp is an experimental property that does not yet have full support. Values will only be synced one direction: from Content Hub TO OrderCloud.

The value of Map_xp will use the same value resolver syntax with the brackets ({}) using your schema keys, however it will be in a modified JSON format. To sync values from Content Hub to OrderCloud xp, use proper JSON formatting WITHOUT the beginning and ending bracket. To resolve values, you will wrap your bracket syntax with double quotes.

e.g. "MaterialCode": "{MaterialCode}", "UOM": "{UOM}"

Notice that this would be proper JSON if we added brackets to the beginning and end of the string.

Configure a new Trigger

  • You can name this trigger anything you want, make it descriptive something like “OrderCloud Sync” which matches our Action. For objective, check all 3 boxes for creation, modification and deletion. For execution type, click “In background”.

  • Configure a trigger for your chosen schema, add any properties that you would like to trigger an event off of.

Image Syncing

  • If there is an image property, include this as well. Our example schema has an image property Asset which is represented by the relationship PCMProductToAsset. Make note of this relationship name, as it will come into play later on.

  • Next, configure two more trigger conditions for M.Asset and M.PublicLink following the screenshot for which properties to configure.

static page image
  • Select the Action for the trigger we just configured

    • Now that we have configured the trigger, switch to the “Actions” tab and select the Action that we configured in the previous step.

  • Save the trigger.

With that, the integration should be fully configured. Test it out by creating an Entity of your specified type, then attempt to “GET” the product in OrderCloud and if the product exists, you can celebrate that you now have a functioning bidirectional integration between OrderCloud and Content Hub.


Still have questions?
Ask in our Community Channel

Content Powered By
Sitecore Logo

© Copyright 2024, Sitecore OrderCloud®. All rights reserved.

Contact Us
Privacy Policy
Sitecore