in Emarsys42

Emarsys for Salesforce Commerce Cloud Integration Manual

Updated: 2019年01月09日 09:01

The Emarsys for Salesforce integration allows you to use Emarsys functionality without leaving your Salesforce Commerce Cloud site. You can maximize customer engagement and conversion rates by providing a highly customized customer experience, including product recommendations.

By implementing the Emarsys solutions on your Salesforce platform, you can collect data from customer interaction with your web shop, gain insights into their behavior and reach them through email campaigns and tailored recommendations.

This integration is compatible for Salesforce Commerce Cloud 16.1 and higher. If you are interested in using this integration, please contact Emarsys Support.

Please note that the Salesforce Commerce Cloud was previously known as Demandware, and this name may still appear in some of the screenshots or user interface descriptions in the integration guide. If you find that any of the content is confusing or misleading, please let us know and we will correct it.

Define the mapping between Salesforce Commerce Cloud and Emarsys contact data fields and import your existing customers to Emarsys. Then use this mapping to create the auto-import profile (calling an Emarsys endpoint) and to create the .csv files that will contain the customer information. These files are uploaded regularly to the Emarsys WebDAV so that the Emarsys platform can process them keep your contacts synchronized between the two platforms.

Privacy

All customer, order and product information is transferred from Salesforce to Emarsys over a secure SFTP server connection. The integration does not process any customer credit card data.

Newsletter subscriptions

Allow end users to subscribe to newsletters from the website storefront using the subscription methods:

Global footer newsletter subscription.

Newsletter subscription during the checkout process.

Newsletter subscription from My account section for registered users.

Allow registered end users to unsubscribe from newsletters.

As stated above, you have the option to set the desired opt-in strategy for each one of the three storefront subscription methods. The available values for the opt-in strategy are:

Single opt-in – The customer record’s Emarsys opt-in field is immediately set to TRUE.

Double opt-in – The customer needs to click a link in a confirmation email in order to get the Emarsys opt-in field set to TRUE.

External events

An external event is a numeric ID, which can be triggered for a customer using the Emarsys API. External events are defined inside the Emarsys platform and can be used as triggers for emails.

Functionality currently not supported

Multiple currencies

The current version of the cartridge does not support multiple currencies or localization.

Using Predict with Salesforce

The Emarsys JavaScript tracking code has been included in the Salesforce integration so that this is automatically installed in your webshop pages. This generates product recommendations and maps contacts’ personal interests based on browsing information collected from websites (product views, searches, conversions). This information is collected by a set of JavaScript snippets embedded into website page templates.

The following JavaScript commands are pushed to Emarsys Predict:

Cart – This is placed on the page where the cart is shown, and sends Emarsys a list of the items in the visitor’s shopping cart.

Category – This is placed on pages which list products in a category, and sends Emarsys the category currently being browsed by the visitor.

Purchase – This is placed on the order confirmation page, and sends Emarsys a list of the items purchased by the customer.

SetCustomerId – This is placed on every page, as soon as the customer ID is known.

SetEmail – This is placed on every page as soon as the email address is known.

View – This is placed on every product detail page, and sends Emarsys the unique ID of the product being browsed.

SearchTerm – This is placed on the search results page, and sends Emarsys the search terms entered by visitor.

While browsing the site the user should be able to see the recommendations on the following pages:

Product detail page

Home page

Cart page

Search results page

Category page

Order confirmation page

Example

Here you can see how Predict displays personal recommendations on a product page:

Use case and examples

Below are some example use cases for the Emarsys Salesforce integration.

Global footer newsletter subscription

If the customer enters their email address and clicks the button, one of the following scenarios will be followed based on the opt-in strategy you set for this subscription method:

Single Opt-in strategy – The customer is taken directly to the Thank You page.

Double-Opt-in strategy – The will be directed to a Data Submitted page.

If the end user clicks the Submit button without entering the email address, they will be redirected to the sign-up page.

Newsletter subscription during the checkout process

Using this method, the customer can subscribe for newsletters during the checkout process, directly from the billing page.

The email field is a required field on the billing page in standard SiteGenesis functionality. If the customer enters their email address and selects the Please add me to the Salesforce email list checkbox, the contact record will be created by Emarsys and the opt-in field will be set directly to TRUE (Single Opt-in strategy) or after the customer clicks a link in a confirmation email (Double Opt-in strategy).

If the user doesn’t opt-in, all customer data will still be transferred into the Emarsys database, but the email sign up status will be set to inactive.

Newsletter subscription from My account section

There is also the option for a registered customer to subscribe to newsletters from the My account section in the Salesforce storefront. Just like the previous two subscription methods, the My Account subscription process will consider the configuration for the Opt-in strategy (Single Opt-in or Double Opt-in). Also, the registered user has the option of unsubscribing from newsletters by clicking a button inside their account.

Transactional emails

There are two types of transactional emails available with this integration:

Order confirmation email.

Shipping Confirmation email.

Order confirmation emails

As soon as a customer finishes a transaction the order data is transmitted to Emarsys, and the corresponding external event is triggered so that the confirmation email is sent. When triggering the external event, transactional information is transferred with the API call. The transactional information sent to Emarsys is based on the configuration made by the merchant for order emails.

Shipping confirmation email

A shipping confirmation email is sent at the point of dispatch. The approach is similar to the one used for order confirmation emails.

Getting started

This guide describes the steps needed in order to configure the Emarsys cartridge for a Salesforce Commerce Cloud website. It presupposes some degree of familiarity with the Salesforce platform.

Prerequisites

Please note that our extension is designed to work with the default installation of your web shop only. If your installation has been modified or customized, we can not guarantee that the changes made will not clash with any of the extension's functionality.

If your web shop installation has been modified from the default and you require our assistance with the extension, we would need you to provide the following:

A replicated system where the issue is reproducible.

Full access to the admin interface of your web shop.

Full access to the hosting server, with all the adequate rights (e.g. SSH access).

This will enable us to identify any issues quickly, and assist you with the proper resolution.

Before you can install Emarsys for Salesforce you need an Emarsys API account. Please contact Emarsys Support if you do not already have one.

This integration also requires the Salesforce Integration Framework cartridge to be present on the Salesforce instance. If you don’t have it already installed, proceed as follows:

Download integrationframework.zip from the Salesforce Xchange.

Extract the contents to your local file system.

Follow the steps from the documentation file Integration Framework-User and Developer Guide.docx which you can find inside the extracted files, and install it.

Be sure to assign bc_integrationframework to all the sites that you want to integrate with Emarsys.

You should also make sure that you have created any additional database fields in Emarsys that you might need for your Salesforce transactional emails, as well as the Emarsys external events to trigger them.

Installing the Emarsys cartridge

To install the Emarsys integration for the first time on your instance, you will need to prepare and install the cartridges. Proceed as follows:

Inside site_template folder, modify the SiteGenesis folder name and the SiteGenesis references inside the .xml files to match your site name.

Make a .zip file of the updated site_template folder. You will later need to import this into the Business Manager.

Import the cartridge into your workspace and link it to the Salesforce Server Connection.

Now you are ready to assign the cartridges to the sites you want to integrate with Emarsys.

Configuring the integration

Once you have the cartridges prepared, follow the steps below for each site you want to integrate with Emarsys.

Adding the cartridges to the Business Manager

Log in to the Business Manager and go to Administration > Sites > Manage Sites. There, select the site you would like to integrate with Emarsys.

Open the Settings tab and add the cartridges (int_emarsys and bm_emarsys) to the Cartridges field. Make sure that int_emarsys cartridge appears before the storefront cartridge.

After you have applied your changes, return to the Manage Sites page and click the Business Manager link.

Add the int_emarsys and bm_emarsys cartridges to the cartridges path and click Apply.

Importing site_template.zip

In the Business Manager, go to AdministrationSite DevelopmentSite Import Export. Then in the Import, Upload Archive section upload the site_template.zip you created above. Once it is in the list of available files, select it and click Import.

The import may take a few minutes and you should remain on this page until you can see that it has successfully completed.

Configuring the custom site preferences

In the Business Manager, go to Merchant ToolsSite PreferencesCustom Site Preferences and select Emarsys.

This will open the Emarsys Preferences.

The Emarsys Country Codes and Gender Codes are the Emarsys IDs for the languages and genders supported by the web shop.

Make the following settings:

Emarsys Source Name – This is the name of a contact source that was previously created in Emarsys.

Emarsys Environment – This should be set to the Emarsys environment that you log in to. Enter the URL without the https:// part, , for example: suite16.emarsys.net.

API Username – This is your Emarsys API user name.

API Key – This is your Emarsys API key.

Click Apply to save your changes.

If you are using these products, you should now configure your Salesforce preferences for Smart Insight and Predict.

Enabling the Emarsys cartridge

After the cartridges have been installed, you will have to activate the Emarsys Business Manager modules that will allow you to configure the integration according to your requirements. Proceed as follows:

In the Business Manager, go to Administration > Organization > Roles & Permissions and select the Administrator role.

Now go to the Business Manager Modules tab, open the Context drop-down, select your site and click Apply.

Activate the checkboxes next to the Emarsys modules that you need and click Update.

Enabling the integration

When you have completed all of your configuration tasks, you can enable and disable the Emarsys integration via the Business Manager. Go to Merchant Tools > Site Preferences > Custom Preferences > Emarsys and activate or deactivate the Enable Emarsys Services checkbox.

If the integration is disabled and a customer tries to subscribe to a newsletter using the global footer or My Account subscription method, they will be redirected to a custom page showing a message that says subscriptions are not active.

However, even if the integration is disabled, as long as the cartridge is installed customers still have the option to unsubscribe from newsletters from their Salesforce Commerce Cloud account (this applies to registered users only), or by clicking the unsubscribe link in the emails received through the Emarsys platform.

Configuring Salesforce for Predict

If you are using Predict’s product recommendations for web or email, you can easily integrate your Salesforce Commerce Cloud shop and collect the data you need to make relevant product recommendations. You should do this right after you have finished configuring your basic custom preferences.

Enabling the Emarsys data collection scripts

If you are a Predict client, the Emarsys data collection scripts are automatically added to your web shop when you install the Emarsys cartridge.

For these scripts to start collecting data, they need to be enabled in the EmarsysPredict Configuration page. To do this, open the Business Manager and go to Merchant Tools > Site Preferences > Custom Site Preferences and open Emarsys Predict Configuration.

Checking the data collection

Once you have installed and enabled your data collection scripts and widgets, you can easily check that they are working by going to your storefront and visiting pages where the code has been installed (category page, search page, pdp, etc.). At the same time, open the Data Sources page in the Admin menu.

As you click around your storefront, in the Web Behavior box you should see Predict tracking your actions in real time.

Preparing your product data fields for export

In the Salesforce Predict Configuration page you can add (and remove) the Salesforce fields that you want to include in your daily export, and map them to Emarsys fields. These fields will be prepared in a .csv file that will be placed on the storage location that you define below. The export file structure is as follows:

Name: products_<YYYYMMDDHHiiss>_<shopinfo>.csv

Encoding: UTF-8

Columns separator: Comma ( , )

To select and map your fields, open the Business Manager and go to Merchant Tools > Emarsys Integration > Predict Configuration.

The following fields are mandatory for the .csv file:

Item – The unique product ID.

Available – Determines whether the is product available (and can therefore be recommended); values are TRUE or FALSE.

In addition to these you can add custom product fields. Click Add fields and select the field you want to add from the Available elements list. Define the column name (which must be the same as the Emarsys field name to which it is mapped) for that field, then repeat for all the additional fields you want. Remember that the column name for these fields must begin with c_.

Note: Only custom fields that you have defined in the emarsysPredictProductAttributes site preference are listed here (in the Custom Site Preference GroupsEmarsys Predict Configuration).

You can also define the export type:

Export only the main product, with no product version (this is the default setting)

Export each product version / each combination of product versions

Configuring the daily export

To configure Salesforce for Predict, proceed as follows:

In the Business Manager, go to Merchant Tools > Site Preferences > Custom Site Preferences and select EmarsysPredict.

This will open the EmarsysPredict Configuration.

Make the following settings:

Predict Merchant ID – This is your Predict merchant user ID and can be found in the Account Details box on the Data Sources page.

Emarsys Predict SFTP Path – The folder name for the Emarsys Predict SFTP Server where product export will be uploaded.

List of Product Variation attributes for Predict feed – A list of product variation attributes used for the Predict feed (to ensure that, for example, the correct size or color of shoe is recommended). All the product variation attributes should be added here (they must already exist in Salesforce or this will cause an error).

Predict: Product attributes for exporting – A list of product attributes for the export feed. These are matched to the fields in Emarsys and must conform to the syntax requirements of the Predict product catalog. See Custom fields for export below for more details.

When you have finished configuring your export file, you can check that the fields have been correctly selected and mapped by going to Custom ObjectsCustom ObjectspredictConfigGeneral and checking the Mapped fields box. Here are all the fields that you selected above.

Setting up the export job

Now you must set up the Salesforce job that will collect the product data, compile the .csv file and place it on the export SFTP server.

In the Business Manager, go to Administration > Operations > Workflow schedules, select the Emarsys Predict job and click Edit.

Here you configure the Emarsys Predict job:

Enabled – This enables or disables the job on your Salesforce site.

Name – The name of the job.

Description – Description of this job.

Runtime – You define the frequency of the job.

When you have defined the frequency of the job, click Run. Then go to the SFTP server and check that the folder you created in the EmarsysPredict Configuration page is there and contains be new export file with products.

The file name should be in the correct format: products_YYYYMMDD_HHiiss_shopinfo.csv

Open the new export file and check that the columns match the mappings for the fields you selected in the Predict Configuration page:

Running the Predict workflow schedule

The EmarsysPredict workflow schedule exports catalog data into a .csv file via the Integration Framework. Every field in the .csv file will be mapped to a corresponding field in Emarsys.

To run the workflow, log in to the Business Manager and go to Administration > Operations > Workflow schedules and check if the EmarsysPredict workflow is scheduled daily. Then run the workflow.

About the Predict product feed

Predict requires a .csv product data feed, which will be fetched from a remote location (HTTP / FTP / SFTP). Emarsys Predict attributes are configurable under the emarsysPredictProductAttributes site preference.

Some attributes are mandatory for the feed. Please note that in some cases the syntax of the value will be checked by Emarsys and must be valid in order for the feed to succeed.

product.ID

product.availability – Values can only be TRUEand FALSE.

product.name

product url – This require a valid URL.

product.images – This requires a valid image path and name.

product.categories – Multiple categories must be separated by a pipe |.

product.price – This must be a field of the type Float.

In addition to this, you can add any Salesforce product standard and custom attributes, for example:

product.onlineFlag

product.skinConcern

product.custom.color

product.custom.size

product.shortDescription

product.longDescription

product.pageTitle

product.taxClassID

product.brand

Configuring the storefront cartridge

In order for your Predict recommendations to work, a few updates need to be made on the storefront cartridge.

footer_UI

In the storefront cartridge, find the footer_UI template and include the following code at the bottom of the template:

<isinclude template="components/predict/traking" />

productdetail.isml

Now find the productdetail.isml template and include the following code inside pdpMain div before the closing tag:

iscommentInclude Emarsys predict on QV page/iscomment

isinclude template="components/predict/predictscriptqv"/

cart.isml

Now find the cart.isml template and before the isese tag, under the isif condition="${pdict.Basket == null || (empty(pdict.Basket.productLineItems) empty(pdict.Basket.giftCertificateLineItems))}" condition near line 68, include the following code:

iscommentPredict Recommendations Widget Goes Here/iscomment

div id="predict-recs"/div

Still in the cart.isml template, include the following code before the closing isif tag near line 874:

iscommentPredict Recommendations Widget Goes Here/iscomment

div id="predict-recs"/div

confirmation.isml

Now find confirmation.isml template and include the following code before the closing isdecorate tag near line 34:

iscommentPredict Recommendations Widget Goes Here/iscomment

div id="predict-recs"/div

htmlhead.isml

Now find the htmlhead.isml template and include the following code at the end of the template:

isinclude template="components/predict/predictscript" /

homepage.isml

Now find the homepage.isml template and include the following code before the closing isdecorate tag near line 29@

iscommentPredict Recommendations Widget Goes Here/iscomment

div id="predict-recs"/div

producttopcontent.isml

Now find the producttopcontent.isml template and include the following code before the closing isif tag near line 92:

iscommentPredict Recommendations Widget Goes Here/iscomment

div id="predict-recs"/div

catlanding.isml

Now find the catlanding.isml template and include the following code before the closing isdecorate tag near line 30:

iscommentPredict Recommendations Widget Goes Here/iscomment

div id="predict-recs"/div

productgrid.isml

Now find the productgrid.isml template and, before the ul id="search-result-items"... tag near line 9, include the following code:

iscommentPredict Recommendations Widget Goes Here/iscomment

div id="predict-recs"/div

Configuring Predict when using AJAX

If you use AJAX in your store, the following updates need to be made on the storefront cartridge in order for your Predict recommendations to work.

addToCart.js

Make this modification to enable the cart trigger when your visitor clicks the Add to cart button.

Find the addToCart.js script and add the following code to the addToCart function:

Configuring Salesforce for Smart Insight

If you are using the Smart Insight customer intelligence module, you can easily integrate your Salesforce shop and export your sales data to Emarsys to help build relevant customer lifecycle segments. You should do this right after you have finished configuring your basic custom preferences.

Preparing your database fields for export

In the Salesforce SmartInsight Configuration page you can add (and remove) the Salesforce fields that you want to include in your daily export, and map them to Emarsys fields. These fields will be prepared in a .csv file that will be placed on the storage location that you define below. The export file structure is as follows:

Name: sales_items_<YYYYMMDDHHiiss>_<shopinfo>.csv

Encoding: UTF-8

Columns separator: Comma ( , )

To select and map your fields, open the Business Manager and go to Merchant Tools > Emarsys Integration > SmartInsight Configuration.

The following fields are mandatory for the .csv file:

Order – The order number.

Date – The date of the order (YYYY-MM-DD).

Customer – The unique customer ID (this ID must be available in Emarsys as well).

Item – The product ID of the sold item (this ID must match the one in the products .csv as well).

Quantity – The quantity of the ordered item.

c_sales_amount – The price of the sold items (this value must be negative if an order was cancelled).For Smart Insight, a daily .csv feed with the orders from the last 24 hours must be delivered to a server where Emarsys can fetch it.

In addition to these you can add custom order attributes. Click Add fields and select the attribute you want to add from the Available elements list. Define the column name (which must be the same as the Emarsys field name to which it is mapped) for that attribute, then repeat for all the additional fields you want. Remember that the column name for these fields must begin with c_.

Note: Only custom attributes that you have defined in the emarsysSmartInsightAvailableElements site preference are listed here (see below for details).

Configuring the daily export

Now that you have prepared your database fields, you can configure the export. Proceed as follows:

SmartInsight destination folder – Set the destination folder for the order export feed on the Smart Insight SFTP server.

Enable SmartInsight TimeFrame – Enable or disable the Smart Insight Timeframe. If this box is unchecked, it means that the timeframe isn’t taken into consideration and the export will contain all orders completed in the last 24 hours.

TimeFrame End – The setup timeframe end date for the Emarsys historical export job.

SmartInsight Available Elements – A list of available attributes for the Smart Insight order export .csv. These are matched to the fields in Emarsys and must also conform to the syntax requirements of the Predict product catalog. See Custom attributes for export below for more details.

SFTP username – The Emarsys SFTP server username for Smart Insight.

SFTP host – The Emarsys SFTP hostname for Smart Insight.

SFTP password – The Emarsys SFTP password for Smart Insight.

Setting up the export job

Now you must set up the Salesforce job that will collect the order data, compile the .csv file and place it on the export SFTP server.

When you have defined the frequency of the job, click Run. Then go to the SFTP server and check that the folder you created in the SmartInsight Configuration page is there and contains be new export file with orders.

The file name should be in the correct format: sales_items_YYYYMMDD_HHiiss_shopinfo.csv

Open the new export file and check that the columns match the mappings for the attributes you selected in the SmartInsight Configuration page:

Running the Smart Insight Workflow Schedule

The EmarsysExportOrders workflow schedule exports order data into a .csv file via the Integration Framework. Every field in the .csv file will be mapped to a corresponding field in Emarsys.

To run the workflow, log in to the Business Manager and go to Administration > Operations > Workflow schedules and check if the EmarsysExportOrders workflow is scheduled daily. Then run the workflow.

In addition to the mandatory attributes, you can add any Salesforce product custom attributes such as custom.product.color. The column names for these additional columns must start with c_. For example, to add the attribute color to the sales items the column name could be: c_color.

The following kinds of custom attributes are possible:

Billing address – The available element should start with billingAddress, and it should contain real attributes. In this way, we get the required values from the billingAddress object.Examples:

billingAddress.address1

billingAddress.postalCode

billingAddress.countryCode.displayValue

Shipping address – The available element should start with shippingAddress, and it should contain real attributes. In this way, we get required values from the order.shipments[0].shippingAddress object.Examples:

shippingAddress.address1

shippingAddress.postalCode

shippingAddress.countryCode.displayValue

General order attributes – The available element should start with order, and it should contain real attributes. In this way we get needed values from the order object.Examples:

order.orderNo

order.creationDate

Delivery method – This is a separate case for the deliveryMethod.display element only. It reads the shipping method name and description from the order.shipments[0].shippingMethod object.

Payment method – This is a separate case for the paymentMethod.display element only. It reads the first payment method from the order object.

Order rebate – This is a separate case for the orderRebate element only.

Shipping costs – This is a separate case for the shippingCosts.display element only. Tt reads the shipping total price from the order.shipments[0] object.

customerNo – This is a separate case for the customer No.

Custom attributes – There are 3 types of custom attributes available for output: custom.order, custom.product and custom.lineItem. These represent the Order, Product and ProductLineItem/GiftCertificateLineItem object attributes respectively. Please see https://documentation.demandware.com/DOC2/index.jsp to see the full list of available attributes for these objects.

Specific custom attributes – The tracking number, shipment company, date of arrival and tracking link should have the following element definitions: custom.shipmentTrackingNumber, custom.shippingCompany, custom.arrivalDate, custom.trackingLink. The available element should begin with custom. It reads the custom attributes values from the order.shipments[0] object.

Frontend setup

In order for email subscriptions to work, a few updates need to be made on the storefront cartridge and inside the Business Manager. Your customers can subscribe on their account profile page, during the checkout process and in the global footer.

Account profile page subscription

Visitors to the webshop can subscribe and unsubscribe via their account profile page:

To enable subscription from the account profile page, an update to the account pipeline needs to be made. There is also a small change required in the account-nav-registered content asset. Proceed as follows:

In the Business Manager, go to Merchant ToolsContentContent Assets and search for the account-nav-registered content asset.

Lock the content asset in order to be able to edit it, then go to the body attribute and add the following line to the list in the My Account section:

In your storefront core cartridge, find the Account-CreateAccount pipeline. After the LoginCustomer pipelet and before the end node, add a call node to call the EmarsysNewsletter-AccountSubscription pipeline.

Then find the Account-EditProfile pipeline. Before the Account-Show jump node, add a call node to call the EmarsysNewsletter-AccountSubscription pipeline.

Checkout subscription

Visitors to the webshop can subscribe on the checkout page:

They can do this either as a registered visitor or as a guest. After adding their product to the cart, in the billing stage of the checkout process they should enter their email address and select both the Please add me to the Salesforce email list. Salesforce does not share or sell personal info. and the I have read the Privacy Policy and I agree. checkboxes. Once they have completed their purchase, they are subscribed and the personal data they have entered is sent to Emarsys.

To enable subscriptions from the checkout page, an update to the COBilling-Start pipeline from the core cartridge also needs to be made. Inside this pipeline, after the COBilling-SaveAddresscall node, add a call node to call the EmarsysNewsletter-CheckoutSubscription pipeline.

Global footer subscription

Visitors to the webshop can subscribe by entering their email address in the global footer. This can be done by typing an email address directly into the subscription box.

If a customer clicks the Subscribe button without entering any email address, they will be directed to a sign-up form where they can enter their information. Clicking Sign me up for email will subscribe them and send the data they entered to Emarsys.

To enable subscriptions from the global footer to work, an update is required in the body of the footer-social-email content asset.

In the Business Manager, go to Merchant ToolsContentContent Assets and search for the footer-social-email content asset.

Lock the content asset in order to be able to edit it, then go to the body attribute and update the ID of the form to emarsys-newsletter-subscription.

Salesforce landing pages

Depending on which opt-in strategy has been configured for the subscriptions methods and depending on the unsubscribe strategy (direct/indirect), your customers can be redirected to several landing pages, as follows:

Thank you page – Single Opt-in strategy

Thank you page – Double Opt-in strategy

Data submitted page – Double Opt-in strategy

Action page – Indirect unsubscribe

Thank you page – Unsubscribe

Synchronizing contact data

The instructions below will show you how to set up the workflow to synchronize contact data between Emarsys and the Salesforce Commerce Cloud.

Running the Setup workflow schedule

Once the cartridges are installed and the credentials have been configured in the Business Manager, a setup workflow needs to be run in order to fetch from Emarsys all the data that is necessary for the integration to work.

In the Business Manager, go to Administration > Operations > Workflow Schedules. Select the Emarsys-Setup workflow and click Run (queue and start).

This will fetch the following data from Emarsys:

All the database fields in the Emarsys account (these are stored in a custom object in Salesforce: EmarsysProfileFields).

All the external events in Emarsys (these are stored in a custom object in Salesforce: EmarsysExternalEvents).

All available values for the Emarsys single-choice fields (these are saved in Salesforce in a custom preference attribute in the Emarsys DB Init Configuration page: Emarsys Single Choice Value Mapping).

You can check that the setup workflow has completed successfully by going to Administration, Operations, Workflow Plan and checking that the status is OK.

Configuring the subscription workflow

To configure the newsletter subscription workflow, log in to the Business Manager and go to Merchant Tools > Emarsys Integration > Newsletter subscriptions. The settings for each of these can be accessed via their respective tabs.

You should configure the following settings on each tab for all three of the subscription methods.

Note: The parameters for all confirmation and unsubscribe links used in emails are provided here.

Opt-in strategy

This defines the overall strategy for the method. The options are:

Single opt-in – This sets the subscribing contact’s opt-in field to TRUE immediately after submitting the subscription. No confirmation is required, although you can select an external event to trigger a follow-up action (such as a Welcome email) once this opt-in has reached the Emarsys database.

Double opt-in (highly recommended) – This triggers a confirmation email that the contact must respond to before their opt-in field is set to TRUE. If you select this option, you must then define the Opt-in external event that triggers the confirmation email. Here you can also define a follow-up action (such as a Welcome email) once this opt-in has reached the Emarsys database.

Opt-in external event

Here you can select the external event which will trigger the follow-up email for the subscription. These external events are created in Emarsys and can be used to trigger Automation Center programs or API calls.

If you have selected Single opt-in as your Opt-in strategy, you can trigger a welcome email, for example.

If you have selected Double opt-in as your Opt-in strategy, this external event should trigger the confirmation email.

Double opt-in after confirmation external event

If you have selected Double opt-in as your Opt-in strategy, you can select another external event to follow up on the confirmation email, for example a welcome email (if you have Single opt-in as your Opt-in strategy, this should be set to No external event.

Database Load Configuration

You will also need to map Emarsys fields with their respective Salesforce attributes before you can make your first upload of Salesforce customers to Emarsys. Proceed as follows:

Select an Emarsys field from the drop-down on the left and map it to an attribute in the drop-down on the right.

EmarsysDBInitConfiguration

Once you have mapped your fields, you will need to configure the Initialize Emarsys Database workflow schedule. This is done in the Business Manager > Merchant Tools > Site Preferences > Custom Site Preferences > EmarsysDBInitConfiguration.

On the Emarsys DB Init Configuration page you must configure the export settings (including opt-in) and the batch size for exports.

Configuring the export settings

Make the following settings:

Export folder – This is the name of the folder on the Emarsys WebDAV where the .csv file will be uploaded.

WebDAV URL, WebDAV Password, WebDAV Username – These are the credentials of the Emarsys WebDAV and will be provided to you by Emarsys Support.

Set Opt-in Status – This determines the opt-in status of the contacts imported from Emarsys using the initial database load feature. There are three options:

0 – The opt-in field is left empty for all users; this is the default setting.

1 – The opt-in field is set to TRUE for all users.

2 – The opt-in field value is set according to a custom attribute (this should be used when customers already have an attribute used to determine if they have subscribed for newsletter). When this option is selected, the merchant will have to add the ID of that custom attribute to the Opt-In Status custom attribute ID field.

You can also see the value mapping for the Emarsys single choice fields as provided by the Setup Workflow, and enter the email addresses which will receive the notification of the successful import.

Click Apply to save your changes.

Setting the batch size threshold

Your customers will be exported to Suite in batches of configurable size. The default size of a batch is set to 10,000 customers, but you can change this value in the Emarsys DB Init Configuration page in the Profiles export threshold field (see image above).

Important notes:

Please keep in mind that setting a high value for the bulk size might affect the performance. Also, the bulk size should never be set to a value higher than 20,000 customers in order to avoid Salesforce quota violations.

The recommendation is to schedule the workflow to run during low traffic periods.

Set the recurrence according to the number of exported customers per iteration.

Initializing the Emarsys Database

You can now return to the Workflow Schedules page and run the Initialize Emarsys Database schedule to generate the first export of contacts from Salesforce to Emarsys.

Your customers will be exported in batches and once all of them have been uploaded to Emarsys, a notification email will be sent to the list of addresses which you defined in the E-mail address for forwarding notifications field (see above). Email addresses should be separated by commas.

When the workflow schedule is finished, you must manually disable it. The Export Status field is used to prevent an export of customers after the Initialize Emarsys Database schedule was run, so that even if the workflow itself is not disabled, the export will be skipped. The Export Status checkbox is automatically activated once all the customers from Salesforce were loaded into Emarsys, so you should return to this page after you receive the notification email and deactivate it.

Sending transactional emails

In the Salesforce Commerce Cloud you can define certain transactional emails, for example an Order confirmation email or a shipping confirmation email. These emails can be triggered in the Emarsys application by associating the event in question with an Emarsys external event. You can then associate that external even with an Emarsys email campaign to trigger the actual email.

Transactional Emails Setup

Before you can configure your transactional emails for order and shipping confirmation you first need to define which Salesforce elements (data fields) will be used for them.

In the Business Manager, go to Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys Transactional Emails Setup.

Open the Order Confirmation Extension screen and define the Salesforce elements that will be used for the order confirmation emails.

Then do the same for the Shipping Information Elements.

You are now ready to configure your transactional emails.

Subscription link parameters for emails

All confirmation and unsubscribe links in your Emarsys emails should contain the following parameters, to ensure that they are pointing to the Salesforce instance (since Salesforce logic is taking care of unsubscribing or subscribing the contact).

Order Confirmation integration

Before you can set up your order confirmation emails you need to integration them into your pipeline. Proceed as follows:

In the storefront core cartridge find the COPlaceOrder-Start pipeline. Before the Mail-SecureSend call node, add a call to call EmarsysEmails-OrderConfirmation pipeline.

Order Confirmation configuration

As soon as a customer completes a transaction the order data should be transmitted to Emarsys and a confirmation email sent to the customer. Salesforce will check in the Emarsys account if the contact record already exists, and will then update it or create a new record. At the same time, the external event will trigger a confirmation email containing the transactional data as defined by the Salesforce elements selected above.

To configure your order confirmation email, proceed as follows:

In the Business Manager, go to Merchant Tools > Emarsys Integration > Order Confirmation configuration and click Add fields.

Here you can see the fields that you previously selected. Defined a placeholder for each field and then select the Emarsys external event that will trigger the email. To remove a field from this transactional email, activate the Remove checkbox.

Click Apply to save your changes. As long as the selected external event has been linked to an active email campaign, an order confirmation email will now be triggered.

Shipping Confirmation configuration

As soon as a product has been shipped to a customer this information should also be transmitted to Emarsys and an email sent to that customer, ideally containing a shipment tracking link. As for the Order Confirmation, Salesforce will first check in Emarsys if the contact record exists and then update or create it. At the same time, the external event will trigger an email containing the shipping information as defined by the Salesforce elements selected above.

To set up the shipping confirmation emails, in the Business Manager go to Administration > Operations > Workflow Schedules. Select the Emarsys-SendShippingEmails workflow and click Run (queue and start).

Here you can see the fields that you previously selected. Defined a placeholder for each field and then select the Emarsys external event that will trigger the email. To remove a field from this transactional email, activate the Remove checkbox.

Click Apply to save your changes. As long as the selected external event has been linked to an active email campaign, a shipping confirmation email will now be triggered.

Note: Shipping confirmation emails will only be sent for orders that are placed while the Emarsys integration was enabled. No legacy orders will be considered for shipping confirmation emails.

Transactional email placeholders

This page describes the syntax in which Salesforce transactional email variables should be coded in the emails sent by Emarsys.

These variables can be used in any combination in their respective event emails. To use the variables simply type in the placeholder syntax as shown below (for example: %%product_name%%) into the header, body text or subject line of the email. We recommended that you select the variables you want and test them until you find the combination that best suits your needs.

The placeholder names shown are the ones given by default, but they can all be changed in Salesforce.

Order Confirmation

The following placeholders are available for order confirmation emails.

Global placeholders

Demandware variable

Emarsys placeholder

taxes

%%taxes%%

b_address_1

%%b_address_1%%

b_address_2

%%b_address_2%%

b_address_zip

%%b_address_zip%%

b_address_city

%%b_address_city%%

b_address_country

%%b_address_country%%

b_address_phone

%%b_address_phone%%

customer_email

%%customer_email%%

s_address_1

%%s_address_1%%

s_address_2

%%s_address_2%%

s_address_zip

%%s_address_zip%%

s_address_city

%%s_address_city%%

s_address_country

%%s_address_country%%

s_address_phone

%%s_address_phone%%

order_date

%%order_date%%

delivery_method

%%delivery_method%%

payment_method

%%payment_method%%

shipping_costs

%%shipping_costs%%

net_sum

%%net_sum%%

total_sum

%%total_sum%%

order_rebate

%%order_rebate%%

Product placeholders

Demandware variable

Emarsys placeholder

product_name

%%product_name%%

product_quantity

%%product_quantity%%

product_url

%%product_url%%

product_image

%%product_image%%

product_tax

%%product_tax%%

product_price_currency

%%product_price_currency%%

product_item_price

%%product_item_price%%

product_total_price

%%product_total_price%%

product_rebate

%%product_rebate%%

Shipping Confirmation

The following placeholders are available for shipping confirmation emails.

There are also several custom site preferences attributes used to define the Salesforce fields that appear in the Emarsys Business Manager extension – these custom attributes are used to define the values that will appear in the drop-downs from the configuration screens.

Custom objects

EmarsysExternalEvents – This is used to store the external events defined in the Emarsys platform. This custom object is automatically populated after the Emarsys-Setup workflow schedule is run.

EmarsysNewsletterSubscription – This is used to store the configuration for each newsletter subscription type (global footer subscription, checkout subscription, and My Account subscription). Instances of this custom object are created on the fly, when you configure the newsletter subscriptions using the Emarsys Business Manager extension.

EmarsysTransactionalEmailsConfig – This is used to store the configurations for Emarsys transactional emails. There will be two instances of this custom object, which will be created automatically when you save the configurations for order and shipping confirmation emails through the Business Manager extension.

EmarsysDBLoadConfig – This is used to store the mapping between Salesforce and Emarsys fields for the initial DB load. There will be only one instance of the custom object, which will be automatically created when you save the initial DB load mapping through the Business Manager extension.

EmarsysProfileFields – This is used to store the Emarsys profile fields. It’s automatically populated after the Emarsys-Setup workflow schedule has finished running.

Custom site preference attributes

emarsysOrderConfirmationElements – The JSON used to define the Salesforce available fields that can be added to the order confirmation emails.

emarsysShippingInformationElements – The JSON used to define the Salesforce available fields that can be added to the shipping confirmation emails.

emarsysDBLoadAttributes – The JSON used to define the Salesforce available fields that can be added to the .csv file that is generated for the initial DB load.

emarsysSingleChoiceValueMapping – The JSON used to store all Emarsys single choice fields and the available values for each field. This attribute is used when creating the Emarsys auto-import profile for the initial DB load, and is automatically populated after the Emarsys-Setup workflow schedule has finished running.

emarsysContactFieldsMap – The JSON used to define the mapping between several Salesforce fields and the corresponding IDs for these fields on the Emarsys side.

Predict custom object

Emarsys Predict uses the EmarsysPredictConfig custom object type to store the list of field mappings for the Predict configuration. This custom object is updated automatically when configs are set up in Predict Business Manager extension.

Smart Insight custom object

Smart Insight uses the EmarsysSmartInsightConfiguration custom object type to store the list of field mappings for the Smart Insight configuration. This custom object is updated automatically when configs are set up in Smart Insight Business Manager extension.

This sets up the timeframe start date for the Emarsys historical export job.

emarsysSmartInsightTimeframeEnd

Date

This sets up the timeframe end date for the Emarsys historical export job.

emarsysSFTPHost

String

The Emarsys SFTP hostname.

emarsysSFTPUsername

String

The Emarsys SFTP username.

emarsysSFTPPassword

Password

The Emarsys SFTP password.

Appendix: cartridge contents

The Emarsys integration consists of two Salesforce cartridges, one used to communicate with the Emarsys platform, and the other to extend the standard Business Manager functionality with a custom module; this module will allow you to customize the newsletter subscription behavior and configure the Salesforce fields that will be added to transactional emails.

Also, the Business Manager module extension will allow you to set the fields that will be added to the .csv file used for the initial database load feature. Please find listed below the cartridge components.