To install the Emarsys integration for the first time on your instance you need to follow the next steps:

1. Download and extract the Emarsys integration archive to your local file system. For example, the cartridge folder of your project.
2. Inside the site_template folder, modify the SiteGenesis folder name and SiteGenesis references inside the XML files to match your site name.
3. Import the cartridge into your workspace and link it to the B2C Commerce Server Connection.
4. Import site_template.zip into your instance (please see more details in the following sections of the document).
5. Assign the emarsys_sg_changes ,int_emarsys, int_emarsys_sg and bm_emarsys cartridges to sites that you want to integrate with Emarsys  make sure that int_emarsys and int_emarsys_sg cartridges are placed before the storefront cartridge (detailed below).
6. Assign the emarsys_sg_changes, int_emarsys, int_emarsys_sg and bm_emarsys cartridges to the Business Manager site (detailed below).

1. Login to Business Manager.

2. Go to Administration > Sites > Manage Sites.

3. Select the site that you would like to integrate with Emarsys.

4. Go to the Settings tab

5. Add the cartridges (emarsys_sg_changes, int_emarsys, int_emarsys_sg and bm_emarsys) into the Cartridges field. Make sure that the int_emarsys and int_emarsys_sg cartridges appear before the storefront cartridge.

6. Click the Apply button.

7. Navigate back to Manage sites (by using breadcrumbs or by clicking the Back to list button).

8. Click the Business Manager link.

9. Add the emarsys_sg_changes, int_emarsys, bm_emarsys and app_storefront_base cartridges to the Cartridges path.

10. Click the Apply button.

Inside the site_template folder, modify the SiteGenesis folder name and SiteGenesis references inside the XML files to match your site name. Afterwards, you’ll need to make a zip archive of the folder in order to be able to import it into Business Manager.

1. Login to Business Manager and navigate to Administration > Site Development > Site Import & Export.

2. From the Import > Upload archive section upload the zip archive you’ve just created: site_template.zip.

3. Upload the file.

4. Select the uploaded archive file and import it.

5. Once the archive has been uploaded, select it from the list of available files and hit the Import button in the bottom right corner.

6. Confirm that you want to import it, so that the import process can start.

7. Wait until the import job has successfully finished.

After the cartridge has been installed, you’ll have to activate the Emarsys Business Manager modules that will allow you to make the configuration for the integration. Please see the steps that you need to follow in order to activate the modules below.

1. Login to Business Manager.

2. Go to Administration > Organization > Roles & Permissions.

3. Select the Administrator role.

4. Switch to the Business Manager Modules tab.

5. Open the Context dropdown. Select your site from the context dropdown list.

6. Click the Apply button.

7. Enable the needed Emarsys modules with checkboxes.

8. Click the Update button.

1. Login to Business Manager.

2. Go to Merchant Tools > Site Preferences > Custom Site Preferences.

3. Select Emarsys.

4. Set the following attributes:

• Enable Emarsys Services - this is switch that turns the Emarsys functionality on or off.
• Emarsys Environment - this should be set to the Emarsys suite that you will connect to. Make sure to omit the https:// part (please check the screenshot below).
• Emarsys Source Name - this is the name of a source that was previously created in Emarsys. Please note that you can only create and query the Emarsys Source Name by using the Emarsys API. Please see the related API endpoints here: https://api.emarsys.net/api-demo/#tab-apisource
• Emarsys Country Codes - JSON used to map the country IDs on the B2C Commerce side with the IDs on the Emarsys side. If you need to add another country, you’ll have to manually update the JSON with the correct key-value pair, where the key is the DW country ID and the value is the Emarsys country ID. Please check this link for the complete list of Emarsys country IDs: https://help.emarsys.com/hc/en-us/articles/115004634749-Overview-Single-choice-fields-and-their-values
• Emarsys Gender Codes automatically populated after metadata import.

• Emarsys Contact Fields Map - JSON used to map account information and shipping address on the B2C Commerce side with the IDs on the Emarsys side. If you need to add another fields to map, you’ll have to manually update the JSON with correct key-value pair, where the key is ID on the Emarsys side and the value is the Profile/Address System Object attribute. Example of the JSON for this field is:

This configuration will map first saved by customer address or shipping or billing address if any is available during checkout.

• Emarsys Address Fields Map - JSON used to map the rest of saved for every customer addresses on the B2C Commerce side with the IDs on the Emarsys side. If you need to add another fields to map or map more addresses, you’ll have to manually update the JSON with correct key-value pair, where the key is ID on the Emarsys side and the value is the Address System Object attribute. Example of the JSON for this field is:

This configuration will map second and third saved by customer address if any. All fields like “1_1”, “2_1”, “2_1” must be configured on the Emarsys side at first.

5. Click the Apply button.

6. Click the Back button.

7. Open the EmarsysCatalog configurations.

8. Set the following attributes:

• Predict Merchant ID - represents the ID of the Predict merchant user. Should be taken from the Emarsys Dashboard.
• Predict: Enable tracking code - enables or disables the JS tracking code on your site.

• List of Product Variation attributes for predict feed - the list of product variation attributes used for the catalog job. All the product variation attributes should be put here. For example:
  • product.custom.color
  • product.custom.size
• Predict: Product attributes for exporting - the list of product attributes for export feed. Mandatory attributes:
  • Merchant will be able to add any B2C Commerce product standard and custom attributes, e.g. product.ID, product.availability, product.name, product.url, product.image, product.categories, product.price, product.onlineFlag, product.skinConcern, product.custom.color,  product.custom.size, product.shortDescription, product.longDescription, product.pageTitle, product.taxClassID, product.brand,
  • Some mandatory attributes with specific syntax: url, image, price, availability, categories.
  • Please see section Emarsys Predict Export Attributes Configuration for a detailed description.

9. Open the EmarsysSmartInsight configurations

10. Set the following attributes:

• SmartInsight Available Elements - The list of available attributes for SmartInsight order export CSV.
  • The following attributes are required in the CSV file:
    • order - order number
    • date - date of the order (YYYY-MM-DD)
    • customer - unique customer ID (this ID must be available in the Emarsys Platform as well)
    • item - ProductId of the sold item (this ID must be in the products CSV as well!)
    • quantity - quantity of the ordered item
    • c_sales_amount - Price of the sold items (this value must be negative if an order was cancelled!)

Please see section Emarsys SmartInsight Export Attributes Configuration for a detailed description.

11. Open the EmarsysLoyaltyWallet configurations.

12. Set the following attributes:

• Emarsys Loyalty Wallet Enabled - this is a switch that turns the Emarsys Loyalty Wallet functionality on or off.
• Emarsys appId
• emarsys customerId
• Emarsys Secret - server side secret from Loyalsys.
• Emarsys Region
• Loyalsys URL exaccess
• Example: https://exaccess.loyalsys.io/v1.0.1/ls_ea.min.js?x=
• Loyalsys URL ui-elements
• Example: https://ui-elements.loyalsys.io/v1.0.1/embed.min.js?x=

The Emarsys Catalog is being used to recommend products based on a self-learning algorithm. Recommended products can be rendered within shop pages and within emails. To get this working, Catalog requires a CSV product data feed which will be fetched from a remote location (HTTP / FTP / SFTP).

Emarsys Predict Attributes will be configurable under the emarsysPredictProductAttributes site preference.

The following attributes are mandatory for the feed:

• product.ID
• product.availability
• product.name
• product url
• product.images
• product.categories
• product.price

If you need to add another attribute, the following ones are available:

• Standard product attributes
• Product custom attributes

Emarsys SmartInsgiht attributes will be configurable under the emarsysSmartInsightAvailableElements site preference. The merchant will be able to add product custom attributes like custom.product.color.

The column name of these additional columns must start with “c_”. For example, adding the attribute color to the sales items the column name could be named as c_color.

The following attributes are mandatory in the feed:

• order order number
• date  date of the order (YYYY-MM-DD)
• customer  unique customer id (this ID must be available in Emarsys Suite as well)
• item  ProductId of the sold item (this Id must be in the products CSV as well!)
• quantity  quantity of the ordered item
• c_sales_amount  Price of the sold items (this value must be negative if an order was cancelled!)

The following kind of attributes are possible:

• Billing address: The available element should start with 'billingAddress' and it should contain real attributes. In this way, we get needed 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 needed values from the order.shipments[0].shippingAddress object. Examples: shippingAddress.address1, shippingAddress.postalCode, shippingAddress.countryCode.displayValue, etc.
• 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, etc.
• Delivery method: Separate case for  the'deliveryMethod.display' element only.

It reads shipping method name and description from the order.shipments[0].shippingMethod object

• Payment method: Separate case for 'paymentMethod.display' element only. It reads 1st payment method from the order object.
• Order rebate: Separate case for the 'orderRebate' element only.
• Shipping costs: Separate case for 'shippingCosts.display' element only, it reads shipping total price from the order.shipments[0] object.
• customerNo: Separate case for customer No.
• masterid, variantid: It includes those attributes to send the ID of master and variation products for the purchased product.
• Custom attributes: You have 3 types of custom attributes available for output: custom.order, custom.product and custom.lineItem. Each type represents Order, Product and ProductLineItem/GiftCertificateLineItem object attributes respectively, please visit https://documentation.b2c.commercecloud.salesforce.com/DOC2/index.jsp to see the full list of available attributes for these objects.

• Specific custom attributes: Tracking number, shipment company, date of arrival, tracking link should have the following element definition: custom.shipmentTrackingNumber, custom.shippingCompany, custom.arrivalDate, custom.trackingLink. The available element should be started with 'custom' it reads custom attributes values from the order.shipments[0] object.

The table below contains the list of Site Preferences for Emarsys Catalog and SmartInsight.

Services are used to interact with the Emarsys API.

• Navigate to Administration > Operations > Services.

• emarsys.api - the service that communicates with Emarsys events.

• exchange.emarsys.api  - used to load the directory to Emarsys.

Once the cartridges are installed and the credentials have been configured inside Business Manager, a job schedule needs to be run in order to get all the data that is necessary for the integration to work from the Emarsys Platform:

• Emarsys profile fields (profile fields are stored in a custom object on the Salesforce Commerce Cloud side: EmarsysProfileFields)
• External events configuration (whitelisted SFCC side events and their mapping with Emarsys side events: EmarsysExternalEvents)
• The source ID defined in Emarsys (will be saved on the Salesforce Commerce Cloud side in a custom preference attribute: Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys > Emarsys Source ID)
• All available values for Emarsys single choice fields (will be saved on the Salesforce Commerce Cloud side in a custom preference attribute: Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys DB Init Configuration > Emarsys Single Choice Value Mapping)

All this data will be automatically stored in the Salesforce Commerce Cloud when the job is successfully executed.

Before running the job, you should check some Business Manager configurations:

1. Login in to Business Manager.

2. Select your site in the left top corner of the page.

3. Navigate to Merchant Tools > Custom Objects > Custom Object Editor.

4. Select the object type EmarsysExternalEvent and click the Find button.

5. Click the StoredEvents link in the (ExternalEvents) column.

6. The fields Newsletter Subscription Source and Other Source should not be empty. These fields should contain lists of SFCC events, for which the appropriate Emarsys external events should be created.

After you checked the configuration you are all set to run the job

1. Login in to Business Manager.

2. Go to Administration > Operations > Job schedules.

3. Select the Emarsys-Setup job and run it.

This job includes 5 steps:

• GetSourceID - it reads contact source name from the emarsysSourceName site custom preference. Then it tries to get its ID from Emarsys. If there are no contact sources with this name, the job step creates it. The main purpose of the step is to store ID of the contact source in the emarsysSourceID site custom preference.
• GetAvailableProfileFields - it gets Emarsys system and custom fields descriptions and stores them in the EmarsysProfileFields custom object. The language of the fields is taken from the emarsysGetProfileFieldsLanguage site custom preference.
• CreateSingleChoiceValueMapping - it collects option descriptions for Emarsys fields of singlechoice type. These fields hold only the index of the selected option but not its value. The job step stores option descriptions for such fields in the emarsysSingleChoiceValueMapping site custom preference.
• CreateExternalEvents - it reads SFCC events names from the newsletterSubscriptionSource and otherSource fields of the EmarsysExternalEvents custom object. For every SFCC event, it creates an appropriate event on the Emarsys side. It stores initial mapping between SFCC events and Emarsys events. Mapping objects are written in the newsletterSubscriptionResult or otherResult field depending on the type of the event.
• GetAvailableEvents - it gets all Emarsys external event descriptions and stores them in the result field of the EmarsysExternalEvents custom object.

Steps Configuration Description

1. custom.EmarsysComponents.CreateExternalEvents

1.1 customObjectKey - it specifies the key of the EmarsysExternalEvents custom object. External event configurations are stored in this object. (default value: StoredEvents)

2. custom.EmarsysComponents.GetAvailableEvents

2.1 isDisabled - it provides a convenient way to deactivate this job step.

EmarsysExportOrders will export order data into a CSV file through a new Job Schedule. Every field in the CSV file will be mapped to a corresponding field defined in the Emarsys documentation.

File structure:

• Name: sales_items_<YYYYMMDDHHiiss>_<shopinfo>.csv
• Encoding: UTF-8
• Column separator: “,”

At least these columns are required in the CSV:

1. order - order number

2. date - date of the order (YYYY-MM-DD)

3. customer - unique customer ID (this ID must be available in Emarsys Suite as well)

4) item - ProductId of the sold item (this ID must be in the products CSV as well!)

5. quantity - quantity of the ordered item

• Login in to Business Manager.
• Go to Administration > Operations > Jobs Schedules.
• Open the Emarsys-ExportOrders job.
• Check if the job is scheduled daily.

Description Configure Steps

1. custom.EmarsysComponents.EmarsysExportOrders

1.1 destinationFolder - the target folder path to save the CSV file.

1.2 smartInsightCurrency - mnemonic currency code of the currency that is configured for the.Smart.Insight.

1.3 queryString - it adds a query addendum for searchOrders. It starts with AND.

1.4 enableCustomTimeFrame - it enables timeframe for exported orders.

1.5 timeframeStart - timeframe start date for the Emarsys historical export job.

1.6 timeframeEnd - timeframe end date for the Emarsys historical export job.

2. custom.CSComponents.FtpUpload

2.1 ServiceID - the service ID used in Job. Default value: exchange.emarsys.api.

2.2 FilePattern - the file pattern where used regular expression.

2.3 SourceFolder - the local folder with files, relative to IMPEX/.

2.4 TargetFolder - the remote folder on Server, relative to home directory.

2.5 ArchiveFolder - the local folder where to archive files, relative to IMPEX/.

2.6 NoFileFoundStatus - the exit code in case no files were found.

2.7 IsDisabled - it marks the step as disabled. This will skip the step and returns an OK status.

This job initialized to send profiles data directly to Emarsys.

Description Configure Steps

1. custom.DBLoad.ExportCustomerInfo

1.1 enableAPI  - It enables API call on Emarsys for exported customer data.

1.2 csvFileColumnsDelimiter - character used to separate columns in the CSV file.

1.3 optInStatus - 0 - All users empty; 1 - All users true; 2 - Depending on attribute.

1.4 customAttributeId - Opt-In Status custom attribute ID.

1.5 profilesExportThreshold - How many profiles should be exported at once?

1.6 queryString - It adds a query addendum for searchOrders. It starts with AND.

1.7 enableCustomTimeFrame - It enables timeframe for exported orders.

1.8 timeframeStart - Timeframe start date for the Emarsys historical export job.

1.9 timeframeEnd - Timeframe end date for the Emarsys historical export job

1.10 fromEmail  - The email address for forwarding notifications.

1.11 mailTo - The notification destination e-mail address.

1.12 mailSubject - The mail subject.

A new job schedule Emarsys-ExportCatalog will export catalog data into a CSV file. Every field in the CSV file will be mapped to a corresponding field defined in the Emarsys documentation.

File structure:

• Name: products_<nameSite>.csv
• Encoding: UTF-8
• Column separator: “,”

At least these columns are required in the CSV:

1. Item - Unique product ID

2. available - Is the product available (and can be recommended)?: true or false

3. title_multilang - Product title

4. link_multilang - Deep link to the product

5. image - URL of the product image

6. category_multilang - Category path to the product separated by “ > “, e.g. books > scifi > startrek

7. price_multilang - Product price (float value 1234.99)

8. group_id - Master product ID

• Login in to Business Manager.
• Go to Administration > Operations > Job schedules.
• Check if the Emarsys-ExportCatalog job is scheduled daily.
• Run the job.

Description Configure Steps

1. custom.EmarsysComponents.EmarsysExportCatalog

1.1 exportFolderName - Target folder path

1.2 exportFileName - Export file name

1.3 catalogConfigKey - Adds the unique key value for custom object

2. custom.CSComponents.FtpUpload

2.1 ServiceID  - The service ID used in Job. Default value: exchange.emarsys.api.

2.2 FilePattern - File pattern where used regular expression.

2.3 SourceFolder - Local folder with files, relative to IMPEX/.

2.4 TargetFolder - Remote folder on Server, relative to home directory.

2.5 ArchiveFolder - Local folder where to archive files, relative to IMPEX/.

2.6 NoFileFoundStatus - Exit code in case no files were found.

2.7 IsDisabled - Marks the step as disabled. This will skip the step and returns an OK status.

This job initialized email send about confirmation or cancellation order through campaigns in Emarsys

Description Configure Steps

1. custom.EmarsysComponents.OrderStatusСhangeNotification

1.1 isDisabled - Marks the step as disabled. This will skip the step and returns an OK status.

1.2 stepFunctional 0 - send shipping data for Emarsys; 1 - send cancelled orders for Emarsys.

For the global footer subscription to work, an update is required in the body of the footer-social-email content asset.

1. Navigate to Business Manager > Merchant Tools > Content > Content Assets.
2. Search for the footer-social-email content asset.
3. Lock the content asset in order to be able to edit it.

Go to the body attribute and update the ID of the form to: emarsys-newsletter-subscription.

1. In the storefront cartridge, find the footer_UI.isml template.

Path: app_storefront_core\cartridge\templates\default\components\footer\footer_UI.isml

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

Path: app_storefront_core\cartridge\templates\default\components\header\htmlhead.isml

Include the CSS file into the htmlhead.isml template:

1. Navigate to Business Manager > Merchant Tools > Content > Content Assets.
2. Search for the account-nav-registered content asset.
3. Lock the content asset in order to be able to edit it.
4. Go to the body attribute and add the following line to the list of the My Account section (please also check the screenshot below):

It doesn’t require any additional modifications to the core cartridge.

It doesn’t require any additional modifications to the core cartridge.

1. In the storefront cartridge, find the pt_productdetail.isml template.

Path: app_storefront_core\cartridge\templates\default\product\pt_productdetails.isml

Include the following code update after line 8:

2. In the storefront cartridge, find the pt_cart.isml template.

1. Path: app_storefront_core\cartridge\templates\default\checkout\cart\pt_cart.isml
2. Include the following code before the closing isif tag near line 891.

3. In the storefront cartridge, find the cart.isml template.

1. Path: app_storefront_core\cartridge\templates\default\checkout\cart\cart.isml
2. Include the following code before the iselse tag under <isif condition="${pdict.Basket == null || (empty(pdict.Basket.productLineItems) && empty(pdict.Basket.giftCertificateLineItems))}" condition near line 24 .

After line 890:

4. In the storefront cartridge, find the confirmation.isml template.

Path: app_storefront_core\cartridge\templates\default\checkout\confirmation\confirmation.isml

Include the following code before the closing isdecorate tag near line 34.

5. In the storefront cartridge, find the homepage.isml template.

Path: app_storefront_core\cartridge\templates\default\content\home\homepage.isml

Include the following code before the closing isdecorate tag near line 29.

6. In the storefront cartridge, find the producttopcontent.isml template.

Path: app_storefront_core\cartridge\templates\default\product\producttopcontent.isml

Include the following code before the closing isif tag near line 92.

7. In the storefront cartridge, find the catlanding.isml template.

Path: app_storefront_core\cartridge\templates\default\rendering\category\catlanding.isml

Include the following code before the closing decorate tag near line 30.

8. In the storefront cartridge, find the productgrid.isml template.

Path: app_storefront_core\cartridge\templates\default\search\productgrid.isml

Include the following code before the  <ul id="search-result-items" tag near line 9.

9. In the storefront cartridge, find the pt_account.isml template.

Path: app_storefront_core\cartridge\templates\default\account\pt_account.isml

Replace the following code after line 8.

10. In the storefront cartridge, find the pt_checkout.isml template.

Path: app_storefront_core\cartridge\templates\default\checkout\pt_checkout.isml

Replace the following code after line 8.

11. In the storefront cartridge, find the pt_orderconfirmation.isml template.

Path: app_storefront_core\cartridge\templates\default\checkout\pt_orderconfirmation.isml

Replace the following code after line 8.

12. In the storefront cartridge, find the pt_storefront.isml template.

Path: app_storefront_core\cartridge\templates\default\content\home\pt_storefront.isml

Replace the following code after line 8.

13. In the storefront cartridge, find the pt_categorylanding.isml template.

Path: app_storefront_core\cartridge\templates\default\search\pt_categorylanding.isml

Replace the following code after line 8.

14. In the storefront cartridge, find the pt_contentsearchresult.isml template.

Path: app_storefront_core\cartridge\templates\default\search\pt_contentsearchresult.isml

Replace the following code after line 8.

15. In the storefront cartridge, find the pt_productsearchresult_nohits.isml template.

Path: app_storefront_core\cartridge\templates\default\search\pt_productsearchresult_nohits.isml

Replace the following code after line 8.

Include the following code after line 52.

16. In the storefront cartridge, find the productgrid.isml template.

Path: app_storefront_core\cartridge\templates\default\search\productgrid.isml

Replace the following code after line 8.

17. In the storefront cartridge, find the pt_productsearchresult.isml template.

Path: app_storefront_core\cartridge\templates\default\search\pt_productsearchresult.isml

Replace the following code after line 8.

18. In order to handle cart data sending to Emarsys right after user clicks the Add to cart button, the following modifications are required: in the storefront cartridge find the addToCart.js script. Add the following code in the addToCart function.

Path: app_storefront_core\cartridge\js\pages\product\addToCart.js

To connect your Loyalty Wallet, the following snippet should be placed in the footer

(Path: app_storefront_core\cartridge\templates\default\components\footer\footer_UI.isml) after line 38: <isinclude template="/loyaltyWallet"/>

Also, to customize the Emarsys Loyalty Wallet:

1. Navigate to Business Manager > Merchant Tools > Site Preferences > Custom Preferences.
2. Search for the EmarsysLoyaltyWallet Custom Site Preference Groups
3. Emarsys Loyalty Wallet Enabled must be enabled.
4. Other fields must also be filled. Please see section Site preferences configuration for a detailed description.