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.

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.

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.

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 or region IDs on Salesforce Commerce Cloud 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: 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:

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:

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

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

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

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

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 - this service communicates with Emarsys events.

• exchange.emarsys.api  - it is used to load the directory in 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 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)

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

1. Login in to Business Manager.
2. Select your site in the top left 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. 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:

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

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

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

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.

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:

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

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.

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

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:

1. Navigate to Business Manager > Merchant Tools > Site Preferences > Custom Preferences.
2. Look for the EmarsysLoyaltyWallet Custom Site Preference Group
3. The preference Emarsys Loyalty Wallet Enabled have to be enabled.
4. 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.