The Emarsys Salesforce Commerce Cloud plug-in was certified by Salesforce in August 2021. The integration and documentation are available on Salesforce Marketplace.
Integration components
The Emarsys integration consists of two Salesforce Commerce Cloud 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 Salesforce Commerce Cloud fields that will be added to the 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.
SFRA Commerce Cloud 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/emarsysEventsHelper.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. Cartridge SFRA
- int_emarsys_sfra
Scripts
- helpers/emarsysSFRAHelper.js
- helpers/newsletterHelper.js
Models
- customerModel.js
Controllers
- Account.js
- CheckoutServices.js
- Cart.js
- ContactUs.js
- EmarsysNewsletter.js
- Home.js
- Order.js
- Predict.js
- Product.js
- Search.js
Templates
- default/initAnalytics.isml
- default/subscription/userdataforn.isml
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
- externalEvents.scss
- scss/global.scss
- scss/main.scss
- scss/notification.scss
- scss/tabs.scss
Static
- default/scss/dialogPopup.scss
- default/scss/externalEvents.scss
- default/scss/global.scss
- default/scss/main.scss
- default/scss/notification.scss
- default/scss/tabs.scss
- 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/eventsPageisml
- 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 examaple, the cartridge folder of your project.
- Inside the site_template folder, modify the RefArch folder name and RefArch references inside the XML files to match your site name.
- Import the cartridge into your workspace and link it to the Salesforce Commerce Cloud Server Connection.
- Import the file site_template.zip into your instance (please see more details in the following sections of the document).
- Assign the emarsys_sfra_changes, int_emarsys, int_emarsys_sfra and bm_emarsys cartridges to all sites that you want to integrate with Emarsys make sure that the int_emarsys and int_emarsys_sfra 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 int_emarsys 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_sfra_changes , int_emarsys, int_emarsys_sfra and bm_emarsys) into the Cartridges field. Make sure that the int_emarsys and int_emarsys_sfra cartridges appear before the storefront cartridge.
6. Click on the Apply button.
7. Navigate back to Manage sites (using breadcrumbs or by clicking the Back to list button).
8. Click the Business Manager link.

9. Add the emarsys_sfra_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 RefArch folder name and RefArch references in 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 from 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 below that you need to follow in order to activate the modules.
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 drop-down. Select your site from the Context dropdown.
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 the switch to turn 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 the 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: the JSON used to map the country IDs on Salesforce Commerce Cloud 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: it is automatically populated after metadata import.

- Emarsys Contact Fields Map: the JSON used to map account information and shipping address on the Salesforce Commerce Cloud 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: the JSON used to map the rest of saved for every customer addresses on the Salesforce Commerce Cloud 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 - it represents the ID of the Predict merchant user. It should be taken from the Emarsys dashboard.
- Predict: Enable tracking code - It enables or disables JS tracking code on your site.
-
List of Product Variation attributes for predict feed - the list of product variation attributes used for the predict job. All the product variation attributes should be put here. For example:
product.custom.color
product.custom.size
-
Predict: Product attributes for exporting - list of product attributes for export feed. Mandatory attributes:
- The merchant will be able to add any Salesforce Commerce Cloud 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 Smart Insight 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
- price - 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 Smart Insight Export Attributes Configuration for a detailed description.
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.
If you are using a unique customer ID other than email, then you need to ensure that the setCustomerId Web Extend command is used.

11. Set the following attributes:
- Emarsys Loyalty Wallet Enabled - this is to switch 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
Emarsys Predict 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. Predict 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 few 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 attributes are available:
- Standard product attributes
- Product custom attributes
Emarsys Smart Insight Export Attributes Configuration
Emarsys Smart Insight attributes will be configurable under the emarsysSmartInsightAvailableElements site preference. Merchants 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 the Emarsys platform 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
- price - 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 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 order object.Examples: order.orderNo, order.creationDate, etc.
-
Delivery method: 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: Separate case for the 'paymentMethod.display' element only. It reads 1st payment method from order object
- Order rebate: Separate case for the 'orderRebate' element only.
-
Shipping costs: Separate case for the 'shippingCosts.display' element only, it reads shipping total price from the
order.shipments[0]
object. - customerNo: Separate case for customer No.
- masterid, variantid: Include 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 Smart Insight 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 | Smart Insight Available Elements. |
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 on 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 configuration:
- Login in to Business Manager.
- Select your site in the top left corner of the page.
- Navigate to Merchant Tools > Custom Objects > Custom Object Editor.
- Select the object type EmarsysExternalEvent and click the Find button.
- Click the StoredEvents link in the (ExternalEvents) column.
- Fields Newsletter Subscription Source and Other Source should not be empty. These fields should contain lists of SFCC events, for which appropriate Emarsys external events should be created.
After you checked the configuration you are all set to run the job:
- Login in to Business Manager.
- Go to Administration > Operations > Job schedules.
- Select the Emarsys-Setup job and run it.
This job includes 5 steps:
- GetSourceID - It reads the 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 this step is to store the 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 thenewsletterSubscriptionSource 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 events 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 configuration (default value: StoredEvents) is stored in this object.
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 the corresponding field defined in the Emarsys documentation.
File structure:
- Name: sales_items_<YYYYMMDDHHiiss>_<shopinfo>.csv
Please make sure that your sales data file follows this naming convention.
- 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)
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.
3. 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.
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.2 destinationFolder - the target folder path to save the CSV file.
1.3 smartInsightCurrency - mnemonic currency code of the currency that is configured for the.Smart.Insight.
1.4 enableCustomTimeFrame - it enables timeframe for exported orders.
1.5 queryString - It addsa query addendum for searchOrders. Starts with AND.
1.6 timeframeStart - timeframe start date for the Emarsys historical export job.
1.7 timeframeEnd - timeframe end date for the Emarsys historical export job.
2. custom.CSComponents.FtpUpload
2.2 ServiceID - the service ID used in the Job. Default value: exchange.emarsys.api.
2.3 FilePattern - File pattern where used regular expression.
2.4 SourceFolder - Local folder with files, relative to IMPEX/.
2.5 TargetFolder - Remote folder on Server, relative to home directory.
2.6 ArchiveFolder - Local folder where files are archived, relative to IMPEX/.
2.7 NoFileFoundStatus - The exit code in case no files were found.
2.8 IsDisabled - It marks the step as disabled. This will skip the step and returns an OK status.
Emarsys-Init-Database
This job fetches profile data from Salesforce Commerce Cloud and sends it 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 csvFileColumnsDelimiter - The character used to separate columns in the CSV file.
1.2 optInStatus - 0 - All users empty; 1 - All users true; 2 - Depending on attribute.
1.3 customAttributeId - The opt-In Status custom attribute ID.
1.4 profilesExportThreshold - how many profiles should be exported at once?
1.5 queryString - Add a query addendum for searchOrders. Start with AND.
1.6 enableCustomTimeFrame - It enables timeframe for exported orders.
1.7 timeframeStart - Timeframe start date for the Emarsys historical export job.
1.8 timeframeEnd - Timeframe end date for the Emarsys historical export job
1.9 fromEmail - The email address for forwarding notifications.
1.10 mailTo - Notifications destination e-mail address.
1.11 mailSubject - 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 the 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:
- Item - unique product id
- available - Is the product available (and can be recommended)?: true or false
- title_multilang - Product title
- link_multilang - Deep link to the product
- image - URL of the product image
- category_multilang - Category path to the product separated by “ > “, e.g. books > scifi > startrek
- price_multilang - Product price (float value 1234.99)
- 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 - Add 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 - 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 - OrderStatusСhangeNotification
This job initialized email sending 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.
SFRA integration
Email settings
In order to connect the Email Settings, you need to open the file header.isml (app_storefront_base\cartridge\templates\default\account\header.isml) and add this code after line 17:
<liclass="nav-item"role="presentation">
<atitle="EmailSettings"href="${URLUtils.url('EmarsysNewsletter-EmailSettings')}"role="menuitem"tabindex="-1">
${Resource.msg('emarsys.settings','emarsys',null)}
</a></li>
In this file mobileHeader.isml (app_storefront_base\cartridge\templates\default\account\mobileHeader.isml) add code after line 23:
<liclass="dropdown-item"role="menuitem">
<ahref="${URLUtils.url('EmarsysNewsletter-EmailSettings')}"class="dropdown-link"role="button"title="EmailSettings">
${Resource.msg('emarsys.settings','emarsys',null)} </a></li>
Add the checkbox "Please add me to Salesforce Commerce Cloud's email list."
For adding the subscription checkbox to the billing address, you need to open the file billing.isml (app_storefront_base\cartridge\templates\default\checkout\billing\billing.isml) and add this code after line 73:
<divclass="form-groupcustom-controlcustom-checkbox">
<input
type="checkbox"
class="custom-control-input"id="add-to-email-list"
<isprintvalue=${pdict.forms.billingForm.addToEmailList.attributes}encoding="off"/>>
<labelclass="custom-control-label"for="add-to-email-list">
<isprintvalue="${pdict.forms.billingForm.addToEmailList.label}"encoding="htmlcontent"/>
</label>
</div>
In this file billing.xml (app_storefront_base\cartridge\forms\default\billing.xml), add code after line 7:
<field formid="addToEmailList" label="checkout.addtoemaillist" type="boolean" mandatory="false"/>
In this file forms.properties (app_storefront_base\cartridge\templates\resources\forms.properties), add code after line 187:
checkout.addtoemaillist=PleaseaddmetoSalesforceCommerceCloud'semaillist

Checkout subscription
For the checkout subscription with place order, the following code must be inserted in CheckoutService.js, the file is in the path: cartridges\app_storefront_base\cartridge\controllers\CheckoutServices.js
1. After line 659:
if(require('dw/system/HookMgr').hasHook('emarsys.sendOrderConfirmation')){
require('dw/system/HookMgr').callHook('emarsys.sendOrderConfirmation','orderConfirmation',{Order:order});
}
2. After line 712:
if (require('dw/system/HookMgr').hasHook('emarsys.order.afterSubmit')){
require('dw/system/HookMgr').callHook('emarsys.order.afterSubmit','afterOrderSubmit',order);
}
Update home page
You need to update the code in homePage.isml, the file is in the path: app_storefront_base\cartridge\templates\default\home\homePage.isml
1. Find line 30 and add the ID: id="emarsys-newsletter-subscription"

2. In line 34, update the <input>
tag:
<input type="text"
id="email-alert-address"
class="form-control"
name="hpEmailSignUp"
placeholder="${Resource.msg('placeholdertext.form.emailsignup','homePage',null)}"
aria-label="${Resource.msg('placeholdertext.form.emailsignup','homePage',null)}">
Page header update
You need to update the code in pageHeader.isml, the file is in the path:
cartridges\app_storefront_base\cartridge\templates\default\components\header\pageHeader.isml
1. After line 17, insert the code:
<script>
var analyticsData = {};
analyticsData.emarsysAnalytics = <isprint value="${JSON.stringify(pdict.analyticsData)}"encoding="off"/>
||{emarsysAnalytics:{isEnableEmarsys:false}};
</script>
Predict
To make recommendations on the site you need to add a <div>
tag with id="predict-recs"
to the following places:
- Product detail page (Path: app_storefront_base/cartridge/templates/default/product/productDetails.isml)
- Home page (Path: app_storefront_base/cartridge/templates/default/home/)
- Cart page (Path: app_storefront_base/cartridge/templates/default/cart/cart.isml)
- Search results page (Path: app_storefront_base/cartridge/templates/default/ search/searchResults.isml)
- Category page (Path: app_storefront_base/cartridgeето/templates/default/rendering/category/catLanding.isml)
- Order confirmation page (Path: app_storefront_base/cartridge/templates/default/checkout/confirmation/confirmation.isml)
Example: productDetails.isml
<iscomment>PredictRecommendationsWidgetGoesHere</iscomment>
<div id="predict-recs"></div>
Loyalty Wallet
To attach your Loyalty wallet, it should be included in the footer
(path: app_storefront_base\cartridge\templates\default\components\footer\pageFooter.isml) after line 35: <isinclude template="/loyaltyWallet"/>
Also, to customize Emarsys Loyalty Wallet, proceed as follows:
- Navigate to Business Manager > Merchant Tools > Site Preferences > Custom Preferences.
- Look for the EmarsysLoyaltyWallet Custom Site Preference Group
- The preference Emarsys Loyalty Wallet Enabled have to be enabled.
- Other fields of the group also have to be filled. Please see section Site preferences configuration for a detailed description.
You should login to your site to see if the Loyalty Wallet is attached. In the right corner of the page, the Loyalty Wallet menu should appear.


Testing
For a complete list of test cases, please refer to the test cases document.