Salesforce Commerce Cloud integration

The Dynamic Content Salesforce Commerce Cloud (SFCC) integration makes it easier for developers to integrate Dynamic Content projects with SFCC. The integration is designed to reduce the amount of setup that developers are required to do and to make the integration process simpler for Dynamic Content users and those using and configuring SFCC.

There are two ways of integrating Dynamic Content with SFCC:

  • Mapping slots in Dynamic Content to content slots in SFCC
  • Generating content assets in SFCC from content items in Dynamic Content

On this page we'll explain how to set up and use the slot based integration. The content asset based integration is covered in detail on the SFCC Content Assets page.

The integration architecture

The diagram below shows the main components of the integration. In this section we'll provide an overview of each step of the process for developers and users.

Dynamic Content SFCC integration architecture
Dynamic Content SFCC integration architecture

The integration process

  • Slots in Dynamic Content are mapped to content slots in SFCC. For more information about how to set up this slot mapping see Slot mapping.
  • When an edition is scheduled in the Dynamic Content app, a webhook_event is generated. The webhook service will notify the integration and send it a "payload" containing information about the edition
  • The integration will use this edition data to create a campaign in SFCC. The campaign description will be set to the edition name, the campaign schedule will match the edition schedule and the campaign ID will be set to the edition ID.

  • Once the campaign is created, the integration will request the HTML for each slot in the edition. It makes use of the content rendering Service to convert slot content into HTML format. The content rendering service retrieves the slot in JSON format and converts it into HTML using a handlebars template that you specify.

You can find out more information about how to specify which handlebars template to use see Setting up an integration. Visit the content rendering service section for more detail about how the service uses handlebars templates, together with some examples.

  • For each slot in the edition, the integration will create a slot configuration for the corresponding slot in SFCC. The HTML contents of the slot will be stored in the slot configuration.

  • The slot configuration is then assigned to the SFCC campaign.

The content is now available to be previewed in the SFCC storefront and to be scheduled to go live. If you choose to unschedule the edition in Dynamic Content, then the campaign and slot configurations will be deleted.

Setting up an integration

In order to perform operations in your SFCC environment, such as creating campaigns and slot configurations, the integration uses the Salesforce Open Commerce API (OCAPI). You will need to set up OCAPI credentials for use with the integration and provide those to Amplience at the start of the project. See the Setup page for more details or expand the section below.

Salesforce Commerce Cloud integration setup

When you start a new integration project, you need to provide Amplience with some configuration details so we can set up a new integration between Dynamic Content and your Salesforce Commerce Cloud (SFCC) instance. On this page we've included the details required to set up your integration and how you need to configure your SFCC instance.

For a content asset integration you will need to provide some additional information in addition to the details on this page. See SFCC content assets for more information.

Details you need to provide

You will need to provide Amplience with the following details in order to set up your integration with Dynamic Content.

Property                        Description
SFCC API Client ID In order to allow the Dynamic Content integration to access the Open Commerce API (OCAPI) on your Salesforce instance, create a new API client and provide us with the details. You can add a new API Client from the SFCC Account Manager.
SFCC API Secret When you create an API Client in the SFCC Account Manager, you will also specify an API Secret. See the Setting up a Client ID in SFCC section for more details.
businessManagerURL This is the domain of your SFCC instance.
site This is the site id that you wish to publish content to. Slots in SFCC are site specific.
ismlTemplate This is a template in your storefront cartridge that is used for slots of type HTML. The standard path for SiteGenesis is:
slots/html/htmlslotcontainer.isml
and the standard path for Storefront Reference Architecture (SFRA) is:
slots/html/htmlSlotContainer.isml
API path This is the path to your the Salesforce Open Commerce API (OCAPI) data API on your SFCC instance.
For example:
https://yoursandbox.demandware.net/s/-/dw/data
Note that there must be a valid SSL certificate attached to this domain.
For all sandboxes the SSL certificate is *.demandware.net so if your sandbox URL uses dot notation, for example: mydomain.cust-eu03.dw.demandware.net, it must be converted to dash notation: mydomain-cust-eu03-dw.demandware.net
version This is the version of OCAPI on your SFCC instance that you wish to use.
htmlTemplate This is the handlebars wrapper template that will be called by the integration to convert slot content into HTML. Rather than include all the logic in this top level template, we recommend using the handlebars partials feature to load in templates specific to a particular content type. See the handlebars page for more information on partials.
Note that all handlebars templates, including the wrapper template, must be stored in Content Hub. When you specify the name of the wrapper template it should not be suffixed with ".html", although it will appear as an HTML file in Content Hub.
Dynamic Content hub Each integration is set up for a specific Dynamic Content hub. If you have multiple hubs on your account, then you need to let us know which hub to use.

Setting up an API client in SFCC

In order to allow Dynamic Content to integrate with your SFCC instance, you will need to set up a new API Client in the SFCC account manager. In order to create an API Client, you must log in to the SFCC account manager as an admin user and follow these steps:

  1. In the SFCC account manager, go to the API Client screen. The "Add API Client" screen is shown in the image below.

  2. Click Add API Client

  3. Enter a display name to identify the API Client, for example, "Amplience Dynamic Content"

  4. Enter a password. This will be your client secret.

    Note: leave the sections JWT and OpenID as their defaults

  5. From the "Token Endpoint Auth Method" menu choose "client_secret_basic"

  6. Click 'Add'

  7. Make a note of the API Client ID that is generated.

  8. Provide the API Client ID and the Password that you entered in step 4 to Amplience.

The Add API Client screen in SFCC Account Manager

The newly created API Client will be shown in the list.

The new API Client ID is shown in the list

Open Commerce API settings

To enable the Dynamic Content integration to access OCAPI on your SFCC instance you will also need to configure your OCAPI settings.

  1. In SFCC Business Manager, go to Administration > Site Development > Open Commerce API Settings
  2. From the Select Type field, select ‘Data’
  3. From the Select Context field, select ‘Global’ Note: Most Data API resources are organization-specific, so they support only global client permissions.
  4. In the text field, paste in the following JSON:
{
    "_v": "18.7",
    "clients": [{
        "client_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "resources": [{
            "resource_id": "/sites/{site_id}/slot_search",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }, {
            "resource_id": "/sites/{site_id}/slots",
            "methods": ["get"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }, {
            "resource_id": "/sites/{site_id}/slots/{slot_id}/slot_configurations/{configuration_id}",
            "methods": ["get", "put", "patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }, {
            "resource_id": "/sites/{site_id}/slot_configurations",
            "methods": ["get"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },{
            "resource_id": "/sites/{site_id}/slot_configuration_search",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }, {
            "resource_id": "/sites/{site_id}/campaigns/{campaign_id}",
            "methods": ["get", "put", "patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }, {
            "resource_id": "/sites/{site_id}/campaigns/{campaign_id}/slot_configurations/{slot_id}/{slot_config_id}",
            "methods": ["put", "patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }, {
            "resource_id": "/sites/{site_id}/slot_configuration_campaign_assignment_search",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        }]
    }]
}

Setting the API Client ID

Once you've added the JSON shown above, you must set the client_id property to the API Client ID you created for use with the integration. See Updating your OCAPI settings.
If you have other OCAPI settings that you need to keep, you will need to merge the data

Your OCAPI settings screen should look something like the following image:

OCAPI settings screen in Business Manager

If you're using content asset integration, you will need some additional OCAPI settings. See SFCC Content Assets for more details.

Updating your OCAPI settings

Once you've added the JSON, you will need to modify the values of the following properties.

Property                        Value
_v It is recommended to modify this to match the latest version of the configuration file structure. Please refer to the SFCC Documentation and search for "OCAPI Settings" for more details.
This property is independent of the OCAPI version itself and allows the configuration of resources in any OCAPI version.
client_id Change this to match your API Client ID.
This is required for staging, development and production instances. All sandboxes can use the default client id "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

When you've finished updating these values click "Save".

Slot mapping

The mapping between a Dynamic Content slot and an SFCC content slot is setup when a slot is created in the production view in Dynamic Content. For more information about setting up a slot type to include this mapping, see the Slot mapping page or expand the section below.

Salesforce Commerce Cloud slot mapping

At the start of a Dynamic Content integration, we assume that you have already have content slots set up in Salesforce Commerce Cloud (SFCC). Slots in Dynamic Content are then mapped to the content slots in SFCC.

When an edition is scheduled, the integration converts each slot contained within the edition into HTML format. For each content slot mapped in SFCC, it creates a slot configuration into which it stores the HTML from the corresponding Dynamic Content slot.

For more information about supporting multiple SFCC sites from the same Dynamic Content hub, and specifying to which SFCC site slot content should be delivered see Mapping slots to SFCC sites.

The slot type

The mapping between a Dynamic Content slot and an SFCC content slot is setup when a slot is created in the production view in Dynamic Content.

In your slot type, you need to include an _environment property. An example slot type is shown below. Generally you will have one slot type that will be able to handle any content types that you support and so the enum in the example would usually include more content types.

{
    "$schema": "http://bigcontent.io/cms/schema/v1/schema#",
    "allOf": [
        {
            "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
        }
    ],
    "id": "https://raw.githubusercontent.com/amplience/dc-integrations-sfcc/master/examples/dc-slot-example.json",
    "title": "content-type-slot-example.json",
    "description": "content-type-slot-example.json description",
    "type": "object",
    "properties": {
        "_environment": {
            "type": "object",
            "properties": {
                "sfcc_slot": {
                    "$ref": "https://raw.githubusercontent.com/amplience/dc-integrations-sfcc/master/content-types/sfcc/sfcc.json#/definitions/sfcc_slot"
                },
                "sfcc_category_slot": {
                    "$ref": "https://raw.githubusercontent.com/amplience/dc-integrations-sfcc/master/content-types/sfcc/sfcc.json#/definitions/sfcc_category_slot"
                }
            }
        },
        "content": {
            "allOf": [
                {
                    "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
                },
                {
                    "properties": {
                        "contentType": {
                            "title": "Page Content",
                            "enum": [
                                "http://dev-solutions.s3.amazonaws.com/DynamicContentTypes/res/simpleBanner/contentType/simple-banner.json"
                            ]
                        }
                    }
                }
            ]
        }
    }
}

SFCC environment properties

The _environment property should contain two properties within it sfcc_slot and sfcc_category_slot. sfcc_slot is defined as follows:

{
    "$schema": "http://bigcontent.io/cms/schema/v1/schema#",
    "allOf": [
        {
            "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
        }
    ],
    "id": "https://raw.githubusercontent.com/amplience/dc-integrations-sfcc/master/content-types/sfcc/sfcc-slot.json",
    "title": "SFCC Slot",
    "description": "SFCC Slot",
    "type": "object",
    "properties": {
        "slot_id": {
            "type": "string"
        }
    }
}

And here is the definition of sfcc_category_slot:


{
    "$schema": "http://bigcontent.io/cms/schema/v1/schema#",
    "allOf": [
        {
            "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
        }
    ],
    "id": "https://raw.githubusercontent.com/amplience/dc-integrations-sfcc/master/content-types/sfcc/sfcc-category-slot.json",
    "title": "SFCC Category Slot",
    "description": "SFCC Category Slot",
    "type": "object",
    "properties": {
        "category_id": {
            "type": "string"
        }
    }
}

Folder slots

Folder slots allow you to schedule content to be added to a slot on a folder landing page. If used together with our content asset integration this will give you full control over your folder landing page content.

The sfcc-folder-slot definition is shown below. To make use of folder slots, you will also need to include the sfcc_slot environment property as described above.

{
  "$schema": "http://bigcontent.io/cms/schema/v1/schema#",
  "allOf": [
    {
      "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
    }
  ],
  "id": "https://raw.githubusercontent.com/amplience/dc-integrations-sfcc/master/content-types/sfcc/sfcc-folder-slot.json",
  "title": "SFCC Folder Slot",
  "description": "SFCC Folder Slot",
  "type": "object",
  "properties": {
    "folder_id": {
      "type": "string"
    }
  }
}

An example of how these environment variables are shown in the slot editing form is shown in the image below:

A slot with SFCC environment properties

The Dynamic Content integration supports two types of SFCC content slots: global slots and category slots. A Dynamic Content slot is mapped to a global slot in SFCC by specifying the slot_id, while for a category slot you provide both the slot_id and the category_id (electricals, home etc).

The handlebars wrapper template

When an edition is scheduled, the Dynamic Content SFCC integration will call the content rendering service API with the slot ID of each slot in the edition and the top level handlebars template that was set up when the integration was configured.

Example template

An example of this top level template (contentWrapper.html) is shown below.

For each slot in the edition, the content rendering service will load this template, passing the slot contents in JSON format. The template will convert the JSON into HTML.

For this example we have one slot type, with a URL ending "page-siteid.json". When JSON content from a slot created with this slot type is sent to this template, it will load the "templateChooser" partial to process the content items the slot contains.

contentWrapper.hmtl
{{#if (test this.[@type] (toRegex ".*/page-siteid.json")) ~}}
{{> templateChooser this.content }}
{{~/if}}

The templateChooser template is shown below. In this example the template is only being sent one content item. Depending on the content type, the template will load in the corresponding partial to convert the content to HTML.

templateChooser.html
{{#if (test this.[@type] (toRegex ".*/text")) ~}}
{{> text }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/video")) ~}}
{{> video }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/promobanner")) ~}}
{{> promoBanner }}
{{~/if}} 
{{#if (test this.[@type] (toRegex ".*/splitblock")) ~}}
{{> splitBlock }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/slider")) ~}}
{{> slider }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/image")) ~}}
{{> image this}}
{{~/if}}
{{#if (test this.[0].[@type] (toRegex ".*/image")) ~}}
{{> image this.[0]}}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/externalblock")) ~}}
{{> externalBlock }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/cardlist")) ~}}
{{> cardList }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/card.json")) ~}}
{{> card }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/blog")) ~}}
{{> blog }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/banner")) ~}}
{{> banner }}
{{~/if}}
{{#if (test this.[@type] (toRegex ".*/homepage")) ~}}
{{> homepage }}
{{~/if}}

Example

For an end to end example that takes you all the way from scheduling an edition to previewing the content in SFCC, go to the SFCC integration example page or expand the section below.

Salesforce Commerce Cloud integration example

On this page we walk you through an end to end example of the Dynamic Content - Salesforce Commerce Cloud (SFCC) integration. While it is a simple example, with one piece of content and a single slot, it does show each stage of the integration step by step.

The Dynamic Content edition

We want to put together some content for a 4th of July promotion. Here's the banner that's been chosen, a simple image with text advertising a money off promotion.

The banner for our July 4th promotion

Each slot you create in Dynamic Content can be mapped to a corresponding content slot in SFCC. In this case the Homepage Top Banner in Dynamic Content, to which we want to add the 4th of July banner, is mapped to the content slot with the id "home-page-m" in SFCC.

Mapping the Homepage Top Banner slot to a SFCC content slot

We only want the content to be live on 4th July, so we set up an edition to start at the beginning of the day and end at one minute before midnight. The content should be published at the top of the home page, so the "Home Page Top banner" slot is added to the edition and the "25% off everything" banner is added to the slot.

The edition is then scheduled.

The 4th of July edition

The campaign in Salesforce Commerce Cloud

When an edition is scheduled, the Dynamic Content SFCC integration is notified via the webhooks service. The integration will use the information from the scheduled edition to create a SFCC campaign, create new slot configurations for the corresponding SFCC content slots and populate them with HTML content.

The following sections show you what the integration creates in SFCC.

The Campaigns screen is shown in the image below. We've used the search bar to search for the edition name "4th July Only". Notice that the campaign description matches the edition name and the start and end date is the same as the edition.

The 4th July only campaign has been created

Slot configurations

Open the "Content Slots" section in SFCC Business Manager to view the content slots and find which ones were mapped from the "4th July only" edition. The "home-main-m' content slot was mapped from the Dynamic Content slot contained in the edition and this is highlighted below.

The main home page slot mapped from Dynamic Content

A content slot contains one or more slot configurations or versions. The slot configuration to look for is one with a description that includes the edition name. Open this slot configuration to see its contents.

The slot configuration generated from the 4th July edition

The slot configuration contains the HTML content of the corresponding Dynamic Content slot.

When an edition is scheduled, the Dynamic Content SFCC integration will create a new slot configuration for each content slot in SFCC that corresponds to each slot in the edition. The integration will retrieve the content of each slot in HTML format and store this in the slot configuration. In the SFCC Storefront, the HTML is combined with CSS styling to render the content.

The slot configuration below contains the HTML content of the "Homepage Top Banner" slot from the "4th July Only" edition.

The slot configuration contains the slot contents contained in the edition

Previewing the content

To check that everything from the scheduled edition has been created in SFCC, we can preview the content using the SFCC Storefront Toolkit. In this example, we'll choose 4th July, since that's when the SFCC campaign should be scheduled.

Choosing a date to preview the storefront

A preview of the storefront at this date is displayed and the 25% off everything banner is shown.

The 4th July content is previewed

SFCC integration videos

SFCC content assets

The content rendering service

Webhooks

results matching ""

    No results matching ""