The Emarsys Salesforce Commerce Cloud plug-in was certified by Salesforce in August 2021. The integration and documentation are available on Salesforce Marketplace.
Further reading:
- Emarsys Salesforce Commerce Cloud plug-in - B2C Commerce Link Cartridge - Getting started - from 2020
- Emarsys Salesforce Commerce Cloud plug-in - B2C Commerce Link Cartridge - Operations guide - from 2020
- Emarsys Salesforce Commerce Cloud plug-in - B2C Commerce Link Cartridge - User manual - from 2020
Integration components
The Emarsys integration consists of two B2C Commerce cartridges, one used for communicating with the Emarsys Platform and the other one used to extend the standard Business Manager functionality with a custom module - this module will allow the merchant to customize the newsletter subscription behavior and to configure the B2C Commerce fields that will be added to transactional emails. Also, the Business Manager module extension will allow the merchant to set the fields that will be added to the CSV file that is used for the initial database load feature. Please find the cartridge components listed below.
B2C Commerce cartridges
1. Integration Cartridge
- int_emarsys
Forms
- default/emarsyssignup.xml
- default/newsletter_unsubscribe.xml
Models
- loyaltyCustomerData.js
Scripts
- js/emarsys.js
- js/emarsysAnalytics.js
- js/emarsysSubscription.js
- js/util.js
- scripts/hooks/emails.js
- scripts/service/emarsysService.js
- scripts/service/emarsysFTPService.js
- scripts/util/StepUtil.js
- scripts/helpers/emarsysAnalyticsHelper.js
- scripts/helpers/emarsysEventsHelper.js
- scripts/helpers/emarsysHelper.js
- scripts/helpers/emarsysResource.js
- scripts/helpers/ftpClientHelper.js
- scripts/helpers/scarabQueueHelper.js
- scripts/helpers/jobHelper.js
- scripts/helpers/triggerEventsHelper.js
-
JOBS
- scripts/jobsteps/CreateExternalEvents.js
- scripts/jobsteps/CreateSingleChoiceValueMapping.js
- scripts/jobsteps/ExportCatalog.js
- scripts/jobsteps/ExportCustomerInfo.js
- scripts/jobsteps/ExportOrders.js
- scripts/jobsteps/FtpUpload.js
- scripts/jobsteps/GetExternalEventsJob.js
- scripts/jobsteps/GetProfileFieldsJob.js
- scripts/jobsteps/GetSourceID.js
- scripts/jobsteps/OrderStatusСhangeNotification.js
SCSS
- scss/_mixins.scss
- scss/_newsletter.scss
- scss/stylesheet.scss
Static
- static/default/css/stylesheet.css
- static/default/js/emarsys.js
- static/default/js/emarsysAnalytics.js
- static/default/js/emarsysSubscription.js
- static/default/js/util.js
Templates
- default/email/dbload_notification.isml
- default/resources/emarsysresources.isml
- default/subscription/double_optin_thank_you_page.isml
- default/subscription/emarsys_alreadyregistered.isml
- default/subscription/emarsys_datasubmitted.isml
- default/subscription/emarsys_disabled.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/loyaltyWallet.isml
- default/successjson.isml
Resources
- resources/dbload_notification.properties
- resources/emarsys.properties
- resources/emarsysinfo.properties
- resources/forms.properties
- resources/locale.properties
- resources/newsletter_unsubscribe.properties
2. Controller cartridges
- int_emarsys_sg
Controllers
- controllers/Account.js
- controllers/CustomerService.js
- controllers/EmarsysNewsletter.js
- controllers/Predict.js
Scripts
- models/ emarsysNewsletterModel.js
Templates
- default/subscription/userdataform.isml
- default/unsubscribe/landing_unsubscribe.isml
Resources
- resources/emarsys.properties
3. Business Manager Cartridge
- bm_emarsys
Controllers
- EmarsysAdmin.js
- ExternalEvents.js
- NewsletterSubscription.js
Forms
- default/newsletterSub.xml
- default/sendOrderConfEmail.xml
Scripts
- js/components/showStatus.js
- js/components/dialogPopup.js
- js/dynamic.js
- js/externalEvents.js
- js/forms.js
- js/main.js
- js/tabs.js
- js/utils.js
- scripts/helpers/bmEmarsysHelper.js
SCSS
- scss/dialogPopup.scss
- scss/externalEvents.scss
- scss/global.scss
- scss/main.scss
- scss/notification.scss
- scss/tabs.scss
Static
- default/css/dialogPopup.css
- default/css/externalEvents.css
- default/css/global.css
- default/css/main.css
- default/css/notification.css
- default/css/tabs.css
- default/js/dynamic.js
- default/js/externalEvents.js
- default/js/forms.js
- default/js/main.js
- default/js/tabs.js
- default/js/util.js
Templates
- default/application/inputfield.isml
- default/application/modules.isml
- default/components/dialogPopup.isml
- default/components/dynamic.isml
- default/components/errorPage.isml
- default/components/modules.isml
- default/components/newsletterConfiguration.isml
- default/components/pageHeader.isml
- default/components/sendOrderConfEmail.isml
- default/components/tabs.isml
- default/eventsPage.isml
- default/mainPage.isml
- default/pageWrapper.isml
Resources
- resources/ dialogPopup.properties
- resources/dynamicTemplate.properties
- resources/errorMessages.properties
- resources/externalEvents.properties
- resources/forms.properties
- resources/newsletter.properties
- resources/pageDescription.properties
- resources/pageTitle.properties
- resources/ tabs.properties
Extension file
- bm_extensions.xml
Setup
Emarsys cartridge installation
To install the Emarsys integration for the first time on your instance you need to follow the next steps:
- Download and extract the Emarsys integration archive to your local file system. For example, the cartridge folder of your project.
- Inside the site_template folder, modify the SiteGenesis folder name and SiteGenesis references inside the XML files to match your site name.
- Import the cartridge into your workspace and link it to the B2C Commerce Server Connection.
- Import site_template.zip into your instance (please see more details in the following sections of the document).
- 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).
If you implement the bm_emarsys cartridge on a site level, then it may cause conflict with the JavaScript implemented on your site and break the implementation. Please compare the Salesforce Commerce Cloud code with the Emarsys code and make sure that they are implemented at the appropriate level.
- Assign the emarsys_sg_changes, int_emarsys, int_emarsys_sg and bm_emarsys cartridges to the Business Manager site (detailed below).
Configuration
Once you have the cartridges installed, you will need to make the necessary configurations in order for the integration to work.
Business Manager Configuration
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.
Import site_template.zip
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.
Business Manager Modules
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.
Site preferences configuration
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 or region IDs on the B2C Commerce side with the IDs on the Emarsys side. If you need to add another country or region, you’ll have to manually update the JSON with the correct key-value pair, where the key is the DW country or region ID and the value is the Emarsys country or region ID. Please check this link for the complete list of Emarsys country or region 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:
{
"1": "firstName",
"2": "lastName",
"3": "emailAddress",
"4": "birthday",
"5": "gender",
"10": "address1",
"11": "city",
"12": "stateCode",
"13": "postalCode",
"14": "countryCode",
"15": "phone",
"17": "jobTitle",
"18": "companyName",
"46": "salutation"
}
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:
{
"1": {
"1_1": "firstName",
"2_1": "lastName",
"3_1": "emailAddress",
"10_1": "address1",
"11_1": "city",
"12_1": "stateCode",
"13_1": "postalCode",
"14_1": "countryCode",
"15_1": "phone",
"18_1": "companyName"
},
"2": {
"1_2": "firstName",
"2_2": "lastName",
"3_2": "emailAddress",
"10_2": "address1",
"11_2": "city",
"12_2": "stateCode",
"13_2": "postalCode",
"14_2": "countryCode",
"15_2": "phone",
"18_2": "companyName",
}
}
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!)
- The following attributes are required in the CSV file:
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=
Emarsys Predict Export Attributes Configuration
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 SmartInsight Export Attributes Configuration
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
.
For more information on how to format custom fields, see Custom fields.
The following attributes are mandatory in the feed:
- order - order number
- date - date of the order (YYYY-MM-DD)
If you use the date format YYYY-MM-DD, then you will not be able to use Smart Insight as the data source for Revenue Attribution and you cannot use Emarsys Loyalty at all. If you would like to use these features, change the date to timestamp in your sales date file. For more information, see timestamp
in Standard field set.
- customer - unique customer id (this ID must be available in Emarsys Suite as well)
If you are using a unique customer ID other than email, then you need to ensure that the setCustomerId Web Extend command is used.
- 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.
Emarsys Catalog and SmartInsight Site Preferences
The table below contains the list of Site Preferences for Emarsys Catalog and SmartInsight.
Custom attribute | Type | Description |
Predict: Merchant ID | String | Used to enable JavaScript tracking code, recommendations, etc. |
Predict: Enable tracking code | Boolean | Enables/disables the JavaScript tracking code. |
Thank You For Your Order Page Recommendation Type | Enum Of Strings | Select recommendation widget type to show on storefront "thank you for your order” page. |
Product Detail Page Recommendation Type | Enum Of Strings | Select recommendation widget type to show on storefront PDP. |
Home Page Recommendation Type | Enum Of Strings | Select recommendation widget type to show on storefront Home page. |
Cart Page Recommendation Type | Enum Of Strings | Select recommendation widget type to show on storefront cart page. |
Search Page Recommendation Type | Enum of Strings | Select recommendation widget type to show on storefront search page. |
Category Page Recommendation Type | Enum of Strings | Select recommendation widget type to show on storefront category page. |
List of product variation attributes for predict Feed | Set of String | List of product variation attributes for Predict Feed. |
Predict: Product attributes for exporting | Set Of String | Mandatory attributes: item, available, title, link, image, category (path), price for catalog export. |
Export Folder | String | Emarsys Predict export folder relative to IMPEX/src/ . |
Map of locales and currencies | String | Map of configured locales and their currency codes { "en_US":"USD", "it_IT":"EUR", "en_GB":"GBP”}. |
SmartInsight Available Elements | Set Of String | SmartInsight Available Elements. |
Emarsys Services
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.

Job schedules
Emarsys-Setup
You also need to run the Emarsys-Setup job to ensure that several Emarsys Integration screens open properly.
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)
Please note that the source ID is optional.
- 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.
Emarsys-ExportOrders
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.
Emarsys-Init-Database
This job is initialized to fetch profile data from Salesforce Commerce Cloud and sends it directly to Emarsys. This job is needed to create segments, personalize your marketing messages to engage your clientele more efficiently.

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.
Emarsys-ExportCatalog
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. Once this job is finished, a CSV file is created and you can use the products in Emarsys to personalize your marketing messages.
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.
Emarsys - OrderStatusСhangeNotification
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.
Custom code
In order for the email subscriptions to work, a few updates need to be made on the storefront cartridge and inside Business Manager.
Custom code inside core templates
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:
<isif condition="${dw.system.Site.current.preferences.custom.emarsysEnabled}">
<script type="text/javascript"><isincludetemplate="resources/emarsysresources"/></script>
<script src="${URLUtils.staticURL('/js/emarsys.js')}"type="text/javascript"></script>
</isif>

Path: app_storefront_core\cartridge\templates\default\components\header\htmlhead.isml
Include the CSS file into the htmlhead.isml template:
<link rel="stylesheet"href="${URLUtils.staticURL('/css/stylesheet.css')}"/>

Account subscription Business Manager configuration
- Navigate to Business Manager > Merchant Tools > Content > Content Assets.
- Search for the account-nav-registered content asset.
- Lock the content asset in order to be able to edit it.
- Go to the
body
attribute and add the following line to the list of the My Account section (please also check the screenshot below):
<li><a title="Email Settings" href="$httpsUrl(EmarsysNewsletter-EmailSettings)$">Email Settings</a></li>
Controller integration configuration
Account subscription
For the subscription from the account profile to work, an update to the Account needs to be made. Also, there is a small change required in the account-nav-registered content asset.
- In your storefront controllers cartridge, find CustomerModel.js and add in the
createAccount
function and replace the return with:
//Logs the customer in.
var result=Transaction.wrap(function(){
return CustomerMgr.loginCustomer(email,password,rememberMe);
});
//Emarsys subscription
require('int_emarsys_sg/cartridge/controllers/EmarsysNewsletter').AccountSubscriptionPipe();
return result;

- In the storefront controllers cartridge find the Account.js controller and add in the
confirm
function after line 129:
//Emarsys subscription
require('int_emarsys_sg/cartridge/controllers/EmarsysNewsletter').AccountSubscriptionPipe();
Checkout subscription
In order for the end user to be able to subscribe for newsletters during the checkout process, an update to the COBilling.js controller file from the controllers cartridge needs to be made. At line 549, in the save
function and after the step is marked as fulfilled, add a call to the EmarsysNewsletter-CheckoutSubscription method:
//Emarsys checkout subscription
require('int_emarsys_sg/cartridge/controllers/EmarsysNewsletter').CheckoutSubscriptionPipe();
Order confirmation emails
In the storefront controllers cartridge, find COPlaceOrder.js and in the start()
function:
- Before payments handling add:
if (require('dw/system/HookMgr').hasHook('payment.beforeHandle')){
require('dw/system/HookMgr').callHook('payment.beforeHandle','beforeHandlePayment',{Order:order});
}
- After the order is created and submitted, and execution in the successful execution or the order placement at line 175:
if (require('dw/system/HookMgr').hasHook('order.afterSubmit')){
require('dw/system/HookMgr').callHook('order.afterSubmit','afterOrderSubmit',{Order:order});
}
External events triggering functionality
Contact Form Submitted
In the storefront controllers cartridge, find the controller CustomerService.js. Function submit()
should return value of the contactUsResult
variable (str. 68):
Forgot password submitted
In the storefront controllers cartridge find the controller Account.js. Add the return
statement in the passwordResetDialogForm()
function (str. 262):
The passwordResetDialogForm()
function also need some additional return
statements (str. 199 and str. 224):
Shipping confirmation emails integration
It doesn’t require any additional modifications to the core cartridge.
Initial database load integration
It doesn’t require any additional modifications to the core cartridge.
Emarsys Predict
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:
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:(pdict.Product.name||'ProductDetail'),
type:'product',
ns:'product',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
2. In the storefront cartridge, find the pt_cart.isml template.
- Path: app_storefront_core\cartridge\templates\default\checkout\cart\pt_cart.isml
- Include the following code before the closing
isif
tag near line 891.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'Cart',
type:'Cart',
ns:'cart',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
3. In the storefront cartridge, find the cart.isml template.
- Path: app_storefront_core\cartridge\templates\default\checkout\cart\cart.isml
- 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 .
<iscomment>Predict Recommendations Widget Goes Here</iscomment>
<div id="predict-recs"></div>

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.
<iscomment>Predict Recommendations Widget Goes Here</iscomment>
<div id="predict-recs"></div>
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.
<iscomment>Predict Recommendations Widget Goes Here</iscomment>
<div id="predict-recs"></div>
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.
<iscomment>Predict Recommendations Widget Goes Here</iscomment>
<div id="predict-recs"></div>
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.
<iscomment>Predict Recommendations Widget Goes Here</iscomment>
<div id="predict-recs"></div>

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.
<iscomment>Predict Recommendations Widget Goes Here</iscomment>
<div id="predict-recs"></div>

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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'MyAccount',
type:'MyAccount',
ns:'account',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper '))()}"scope="page"/>
<isscript>
var pageContext={
title:'Checkout',
type:'checkout',
ns:'checkout',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'OrderConfirmation',
type:'orderconfirmation',
ns:'orderconfirmation',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
pdict.showCountrySelector=true;
var pageContext={
title:'Storefront',
type:'storefront',
ns:'storefront',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/EmarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'ProductSearchResults',
type:'search',
ns:'search',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/EmarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'ContentSearchResults',
type:'search',
ns:'search',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/EmarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'ProductSearchResultsNoHits',
type:'search',
ns:'search',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
Include the following code after line 52.
<iscomment>PredictRecommendationsWidgetGoesHere</iscomment>
<div id="predict-recs"></div>

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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'ProductSearchResults',
type:'search',
ns:'search',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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.
<isset name="EmarsysAnalyticsHelper"value="${new(require('int_emarsys/cartridge/scripts/helpers/emarsysAnalyticsHelper'))()}"scope="page"/>
<isscript>
var pageContext={
title:'ProductSearchResults',
type:'search',
ns:'search',
pdict:pdict
};
pageContext.analytics=EmarsysAnalyticsHelper.setPageData(pageContext);
</isscript>
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
$.ajax({
url: EmarsysUrls.emarsysAddToCartAjax
}).done(function (data) {
if (data) {
window.ScarabQueue.push(['cart', data]);
window.ScarabQueue.push(['go']);
}
});

Emarsys Loyalty Wallet
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:
- Navigate to Business Manager > Merchant Tools > Site Preferences > Custom Preferences.
- Search for the EmarsysLoyaltyWallet Custom Site Preference Groups
- Emarsys Loyalty Wallet Enabled must be enabled.
- Other fields must also be filled. Please see section Site preferences configuration for a detailed description.
Testing
For a complete list of test cases, please refer the test cases document.