SAP CCv2:: SAP Commerce Cloud Integration with Emarsys - Integration manual – Emarsys

In case you are interested in adopting SAP Commerce Cloud Integration with Emarsys, please feel free to join our Early Adopter Care Program. Register here to participate.

Before looking into integration, make sure you are familiar with the prerequisites and requirements of this solution: SAP Commerce Cloud Integration with Emarsys - Getting started.

We strongly suggest activating Web Extend before performing product sync with SAP CCv2.

Setting up the Emarsys for SAP CCv2 plugin

Before integrating

Consider the following important points before beginning your integration process:

The product catalogue will become available on Predict a couple of hours after the proudct sync is performed. Please be patient.
Products cannot be deleted. Emarsys needs historical products too, the only way to make your product disappear is to set it to unavailable.
In case there is no stock information for a product on the parental level, each child product level is examined to determine available status.
Adding new products can take up to 5 hours due to processing on SAP CCv2 and Emarsys end.
Product descriptions, brands and so on should not include new line character as Predict does not accept them. Any such product is ignored in sync.
Set up events in Interactions in a way that each change in the order management flow corresponds to one single order lifecycle status. For instance, "created" is followed immediately by "processing".
In general, well-thought-out order flow management is especially crucial for transactional tactics and use cases - such as order confirmation and shipment update.
Filters (participation for once par day / week for post-purchase-up-sell) can be managed on the program level for marketing Tactics and automation in general.

User creation

Open the Emarsys Marketing Platform and the SAP CCv2 Backoffice on two separate tabs in your browser.

Important: the backoffice URL is needed in this setup step not the frontend one.
Emarsys: Go to Add-ons → SAP Commerce Cloud Integration.
- Check the provided credentials: there is an auto-generated username and a password.
  These credentials are not static, they are regenerated on each page load for security reasons.
SAP CCv2: Create an administrator user with the credentials provided by Emarsys.
- User → Employees → + (Use the plus sign under the search box.)
  - In the Create New Employee pop-up, paste the username copied over from Emarsys into the ID field and click Done.
  - A green notification comes up about ID creation. Click the ID link in the notification.
  - Copy over the password from Emarsys and, in the PASSWORD tab of the newly created ID, paste it twice into the Change Password fields. Click the yellow SAVE.
- In Groups in GENERAL - PROPERTIES in CCv2, remove employeegroup membership and assign the new user to admingroup.
Emarsys: Finish user creation.
- Enter the created user's URL copied from CCv2 to the URL field
  The service works over HTTPS only for security reasons.
- Delete /backoffice/ from the end of the URL.
- Click the Test and Connect button.

Data sync

Perform all of these tasks in Emarsys. In general, the direction of the data flow is from SAP CCv2 to Emarsys.

If you use your own solution for managing consent and maintain the consent in CCv2, make sure that you do not turn on the sync consents switch in the Contacts tab when setting up.

Customer sync

Turn on Enable contact sync to use your CCv2 Customer entities in Emarsys.
If you want to use the Emarsys integration for managing customer consent, tick the sync consents box and provide the following:
- Base site
- Consent Template
- Consent Template Version
Once you are done with the settings, click Save.

The customerID is by default a unique identifier to create, update or delete customers in Emarsys.
The unique identifier cannot be changed to any other field (e.g. email).

Real-time events sync

Make sure that the initial contact sync has already finished, so the system is not busy syncing.
Turn on the Enable real time event sync. Syncable events are:
- cart
- customer review
- order update
- customer registration (requires contact sync)
- opt-in status (requires consent sync)
Click Save.

You can only sync events of logged-in users.

If you decide not to perform contact sync, you can use only the following events:

All Order Update
Order Created
Order Completed
Order Canceled
Order Shipped
Cart
Customer review

By using these events without contact sync, make sure that:

Contacts are created in Emarsys first (only existing contacts can be treated).
Contacts are created with the SAP CCv2 User ID, which is used as the default identifier for the integration.

You can customize the order, customer review and cart events in SAP CCv2 by adding additional attributes. For more information, see SAP Commerce Cloud Integration with Emarsys - Real Time Events customization.

Product sync

Start the product sync process only after Web Extend is activated.

In case you already have product data locally on the Emarsys side, it is erased during the sync.

Product sync is performed via Flexible Product Catalog Onboarding. Once done, Predict and WebExtend can use the imported product data. A product CSV sample is also available in the this tab, which can be used as a structural example for product mapping in the Smart Insight setup. You can see the CSV sample pop-up below.

Turn on the Enable product sync.
Choose the product catalogue(s) to sync to Emarsys from CCv2. Select catalogues individually or use Select all.
Enter the domain of your product images. For example, https://my-cool-shop.com/.
Enter the product URL template.
An example:
https://my- cool-shop.com/products/{{ code }}
The bracketed code is a unique identifier of a specific product in your catalogue.
Specify the one currency which the price is in. We only support single currency at the moment.
Click Save.

Supported fields:

title
item
link
image
category
description
price
msrp
available
brand
zoom_image

Product stock availability

You need to link StockLevel to the Product to get the right product stock information. Each Product needs to have its StockLevel directly attached otherwise the availability information will not be up-to-date.

Below is a product item with the appropriate fields populated on its ADMINISTRATION tab.

For further important technical details on availability and other product properties, see Attribute inheritance for products.

Product sync transformations

This section describes the transformations that the SAP CCv2 product data goes through to become product data in Emarsys.

item

The product’s code, in case of parent products, is prefixed with g/.

group_id

The top level product’s code, inherited by all of its variants.

Example

In the example, both bbb-222 and ccc-333 inherit the group ID aaa-111:

{
  “code”: “aaa-111”,
  “variants": [
    {
      "code": "bbb-222",
      "variants": [
        {
          "code": "ccc-333"
			} 
       ]
      } 
     ]
}

title

The product’s name.

brand

The product’s manufacturerName.

description

The product’s summary.

The summary field in SAP CCv2 better corresponds to the description field in Emarsys and it supports the possible use cases.

price

To find the product’s default price, we filter the product’s europe1Prices based on the following criteria:

^–has no user assigned to it
^–has no ug (usergroup) assigned to it
^–has no pg (pricegroup) assigned to it
^–the assigned currency’s isocode matches the one selected on the plugin UI

The price attribute is fetched from this entry.

Example:

Assuming the currency configured on the UI is EUR, the price used by the plugin will be 555. In case the product has no europe1Prices, it inherits the price of its immediate parent.

{
  "code": "aaa-111",
  "europe1Prices": [
    {
      "user": { ... },
      "price": 111
    },
    {
      "ug": { ... },
      "price": 222
    },
    {
      "pg": { ... },
      "price": 333
    },
    {
      "currency": {
        "isocode": "USD"
      },
      "price": 444
    },
    {
      "currency": {
        "isocode": "EUR"
      },
      "price": 555
    }
  ]
}

In the following example, the variant aaa-111-variant-1 inherits the price 555 from its parent as it does not have any europe1Prices attached. Please note that if there are europe1Prices present on the product but none of them can be considered default, then the price will be empty.

{
  "code": "aaa-111",
  "europe1Prices": [
    {
      "user": { ... },
      "price": 111
    },
    {
      "ug": { ... },
      "price": 222
    },
    {
      "pg": { ... },
      "price": 333
    },
    {
      "currency": {
        "isocode": "USD"
      },
      "price": 444
    },
    {
      "currency": {
        "isocode": "EUR"
      },
      "price": 555
    }
  ],
  "variants": [
    {
      "code": "aaa-111-variant-1"
    }
  ]
}

image

image is the URL attribute of the product's thumbnail, prefixed with the configured image domain.

Example:

In case the user has configured https://my-cool-shop.com as image domain, we will have https://my-cool-webshop.com/media/images/some-product-thumbnail.jpg as image.

{
  "thumbnail": {
    "URL": "/media/images/some-product-thumbnail.jpg"
  }
}

zoom_image

zoom_image is the URL attribute of the product's picture, prefixed with the configured image domain.

In case the user has configured https://my-cool-shop.com as image domain, we will have https://my-cool-webshop.com/media/images/some-product-picture.jpg as image.

{
  "picture": {
    "URL": "/media/images/some-product-picture.jpg"
  }
}

available

To determine a product’s availability, we check the attached stockLevels.

The product is flagged as available if one of the following criteria is met:

there is at least one entry where the in StockStatus code is forceInStock
there is at least one entry where the in StockStatus code is not forceOutOfStock and the available (quantity) is greater than zero

Example:

aaa-111 is available despite the available amount being zero, because the forceInStock flag is applied.

{
  "code": "aaa-111",
  "stockLevels": [
    {
      "available": 0,
      "inStockStatus": {
        "code": "forceInStock"
      }
} ]
}

bbb-222 is NOT available despite the available amount being greater than zero, because the forceOutOfStock flag is applied.

{
  "code": "bbb-222",
  "stockLevels": [
    {
      "available": 5,
      "inStockStatus": {
        "code": "forceOutOfStock"
      }
} ]
}

ccc-333 is available because the available amount is greater than zero.

{
  "code": "ccc-333",
  "stockLevels": [
    {
      "available": 5
} ]
}

ddd-444 is NOT available because the available amount is zero.

{
  "code": "ddd-444",
  "stockLevels": [{
      "available": 0
} ]
}

link

The plugin replaces the {{ code }} placeholder in the configured product URL template with the product's code.

Example:

In case the user has configured the product URL template https://my-cool-shop.com/products/{{ code }}, we will have https://my-cool-shop.com/products/aaa-111 as link.

{
  code: "aaa-111"
}

CCv2 integration is an on-going effort.

Order and refund sync for Smart Insight and Strategic Dashboard have an ETA of 2022.
Sales Data Sync (Order, Refund, Cancelation) is scoped and planned with the ETA of 2022.

Walk-through video

You can watch a brief video of the complete set up process:

Need assistance with your Emarsys product? We'll get you the help you need!

SAP

Setting up the Emarsys for SAP CCv2 plugin

Before integrating

User creation

Data sync

Customer sync

Real-time events sync

Product sync

Product stock availability

item

group_id

title

brand

description

category

price

image

zoom_image

available

link

Walk-through video

Need assistance with your Emarsys product?
We'll get you the help you need!