Emarsys for Salesforce Commerce Cloud Integration Manual

Below is an overview of the functionality enabled by the Emarsys for Salesforce integration.

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:

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

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:

1. Download integrationframework.zip from the Salesforce Xchange.
2. Extract the contents to your local file system.
3. 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.
4. 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.

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

1. Download and extract the latest release of the Emarsys integration package to your local file system (e.g. the cartridge folder of your project).
2. Inside site_template folder, modify the SiteGenesis folder name and the SiteGenesis references inside the .xml files to match your site name.
3. Make a .zip file of the updated site_template folder. You will later need to import this into the Business Manager.
4. 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.

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.

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.

Your integration is now complete and you can proceed with the Frontend setup and Contact synchronization tasks.

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.

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.

Here you can also select the widget type to show on your storefront.

The following widgets are available:

• Personal
• Home
• Related
• Also Bought
• Cart
• Category

They can be displayed on the following pages:

• Thank You For Your Order page
• Product Detail page
• Home page
• Cart page
• Search page
• Category page

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.

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.
• Title – The product title.
• Link – The deep link to the product.
• Image – The URL of the product image.
• Category – The category path to the product separated by ‘  ‘, e.g. books  sci-fi  Snow Crash.
• Price – The price of the product (float value 1234.99).

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 Groups  Emarsys 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

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 Emarsys Merchant ID which can be found in the Account Details box on the Data Sources page.
• Predict: Enable tracking code – Enable or disable the Javascript tracking code for your site.
• Emarsys SFTP Host – The Emarsys SFTP server host for Predict.
• Emarsys SFTP Username – The Emarsys SFTP server username for Predict.
• Emarsys SFTP Password – The Emarsys SFTP Server password for Predict.
• 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 Objects  Custom Objects  predictConfig  General and checking the Mapped fields box. Here are all the fields that you selected above.

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:

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.

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

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

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:

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).

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

In the Custom Site Preferences, select EmarsysSmartInsight.

This will open the EmarsysSmartInsight Configuration.

Make the following settings:

• Enable SmartInsight – Enable or disable the Smart Insight order export.
• 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 Start – The setup timeframe start date for the Emarsys historical export job.
• 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.

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.

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

Here you configure the Emarsys Export Order 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 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:

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.

Emarsys Smart Insight attributes are configurable under the emarsysSmartInsightAvailableElements site preference (Merchant Tools > Site Preferences > Custom Site Preference Groups > Emarsys SmartInsight Configuration).

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.

Add the following lines of code at the bottom of the footer_UI.isml template:

<script type="text/javascript"><isinclude template="resources/emarsysresources"/></script> <script src="${URLUtils.staticURL('/js/emarsys.js')}" type="text/javascript"></script

Then add the .css file into the htmlhead.isml template:

link rel="stylesheet" href="${URLUtils.staticURL('/css/stylesheet.css')}" /

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 Tools  Content  Content 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:

lia title="Email Settings" href="$httpsUrl(EmarsysNewsletter-EmailSettings)$"Email Settings/a/li

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.

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.

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 Tools  Content  Content 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.

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

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).
• The Emarsys source ID (this will be saved in Salesforce in a custom preference attribute).
• 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.

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.

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:

In the Business Manager, go to Merchant Tools > Emarsys Integration > Database Load Configuration and click Add fields.

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

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.

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.

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.

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).

• Double opt-in

The double opt-in confirmation link should contain:

/on/demandware.store/Sites-SiteGenesis-Site/en_US/EmarsysNewsletter-AccountoutDoubleOptInThankYou?uid=$uid$

• Unsubscribe link

The unsubscribe link should contain:

/on/demandware.store/Sites-SiteGenesis-Site/default/EmarsysNewsletter-Unsubscribe?uid=$uid$&cid=$cid$&lid=$llid$&direct=n

Unsubscribe link for List-Unsubscribe header

If you are using the List-Unsubscribe feature, then this link should contain:

/on/demandware.store/Sites-SiteGenesis-Site/default/EmarsysNewsletter-Unsubscribe?uid=$uid$&cid=$cid$&lid=$llid$&direct=y

As well as the personalization options available in the Emarsys email editor, you can also use placeholders to add transactional content from Salesforce about the order and the customer.

This should be added to the email content as %%placeholder_name%%.

Click here for a full list of placeholders.

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.

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.

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).

To configure your order confirmation email, now go to Merchant Tools  Emarsys Integration  Shipping 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, 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.

The following placeholders are available for order confirmation emails.

Global placeholders

Product placeholders

The following placeholders are available for shipping confirmation emails.

Global placeholders

Product placeholders

• 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.

• 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.

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.

Example of generated mapped fields:

{"field":"product.ID","placeholder":"item"},{"field":"product.availability","placeholder":"available"},{"field":"product.name","placeholder":"title"},{"field":"product.url","placeholder":"link"},{"field":"product.image","placeholder":"image"},{"field":"product.categories","placeholder":"category"},{"field":"product.price","placeholder":"price"}]

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.

Example of generated mapped fields:

{"field":"order.orderNo","placeholder":"order"},{"field":"product.ID","placeholder":"item"},{"field":"product.quantity","placeholder":"quantity"},{"field":"order.customerEmail","placeholder":"c_email"},{"field":"order.totalGrossPrice","placeholder":"c_sales_amount"},{"field":"order.creationDate","placeholder":"date"}

The table below contains the list of Site Preferences for Emarsys Predict and Smart Insight.

• int_emarsys

Pipelines

• DBLoad.xml
• Emarsys.xml
• EmarsysEmails.xml
• EmarsysNewsletter.xml
• Predict.xml
• EmarsysExports.xml

Forms

• default/emarsyssignup.xml
• default/newsletter_unsubscribe.xml

Scripts

• emails/OrderConfirmationEmail.ds
• emails/SendShippingData.ds
• predict/ExportCatalogJob.ds
• smartinsight/ExportOrders.ds
• init/emarsysServiceInit.ds
• subscription/DoubleOptInSubscribe.ds
• subscription/GetAccountStatus.ds
• subscription/GetCustomerData.ds
• subscription/GetSourceID.ds
• subscription/MapFieldsSignup.ds
• subscription/SendDataForDoubleOptIn.ds
• subscription/SubmitContactData.ds
• subscription/SubscriptionTypeData.ds
• subscription/TriggerExternalEvent.ds
• unsubscribe/AccountUnsubscribe.ds
• unsubscribe/NewsletterUnsubscribe.ds
• util/DBLoad/CreateAutoImportProfile.ds
• util/DBLoad/CreateSingleChoiceValueMapping.ds
• util/DBLoad/ExportProfilesAsCSV.ds
• util/DBLoad/UploadProfilesCSVToWebDAV.ds
• util/EmarsysHelper.ds
• util/EmarsysResource.ds
• GetExternalEventsJob.ds
• GetProfileFieldsJob.ds

SCSS

• scss/_mixins.scss
• scss/_newsletter.scss
• scss/stylesheet.scss

Static

• static/default/css/stylesheet.css
• static/default/js/emarsys.js

Templates

• default/resources/emarsysresources.isml
• default/components/predict/cartinfo.isml
• default/components/predict/predictscript.isml
• default/components/predict/predictscriptqv.isml
• default/components/predict/traking.isml
• default/subscription/double_optin_thank_you_page.isml
• default/email/dbload_notification.isml
• default/subscription/emarsys_alreadyregistered.isml
• default/subscription/emarsys_disabled.isml
• default/subscription/emarsys_datasubmitted.isml
• default/subscription/emarsys_emailsettings.isml
• default/subscription/emarsys_error.isml
• default/subscription/emarsys_thankyou.isml
• default/subscription/emarsyssignup.isml
• default/unsubscribe/account_unsubscribe.isml
• default/unsubscribe/landing_unsubscribe.isml
• default/successjson.isml

Resources

• resources/emarsys.properties
• resources/forms.properties
• resources/locale.properties
• resources/newsletter_unsubscribe.properties
• resources/dbload_notification.properties

• bm_emarsys

Pipelines

• EmarsysConfig.xml

Forms

• default/dbload_config.xml
• default/emails_orderconfirmation.xml
• default/emails_shippingconfirmation.xml
• default/subscriptions_config_account.xml
• default/subscriptions_config_checkout.xml
• default/subscriptions_config_footer.xml
• default/predict_config.xml
• default/smartinsight_config.xml

Scripts

• extensions/GetShippingConfigData.ds
• extensions/InitialDBLoadConfig.ds
• extensions/NewsletterSubscription.ds
• extensions/OrderConfirmationConfig.ds
• extensions/SaveNewletterConfig.ds
• extensions/SaveShippingDataConfig.ds
• estensions/PredictConfig.ds
• extensions/smartinsight/GetSmartInsightAvailableElements.ds
• extensions/smartinsight/GetSmartInsightConfig.ds
• extensions/smartinsight/SaveSmartInsightConfig.ds
• util/Resource.ds
• GetAvailableElements.ds
• GetExternaEvents.ds
• Utils.ds

Static

• default/css/main.css
• default/js/main.js

Templates

• default/resources/emarsys_resources.isml
• default/extensions/smartinsight/smartinsight_config.isml
• default/dbload_configuration.isml
• default/emails_orderconfirmation.isml
• default/emails_shippingconfirmation.isml
• default/newsletter_configuration.isml
• default/page_wrapper.isml

Resources

• resources/dbload_configuration.properties
• resources/emails_configuration.properties
• resources/emails_orderconfirmation.properties
• resources/forms.properties
• resources/newsletter_configuration.properties
• resources/emarsyspredict.properties
• resources/smartinsight_config.properties

Extension file

• bm_extensions.xml