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.

For an example of setting up an integration see the setting up an integration: end to end example video.

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 "Salesforce Commerce Cloud integrations".

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.

To create a new integration from an existing one you can use the "Save as" feature. See Using Save As to create 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.

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.

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.

Field	Description
VSE URL	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.
Content rendering service wrapper template	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 an example of a handlebars template for use with a content slot integration see the slot mapping page. 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.

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:

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

Field	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.

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.

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.

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.

Specifying the update method

In the update method field you choose how you'd like to manage content assets by choosing either "PUT" or "PATCH".

The update method depends on your chosen workflow and specifies what the integration should do when a content item is published in Dynamic Content.

• Choose PUT to create or overwrite a content asset in SFCC Business Manager when you publish a content item in Dynamic Content.

• Choose PATCH to create a content asset if one does not exist, but partially update it if it does exist. If you choose this update method then any fields managed in Dynamic Content must be mapped in your field mappings or localized field mappings.

The examples in this section use the "PUT" update method.

For more information about "PATCH" see the using the PATCH update method page.

Specifying a content repository

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.

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

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.

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.

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

Using Save As to create an integration

You can quickly create a new integration from an existing one using "Save As". This will set up a new integration using the label that you specify and copy fields from the original integration.

To create a copy of an integration using Save As, open an existing integration. In this example we're using one with the label "RefArchGlobal slots".

In order to enable the Save As button you must enter values for the Dynamic Content and Salesforce Commerce Cloud client secrets. The secrets are not displayed when you view an integration and so cannot be copied to a new integration. To enter the client secrets, click the "edit" button to the right of the Dynamic Content and SFCC client secret fields and enter a valid secret in each one.

When you have entered the client secrets, the "Save As" button will be enabled.

Click the Save As button. The Save As dialog will be displayed. Enter a label for the new integration and click the "Ok" button.

A new integration is set up on the hub and you can edit it as normal.

Video: setting up an integration: end to end example

In this video we show you how easy it is to set up a Dynamic Content SFCC integration. We'll walk you through the end to end process of setting up a content slot integration, from creating and registering the slot schema to adding the slot to an edition, scheduling content and previewing in the SFCC storefront.

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:

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}}

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.

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.

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 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.

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.

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 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.

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.

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

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.

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.

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