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.

Setting up a SFCC integration

On this page we'll show you how to add a SFCC integration from the Dynamic Content app. Some of the set up is the same for both content slot and content asset integrations, but to configure a content asset integration requires some additional steps, as explained on the content assets page.

You will also need to include a SFCC client ID and secret. For more details of how to set this up in SFCC Business Manager see the Setting up an API client.

To configure a new Dynamic Content SFCC integration, choose "Integration" from the Development menu in the Dynamic Content app. From the integrations home page click "View or add Salesforce Commerce Cloud integrations".

The integrations home page

A list of the integrations set up on your hub is displayed. From here you can view and edit existing integrations and add a new one.

To add a new integration click the "Add Integration" button as shown in the image below.

Adding an integration

Adding Client IDs and secrets

From the Add Integration screen you can add a content slot integration, a content asset integration or both. Some fields are common to both kinds of integration and required fields are marked with a "*".

Give the integration a label. This can be anything you like and is used to identify the integration in the list and used as a label for its webhook.

While you can create one integration to include both content slots and content assets, we recommend creating a separate integration for content assets so that your integrations are easier to maintain.

The fields common to both content slot and content asset integrations are shown below.

Field                        Description
Dynamic Content Client ID Dynamic Content authentication. Provided to you by Amplience at the beginning of your project.
Dynamic Content Client secret Provided to you by Amplience at the beginning of your project.
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 add the client ID to this field. 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.

Enter these fields in the Add Integration screen, as shown in the image below.

Specifying Dynamic Content and SFCC authorisation details

API path and version

You will also need to specify the API path and OCAPI version:

Field                        Description
SFCC 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
SFCC API version This is the version of OCAPI on your SFCC instance that you wish to use. See the SFCC FAQs for more details.

You should enter the API path for your SFCC instance and the version you wish to use as shown in the image below.

Specifying the API path and version

Content rendering service fields

The final required section contains the fields to configure the integration's use of the Content Rendering service: the virtual staging environment (VSE) URL and the handlebars wrapper template. The VSE URL is the virtual staging domain that the integration will use to deliver content. The URL will be provided to you at the start of your project and will generally be the same URL as set up in your Preview settings in the Dynamic Content app.

For a slot based integration, the wrapper template will be called by the integration to convert slot content into HTML and should include your supported slot types. For a content asset integration the template should include each content type you support.

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.

An example of a wrapper template for a content asset integration is shown below. For each content type, the wrapper will then load the corresponding partial. The use of partials is explained in more detail on the handlebars page.

{{#if (test this.[@type] (toRegex ".*/blog-asset.json")) }}
{{> blog }}
{{/if}}

{{#if (test this.[@type] (toRegex ".*/banner")) }}
{{> banner }}
{{/if}}

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.

The content rendering service VSE and wrapper template

Adding a content slot integration

When the standard fields have been added, you will need to setup content slots or content assets for this integration and then add the fields that are specific to your chosen type of integration.

To add a content slot integration click the "Add Content Slots" button as shown:

Adding a slot integration

To finish configuring the integration you'll need to provide the site id and the ismlTemplate you want to use.

Property                        Description
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

In the example below we're using the site RefArchGlobal. If you want to support multiple SFCC sites, then a separate integration must be created for each site.

Setting up the siteid and ISML template for a content slot integration

To create the integration click the "Save" button. If all the fields have been entered correctly and the client IDs and secrets are correct, you will get a message to tell you that the integration has been successfully created.

The webhook setup for the integration will be displayed as highlighted in the image below. You can click this link to go to view the webhook history as explained in the viewing error logs section.

When an integration is created its webhook is shown

The content slot integration is now ready to use. If you are using the integration's localization features then you will need to enter the locale mappings.

Adding a content asset integration

To add a content asset integration click the "Add Content Assets" button. You will then need to enter the required information to configure content assets.

Adding a content asset integration

In the Library section, fill in the library ID. This is the ID of the shared library within which the content assets will be created, or the site-id in the case of a private library.

Finding the library ID

To find the library ID, go to the Administration section in Salesforce Business Manager, choose Sites -> Libraries and find the library you want to use.

Finding the library ID

You can also optionally set up the integration to only generate content assets from content in a specific Dynamic Content repository. In the example below the MobileFirstGlobalContent repository is chosen, but you can choose to leave the repository field set to "none" so that content assets will be created from all respositories.

If you want to publish to multiple libraries you will need to configure multiple integrations and you can then use a repository filter on each integration to control which content goes to which library.

Specifying the library and repository for a content asset integration

To save the content asset integration click the "Save" button. A message will tell you if the integration has been successfully created.

The content asset has been successfully created and its webhook is displayed

For a content asset integration you'll need to do some additional setup. See Setting up a content asset integration for more details.

Viewing error logs for an integration

When an integration is saved, a webhook will be created and displayed at the top of the window. Clicking this link opens the webhook logs for this integration, allowing you to view all requests and responses and track down any errors.

Clicking the webhook link in the integration window takes you to the webhook logs

Setting locales

If you wish to make use of the Dynamic Content SFCC integration's localization features, then you'll need to provide locale mappings. Add the locale mappings to the Locale mapping section.

Locales can be specified for either content slot or content asset integrations that make use of the localization features

For more information about locale mapping and see the SFCC Localization page.

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

Previewing the content from the Dynamic Content planning view

You can configure a content preview to launch the SFCC Storefront directly from the Dynamic Content planning view. This allows planners to view the content exactly as it is scheduled to appear on the date they choose without having to log on to SFCC Business Manager.

For details of configuring a content preview to work with the SFCC integration see the SFCC setup page.

In the example below the "Pop up edition" is scheduled to go live on 5th March. When the edition is scheduled the integration will create an SFCC campaign, create new slot configurations from the slots in this edition and populate them with HTML content.

A scheduled edition

You can preview the content exactly as it will appear when this edition is scheduled to go live. We'll choose the edition start date of 5th March and select the preview app that is configured to launch the SFCC Storefront.

Choosing to preview content in the SFCC Storefront on the edition start date

The SFCC Storefront is open and displays the home page as it will appear on the edition start date.

The edition content is previewed in the SFCC Storefront

SFCC integration videos

SFCC content assets

The content rendering service

Webhooks

results matching ""

    No results matching ""