Dynamic Content: Developer Edition

Getting Started

The Dynamic Content Developer Edition includes our Accelerators content types and a Salesforce Commerce Cloud integration already setup for you. You just need to do some configuration. On this page you'll find everything you need to get started.

The Developer Edition contains many of the features of the enterprise version, but there are some limitations. See Developer Edition limitations for more details.

In the find out more section of this page we've included links to pages where you can find out much more about the integration to help you take your next steps in Dynamic Content development.

Overview video

Watch the video below for a walkthrough of setting up the Developer Edition. It includes an end to end example of mapping slots in Dynamic Content to SFCC content slots, creating content and adding it to slots in editions, scheduling the editions and previewing the content in SFCC Storefront.

How it works

The integration we've set up for you is a slot based integration. Content is added to Dynamic Content slots which are mapped to content slots in SFCC. These slots are organized into editions, collections of content with a start and end date. When an edition is scheduled, the integration creates a campaign in SFCC, converts the contents of its slots to HTML format and adds the HTML to a slot configurations in the corresponding SFCC slots. You can then preview the content in your SFCC Storefront.

Before you begin

Before you're ready to begin the setup process you'll need:

• An account on SFCC Business Manager
• An SFCC API client ID and secret. You can use the API key and secret from your existing SFCC account or create a new one. Expand the selection below for more details about how to do this.
• You'll also need to configure your OCAPI settings to allow Dynamic Content to use your SFCC account.

Note: If you are using a sandbox, you can just set the ClientID and secret to "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa".

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 newly created API Client will be shown in the list.

Open Commerce API settings

To give permission for Dynamic Content to use your SFCC account, you'll need to configure the OCAPI settings in business manager.

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": "(**)"
        }
      ]
    }
  ]
}

If you have other OCAPI settings that you need to keep, you will need to merge the data

Once you've added the JSON shown above, you must set the client_id property to the API Client ID you are using with the integration or "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" if you're using a sandbox.

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

The "_v" property indicates the version of the configuration file structure. If you want to update this to the latest version, refer to the SFCC Documentation and search for "OCAPI Settings" for more details.

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

Step 1: Configure your cartridge to use the Dynamic Content accelerators

The Developer Edition includes the Dynamic Content accelerators, a collection of content types with the associated rendering code, CSS and handlebars templates. We've already added the accelerators to your account and done most of the setup for you, but you need to take an additional step to make sure that content created from the accelerators looks great in your SFCC account.

In order to make sure that content created from the accelerators renders correctly in the pages containing your slots, you need to modify your cartridge to point to the CSS and JavaScript code that the accelerators use.

Add the following to your HTML <head> section. For example if you are using Storefront Reference Architecture, you can modify the template at cartridge/templates/default/common/htmlHead.isml:

<link rel="stylesheet" href="https://unpkg.com/dc-accelerators-content-rendering-service@v4/dist/styles.min.css"/>
<script src="https://unpkg.com/dc-accelerators-content-rendering-service@v4/dist/utils.min.js"></script>
<script src="https://unpkg.com/dc-accelerators-content-rendering-service@v4/dist/lory.min.js"></script>

Step 2: Locate the slots to map

The Developer Edition allows you to map up to 5 Dynamic Content slots to content slots in Salesforce Commerce Cloud. You can map Dynamic Content slots to two types of SFCC slots: global slots and category slots. For a global slot you need to provide the id and for a category slot you also need to provide the category id.

From the sites menu in Business Manager choose the site you want to use with the integration. Open the content slots section: Merchant Tools -> Online Marketing -> Content Slots. Locate the id of each content slot that you want Dynamic Content to deliver content to. In the example shown below, the "home-main-m" slot is highlighted. This is a global slot on the Storefront home page.

Step 3: Configure the integration in Dynamic Content

Log in to Dynamic Content using the username and password sent in your welcome email.

From the "Development" tab at the top of the screen choose "Integrations". The integrations home page will be displayed. Click "Salesforce Commerce Cloud integrations". The integrations screen will open showing the integration already set up for your account.

Click to open the integration. In the Salesforce Commerce Cloud auth section click the edit button next to the Client ID and Client secret fields end enter the ID and secret that you want to use for your integration.

danger

• Do not modify the Amplience Dynamic Content auth section. This is already set up for you.

In the SFCC Api field change the SFCC API path to point to your SFCC account. You will not be able to use the account included by default.

Finally scroll down to the "Content Slots" section and edit the Site id to match the site you want to send content to.

Click Save and your integration is ready to go.

Step 4: Set up the app preview

You can launch a preview of your SFCC Storefront directly from Dynamic Content.

To set up the preview, in Dynamic Content, choose "Preview" from the settings menu. A preview app is already set up for you using a default value with the following format:

https://your-subdomain.demandware.net/s/RefArch/home?__siteDate={{context.timestamp | date:'yyyyMMddHHmm'}}

Replace the value included foryour-subdomain with the subdomain of your SFCC sandbox and change RefArch to the SFCC site you want to use. Specify "/home" to launch the home page or change it to the page you want to be shown in the SFCC Storefront.

Once you've configured the preview to point to your own site, click "Save".

Step 5: Map your slots

In order to deliver content to your SFCC content slots, you need to create a slot in Dynamic Content for each content slot that you want to map to in SFCC. In the Developer Edition you can map up to 5 SFCC content slots.

You create slots from the Dynamic Content production view. Click the "Production" tab in the Dynamic Content app and select the "Slots" repository on the left hand side of the window.

The slots repository will initially be empty. Click the "Create slots" button to create a new slot.

Choose the "SFCC Slot Accelerator". This a slot type already configured for you.

In the slot form enter the slot id of the content slot you want to map to. In the example shown below, the Dynamic Content slot is being mapped to the SFCC content slot with the id "home-main-m". If the slot you want to map to is a category slot, then enter the category id as well.

You do not need to enter the site_id, this is only required if you have created multiple integrations, each using a different site.

Once you've finished click "Save" and give the slot a name that helps you identify it, such as "Home page main content slot".

Create a slot in Dynamic Content for every content slot you want to map to in SFCC, up to a maximum of 5.

Step 6: Create some content

Now that you've configured your slots, the next step is to create some content. Select the "Content" repository on the left hand side of the window in the Dynamic Content app. Click the "Create content" button. Your account has already been configured with a set of content types, including banners, sliders and text.

Choose a content type to use to create content. In the image below the "Banner accelerator" is selected.

Fill in the content form. Many content types allow you to add other content items by clicking the "+" icon. The banner content type can contain images created using the image accelerator, for example.

Your Dynamic Content media library, stored in Content Hub, has already been populated with some free use images that you can add to your content.

You can create as many content items as you like and any of this content can be added to your slots.

Walkthrough of creating a content item

You can click on the first image below to start viewing the slideshow.

Choose a content type to use to create content. In this example we'll walk you through creating a banner.

Fill in the content form. The banner content type includes a headline and subheading as well as an image. Click "+" in the banner image field. To add an image to the banner you'll use the image accelerator. Click "Create and add new" to create a new image using the image accelerator.

The image accelerator content form opens. Click the "+" button in the image field.

The media browser is shown. This displays all the images that have been included in your Content Hub account. Choose an image to add.

Click "Save" and give the image a name. In this example it's saved as "Summer dress image".

When the image accelerator content item is saved you'll be taken back to the banner form. Fill in the rest of the fields you want to use and click "Save". Give the banner a name and click "OK".

When you've saved the banner click the eye icon in the top right of the window to show a visualization, a preview of the content.

Clicking the back button will return you to the Content Library in the production view. The content items you just created are shown.

Publish your images

To make sure you can preview unpublished content in SFCC Storefront, any images that you've added to your content must first be published in Content Hub.

Log in to your Content Hub account using the credentials provided. To publish an image, click the up arrow icon on its thumbnail card.

When an image is published a green cloud icon with a tick is shown on its card. You can select and publish multiple items at once, so you might choose to publish all the images that we've added to your account. Once you've published an image, you don't need to publish it again.

Step 7: Create and schedule an edition

Dynamic Content slots are contained within editions, collections of content that have a start and end date. In order to deliver content from Dynamic Content to SFCC, you'll need to create an edition, add your slots to it and add content to these slots. You create an edition from the Planning section of the Dynamic Content app.

When an edition is scheduled, the integration will create a campaign in SFCC and deliver content from each slot in the edition to the corresponding content slot in SFCC.

Walkthrough of creating an edition and adding slots to it

You can click on the first image below to start viewing the slideshow.

Editions are contained within events, the top level structure used for planning your content. In the planning view in the Dynamic Content app, click the "Create Event" button.

Give the event a name and choose a start and end date. Any editions added to this event must be within the start and end date you choose.

A new empty event is created. Click "Create edition".

Give your edition a name and a start and end date. You can add multiple editions to an event, each with their own start and end dates and times. The start date and time specifies when the content in slots added to this edition will go live.

The "Content flagged to expire when edition ends" checkbox specifies whether the content in this edition is set to expire at the edition's end date. When an edition is scheduled in Dynamic Content, the integration will create a corresponding campaign in SFCC. If the edition was not set up to expire, then the campaign is setup with no end date and is treated as "evergreen" or fallback content. You can find out more about evergreen content in the SFCC FAQs.

A new empty edition is created. Click "Add slots" to choose and add your slots.

Choose a slot to add to the edition and drag it to the edition window. In the example shown below, the slot which will contain content for home page main content slot is added to the edition. You can add multiple slots to an edition.

Add content to a slot by selecting it and clicking the "+" icon in the content section.

The content browser is displayed, showing the content items that you created earlier. When you select a content item, its visualization is displayed. Click the "+" icon to add the selected content item to the slot.

When you've finished adding content to the slots in your edition, click the "Schedule" button to schedule the edition. When an edition is scheduled, the Dynamic Content SFCC integration will deliver content in the slots in this edition to your corresponding content slots in SFCC. You'll then be able to preview this content.

View the slot configurations created by the integration

When your edition has been scheduled, you can view the slot configurations and HTML content created by the integration in SFCC Business Manager. For details of how to do this, see below.

Open the "Content Slots" section in SFCC Business Manager (Merchant tools -> Online Marketing -> Content Slots) to view the content slots and find which ones were mapped from the slots included in the edition. The image below shows the "home-main-m" content slot used in the example.

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: the example edition was named "Summer collection promo". Open the slot configuration that includes your edition name to see its contents. The HTML generated from the contents of the Dynamic Content slot should have been added to the slot configuration.

If you unschedule an edition, its content will no longer be available in SFCC.

Step 8: Open the preview in SFCC Storefront

You can now preview your content in SFCC Storefront. You set up the preview app in a previous step, so you can launch a preview directly from Dynamic Content.

Right click in the calendar at the date which you want to show the preview and click "Preview". Choose a date when your content is scheduled to go live and click the "Preview" button.

Your Storefront will open showing a preview of your content.

Find out more

The Dynamic Content SFCC integration

Your integration has been setup as a slot based integration. There's a lot more information about the Dynamic Content Salesforce Commerce Cloud integration in the SFCC slots integration section. You can also check out the tutorial videos for examples of slot based integrations, including a more detailed explanation of the integration architecture.

You can find the answers to common questions about the integration on the SFCC FAQs page.

Content asset integrations are explained on the Content asset integrations page. In the Developer Edition you can't create a new integration, but you can editing the existing one to support content assets.

What's included

The Dynamic Content accelerators are a set of commonly used content types, designed to get you started quickly and for you to modify to meet your needs. In the Developer Edition we've already set up the accelerators for you, including all the content type schemas, rendering code and templates. You can find out more about the accelerators on the Github page.

Go to the Schema editor section for more details about viewing, editing and creating content type schemas and registering content type schemas as content types.

You've been set up with a slot based integration and this uses a handlebars wrapper template (named sfcc-contentWrapper) that is used by the Content Rendering Service to convert slot content into HTML that is then stored in slot configurations in SFCC. You can find a handlebars template for each of the accelerators content types in your Content Hub account. For more explanation of how the handlebars wrapper template works in a slot based integration see the slot mapping page.

Planning and production

The producing content section provides more information about creating, viewing and editing content while scheduling content covers working with events, editions and slots.

Content Hub

To find out more about working with assets in Content Hub and how to upload your own images see managing assets.

Next steps

For an example of how to modify one of the accelerators, including updating the content type schema and making changes to its handlebars template see the modifying the accelerators example.

Troubleshooting and getting help

This section contains some FAQs to help answer common questions about the Developer Edition.

I can't find a slot configuration in SFCC containing my HTML content. What should I check?

Ensure your edition is scheduled. The integration will only create the HTML from the contents of slots in an edition and create a slot configuration containing it when the edition is scheduled.

Can I map multiple SFCC content slots?

Yes, you can create up to five slots in Dynamic Content and map each one to a different content slot in SFCC.

Can I create multiple editions?

Yes you can create multiple editions with different start and end dates in the same or different event. You can also create multiple events. You can also add multiple slots to an edition.

I have scheduled my content but when I preview the SFCC Storefront after the edition’s start date my content doesn’t show up?

Make sure the preview is set up to point to your sandbox (including your site) and the page containing your content slot. Ensure images included in your content are published.

How can I remove content from SFCC?

If you unschedule an edition, its content will be removed from SFCC. Editions can be unscheduled at any time before their start date.

How do I view error logs?

The integration makes use of the Webhooks Service to notify SFCC when a user schedules or unschedules an edition in Dynamic Content. You can view the results of each action in the webhook logs, available by choosing "Webhooks" from the "Development" menu in Dynamic Content.

In the Developer Edition there's only one integration, with one associated webhook.

You can view the webhook logs by clicking on the webhook title or choosing "View" from its contextual menu.

Scroll down to the "Recent deliveries" section, as shown in the image below.

The status code will be one of the following:

• 200 OK. The delivery was successful and it was successfully processed by SFCC.
• 202 Accepted. The delivery was successful but SFCC returned an error with a status code in the range 4xx. These deliveries will not be retried.
• 500 Internal Server Error. The delivery was successful but SFCC returned an error with a status code in the range 5xx. These deliveries will be retried according to our webhook retry policy.

If a status of 202 is returned, click the "View details" button to view the error message from the SFCC integration.

I get a limits alert, what does it mean?

The Developer Edition does contain certain limitations. See the Developer Edition limits for more details

How do I upgrade to the enterprise edition?

Go to the upgrade page and request a call from one of our team.

The SFCC FAQs also provide solutions to common issues.

If you need help help with something that isn't covered in the documentation, ask a question in the Amplience Dynamic Content section of Stack Overflow.