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.
On this 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.
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.
For an example of setting up an integration see the setting up an integration: end to end example video.
On this page
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.
Before you begin: find your client secrets
To use the Save As feature you will need to enter Dynamic Content and SFCC client secrets, so to save time find these before you begin.
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.
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
On this page
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}}
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.
On this page
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.