SFCC Content Asset Integration

The Dynamic Content Salesforce Commerce Cloud (SFCC) integration can be set up to create SFCC content assets from content items in Dynamic Content. Once the integration is configured, all the user needs to do is create and publish content items of the specified content types from the Dynamic Content production view. The integration will create or update the corresponding content assets in SFCC. You can also specify mappings between properties in Dynamic Content content items and fields in SFCC content assets.

The content asset integration has a similar architecture to the content slot integration described in Salesforce Commerce Cloud integration. The main difference is that the content asset integration described on this page creates content assets in SFCC from content items published in the Dynamic Content production view and does not use any planning and scheduling features.

In order to configure this integration you should be an experienced SFCC developer with knowledge of OCAPI and access to the official SFCC documentation.

On this page we'll provide a technical overview of the integration, explain how it is configured, and provide some examples.

Integration overview

The basic flow of the integration is shown below.

SFCC content asset integration architecture
SFCC content asset integration architecture
  • A content item is published from the Dynamic Content production view
  • A webhook-event (Snapshot-published) is generated. If the content type of the asset is one of the types set up when the integration was configured, the webhook service will notify the integration and send it a "payload" containing information about the content item
  • The integration will determine the ID to use for the corresponding content asset in SFCC. The content asset ID will either be the content item ID or a value entered by the user, as detailed in the Mapping properties to SFCC content asset IDs section.
  • If a content asset with this ID already exists, the content asset will be overwritten, otherwise a new item will be created.
  • The integration will request HTML for the content item from the content rendering service. The handlebars template specified when the integration was configured is used to generate the HTML for the content item. See the example wrapper template for more details.
  • The HTML is then added to the content asset.
  • The content asset name will be set to the content item name, except where a mapping has been configured for the name field.
  • Any additional mapped properties will be added to the corresponding fields in the content asset.
  • Any configured folders will be assigned to the content asset.
  • The content asset is now available to be previewed from within SFCC and can be included in an ISML template or within another content asset.

Setting up the integration

In order to perform operations in your SFCC environment, such as creating content assets, 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 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
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
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".

For the content asset integration you will need to supply some additional information.

Property                        Description
Library 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. See finding the library ID
Content types The content types that will be used to create content assets. For each of these content types you can supply an optional mapping of a property to be used for the content asset ID. See the mapping properties to content asset IDs

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
Finding the library ID

Mapping properties to SFCC content asset IDs

The following JSON shows the additional settings that you need to provide to Amplience in order to configure a content asset integration, including the library ID and the list of supported content types, together with optional mappings. When a content item of one these types is published, the webhook service will notify the integration and create or update a corresponding content asset in SFCC.

You can provide this information in JSON format as shown below.

"contentAssets":{  
      "library":"RefArchSharedLibrary",
      "contentTypes":[  
         {  
            "contentType":"https://s3-eu-west-1.amazonaws.com/amp-product/sfcc/blog-asset.json",
            "mappings":{  
               "id":{  
                  "jsonPath":"$.body.assetId"
               }
            }
         }
      ]
   }

You can choose to map a property in each content type to the SFCC content asset ID. If a mapping exists for a content type, then the integration will use the value that the user entered for the mapped property as the content asset ID when creating or updating the content asset. If no mapping is provided, then when the content item is published in Dynamic Content, the integration will use the content ID as the asset ID.

Note that the property that you use to map to the asset ID must be defined as a string with the following validation.

"properties": {
        "assetId": {
            "type": "string",
            "title": "Content Asset ID",
            "minLength": 1,
            "maxLength": 256
        }

When specifying which property to map, the JSONPath syntax is used. In the example below, for the blog content type, the assetId property is used to map to the content asset ID. Note that body is used as a prefix to specify properties that are defined in the content type schema.

  "contentType": "https://s3-eu-west-1.amazonaws.com/amp-product/sfcc/blog-asset.json",
        "mappings": {
           "id": {
            "jsonPath": "$.body.assetId"
          }
        }

Note that if your property includes special characters you must enclose it in square brackets and single quotes, for example: "jsonPath": "$.body['content-asset-id']"

See the example integration to take a look at how the integration uses this mapping.

Mapping additional properties

You can map Dynamic Content properties to other fields in a content asset. The integration includes support for the following types of fields in SFCC:

  • Standard and custom fields
  • Site specific fields
  • Localized fields

There are three supported ways to map a value to a SFCC field:

  • A JSONPath expression
  • A hard coded value
  • A JSONPath expression with a fallback

Whatever you specify in the mapping will be evaluated and sent to the OCAPI APIs in the expected format. In the following example:

"online": {
    "default": {
            "jsonPath": "$.body.online"
    }
}

Where the resulting value is 'true', the JSON sent to OCAPI is

"online": {
    "default": true
}

The expression must evaluate to the types supported by OCAPI, including boolean, string and number.

Note that inline content is supported in JSONPath mappings, but linked content (such as carousels) is not.

Example mapping: blog content asset content type

The example below demonstrates mapping properties of a simple blog content type to various types of SFCC fields and also shows how to map folders to a content asset.

{  
   "contentAssets":{  
      "library":"RefArchSharedLibrary",
      "contentTypes":[  
         {  
            "contentType":"https://s3-eu-west-1.amazonaws.com/amp-product/sfcc/sfccdev/content-types/simple-blog-contentasset.json",
            "mappings":{  
               "id":{  
                  "jsonPath":"$.body['content-asset-id']"
               },
               "name":{  
                  "default":{  
                     "jsonPath":"$.body['content-asset-name']"
                  }
               },
               "online":{  
                  "default":true,
                  "default@RefArchGlobal":{  
                     "jsonPath":"$.body.online"
                  }
               },
               "searchable":{  
                  "default":{  
                     "jsonPath":"$.body.searchable"
                  }
               },
               "page_url":{  
                  "jsonPath":"$.body['page-url']",
                  "fallback":""
               }
            },
            "folders":[  
               {  
                  "id":{  
                     "jsonPath":"$.body['library-folders'][0]"
                  },
                  "default":true
               },
               {  
                  "id":{  
                     "jsonPath":"$.body['library-folders'][1]"
                  }
               },
               {  
                  "id":{  
                     "jsonPath":"$.body['library-folders'][2]"
                  }
               },
               {  
                  "id":"blog-archive"
               }
            ]
         }
      ]
   }
}

Localized fields

name is defined in SFCC as a localized field. For localized fields you must specify a default value as shown in the mapping below which maps the content-asset-name property in the blog content type to the name field.

    "name":{  
        "default":{  
            "jsonPath":"$.body['content-asset-name']"
        }
     }

Site specific fields

online is an example of a site-specific field and maps the online property from the blog content type to SFCC content asset.

"online":{  
            "default":true,
            "default@RefArchGlobal":{  
             "jsonPath":"$.body.online"
                  }
           }

For site-specific fields you must specify a "default" value, in this case "true". To specify a value for a specific site, use default@sitename so for the "RefArchGlobal" site we are using the value that the user enters for the blog content item.

Fallback values

page_url demonstrates how to set an empty string as a fallback value. If your property is not defined as required in the content type and is included in the mapping then you must provide a fallback that will be used if the user does not enter a value.

"page_url":{ 
             "jsonPath":"$.body['page-url']",
              "fallback":""
            }

A fallback value can be set to any value you want.

JSONPath mapped properties must be defined as required or have a fallback configured

If you use JSONPath to map a property then it must be included in the list of required properties in the content type or a fallback must be configured. For example: "required": ["assetId"]. If no value is entered and no fallback provided, then an error will occur.

Mapping folders to content assets

In the folders section of your mapping, you can assign as many folders as you like to a content asset, to support searching and tagging for blogs, for example. We recommend that you create the folder structure in SFCC in advance, but if you include a folder in your mapping that does not exist in SFCC, the integration will create it at the root level.

"folders":[  
        {  
        "id":{  
            "jsonPath":"$.body['library-folders'][0]"
        },
        "default":true
        },
        {  
        "id":{  
            "jsonPath":"$.body['library-folders'][1]"
        }
        },
        {  
        "id":{  
            "jsonPath":"$.body['library-folders'][2]"
        }
        },
        {  
        "id":"blog-archive"
        }
]

In the blog asset type, we have included the available folders in an enum to make it easier for users to specify which folders should be associated with the content asset in SFCC. The library-folders property from the blog content type is shown below. Note that the array is defined to contain exactly 3 items which matches the entries in the mappings shown above. If you wanted to allow the user to choose fewer than 3 folders, then a fallback value would need to be provided for each entry.

    "library-folders" : {
        "type" : "array",
        "title": "Folders",
        "items":{
            "type":"string",
            "title": "Folder",
            "enum":[
                "mens-blog",
                "womens-blog",
                "shoes-blog",
                "suits-blog",
                "dresses-blog",
                "blog",
                "blog-archives"
            ]
        },            
        "minItems":3,
        "maxItems":3
    }

The final entry in the folders mapping, shows how to assign a hard coded value to a field. In this case the folder "blog-archive" will be assigned to the content asset. You can include hard coded values for any field.

    {  
    "id":"blog-archive"
    }

You can also define slots to contain content that will be added to a folder landing page when the slot is scheduled. See the folder slots section of the slot mapping page for more details.

Additional Open Commerce API setup

For the content asset integration, you will need to add the following to your Open Commerce API (OCAPI) settings. These settings are in addition to the OCAPI setup shown on the SFCC setup page.

{
    "resource_id": "/libraries/{library_id}/content/{content_id}",
    "methods": [
        "get",
        "put",
        "delete"
    ],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
},
{
    "resource_id": "/libraries/{library_id}/content/{content_id}/folders",
    "methods": [
        "get"
    ],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
},
{
    "resource_id": "/libraries/{library_id}/folders/{folder_id}",
    "methods": [
        "get",
        "put"
    ],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
},
{
    "resource_id": "/libraries/{library_id}/folders/{folder_id}/content",
    "methods": [
        "get"
    ],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
},
{
    "resource_id": "/libraries/{library_id}/folder_assignments/{content_id}/{folder_id}",
    "methods": [
        "get",
        "put",
        "delete"
    ],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
},
{
    "resource_id": "/libraries/{library_id}/folders/{folder_id}/sub_folders",
    "methods": [
        "get"
    ],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
}

Content wrapper template example

When an integration is configured, you specify the handlebars template that is used by the Content Rendering Service to convert content items to HTML format to add to the SFCC content asset. This is the top level template that will be loaded when an item of one of the supported content types is published and the integration requests the content item in HTML format. The template should include each content type you support.

An example of this wrapper template is shown below. If you also use the slot based integration, then you should include your supported slot types as well.

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

Simple content asset integration example

Blog content type with a mapped content asset ID

Here's a blog content item in the Dynamic Content production view. In this example the Dynamic Content SFCC integration has been configured to use the assetId property to map to the content asset ID in SFCC. We have entered a value of "winter-blog-asset" in this property. The content item is then saved and published.

Blog content item in Dynamic Content
Blog content item in Dynamic Content

The integration will then generate a content asset in SFCC. If a content asset with this ID already exists, then it would be overwritten.

To find the content asset in SFCC, go to the Merchant Tools section, choose Content and then find the library that was configured for this integration. In this example we are using the library "RefArchGlobal". Search for the content asset using its ID. The winter blog asset is shown in the list.

Searching for the content asset in SFCC using the value entered by the user
Searching for the content asset in SFCC using the value entered by the user

When the winter blog asset is opened you will notice that the name matches the name of the content item in Dynamic Content. The body of the content asset contains the HTML generated from the content item by the Content Rendering Service.

The HTML generated from the content item is added to the body of the content asset
The HTML generated from the content item is added to the body of the content asset

The example below shows a preview of the blog on its own page. In most cases you will include the content item in an ISML template or another content asset.

Previewing the blog content asset
Previewing the blog content asset

An example banner content item is shown below. In this example, when the integration was configured, no mapping section was included for the banner content type. The integration will use the content ID as the SFCC content asset ID.

An example banner content item in Dynamic Content
An example banner content item in Dynamic Content

The content is saved and then published. In order to find the content asset in SFCC, we need to find the content in Dynamic Content, by choosing "Get content ID" from the item's contextual menu in the Content Library.

Finding the content ID
Finding the content ID

We can then search for the content asset using the content ID. The content asset is created with the content ID and the content name.

Searching for the content asset using the content ID
Searching for the content asset using the content ID

The HTML is generated in the same way as the previous example.

The HTML is generated for the banner item and added to the content asset
The HTML is generated for the banner item and added to the content asset

Here's a preview of the content asset in its own page.

Previewing the banner content asset
Previewing the banner content asset

Content asset integration example with multiple mapped fields

In the example below we have mapped the properties in a blog content type to the specified fields in a SFCC content asset. Here's an example blog content item in Dynamic Content.

A blog content item showing the mapped fields
A blog content item showing the mapped fields

When a blog content item is published, the integration will create the corresponding content asset in SFCC. The fields that are specified in the mappings for this content type will be set to whatever values the user entered. For example, you can see the Page URL field set to "December-promotion-url" as entered in the content item. The HTML from the item's content has been added to the body field of the content asset.

The content asset in SFCC

The content asset has been set as online and can be previewed on its own page.

Previewing the blog asset on a stand alone page

The URL contains the Page URL value that the user entered in Dynamic Content content item.

The URL contains the value entered by the user in the content item in Dynamic Content

Content Rendering Service

Handlebars

Webhooks

results matching ""

    No results matching ""