This installation guide describes the steps needed in order to configure the Emarsys cartridge for a Salesforce Commerce Cloud website. It presupposes some degree of familiarity with the Salesforce platform.
For a list of all the files in the cartridge, see the appendix.
Before you can install Emarsys for Salesforce you need an Emarsys API account. Please contact Emarsys Support if you do not already have one.
This integration also requires the Salesforce Integration Framework cartridge to be present on the Salesforce instance. If you don’t have it already installed, proceed as follows:
- Download integrationframework.zip from the Salesforce Xchange.
- Extract the contents to your local file system.
- Follow the steps from the documentation file Integration Framework-User and Developer Guide.docx which you can find inside the extracted files, and install it.
- Be sure to assign bc_integrationframework to all the sites that you want to integrate with Emarsys.
You should also make sure that you have created any additional database fields in Emarsys that you might need for your Salesforce transactional emails, as well as the Emarsys external events to trigger them.
Installing the Emarsys cartridge
To install the Emarsys integration for the first time on your instance, you will need to prepare and install the cartridges. Proceed as follows:
- Download and extract the Emarsys integration files from the Salesforce Commerce Cloud Marketplace to your local file system (e.g. the cartridge folder of your project).
- Inside site_template folder, modify the SiteGenesis folder name and the SiteGenesis references inside the .xml files to match your site name.
- Make a .zip file of the updated site_template folder. You will later need to import this into the Business Manager (see below).
- Import the cartridge into your workspace and link it to the Salesforce Server Connection.
Now you are ready to assign the cartridges to the sites you want to integrate with Emarsys.
Configuring the integration
Once you have the cartridges prepared, follow the steps below for each site you want to integrate with Emarsys.
Adding the cartridges to the Business Manager
Log in to the Business Manager and go to Administration > Sites > Manage Sites. There, select the site you would like to integrate with Emarsys.
Open the Settings tab and add the cartridges (int_emarsys and bm_emarsys) to the Cartridges field. Make sure that int_emarsys cartridge appears before the storefront cartridge.
After you have applied your changes, return to the Manage Sites page and click the Business Manager link.
Add the int_emarsys and bm_emarsys cartridges to the cartridges path and click Apply.
In the Business Manager, go to Administration Site Development Site Import Export. Then in the Import, Upload Archive section upload the site_template.zip you created above. Once it is in the list of available files, select it and click Import.
The import may take a few minutes and you should remain on this page until you can see that it has successfully completed.
Configuring the custom site preferences
In the Business Manager, go to Merchant Tools Site Preferences Custom Site Preferences and select Emarsys.
This will open the Emarsys Preferences.
The Emarsys Country Codes and Gender Codes are the Emarsys IDs for the languages and genders supported by the web shop.
Make the following settings:
- Emarsys Source Name – This is the name of a contact source that was previously created in Emarsys.
- Emarsys Environment – This should be set to the Emarsys environment that you log in to. Enter the URL without the https:// part, , for example: suite16.emarsys.net.
- API Username – This is your Emarsys API user name.
- API Key – This is your Emarsys API key.
Click Apply to save your changes.
If you are using Smart Insight or Predict, you should now configure your Salesforce preferences for these products.
Enabling the Emarsys cartridge
After the cartridges have been installed, you will have to activate the Emarsys Business Manager modules that will allow you to configure the integration according to your requirements. Proceed as follows:
In the Business Manager, go to Administration > Organization > Roles & Permissions and select the Administrator role.
Now go to the Business Manager Modules tab, open the Context drop-down, select your site and click Apply.
Activate the checkboxes next to the Emarsys modules that you need and click Update.
Enabling the integration
When you have completed all of your configuration tasks, you can enable and disable the Emarsys integration via the Business Manager. Go to Merchant Tools > Site Preferences > Custom Preferences > Emarsys and activate or deactivate the Enable Emarsys Services checkbox.
If the integration is disabled and a customer tries to subscribe to a newsletter using the global footer or My Account subscription method, they will be redirected to a custom page showing a message that says subscriptions are not active.
However, even if the integration is disabled, as long as the cartridge is installed customers still have the option to unsubscribe from newsletters from their Salesforce Commerce Cloud account (this applies to registered users only), or by clicking the unsubscribe link in the emails received through the Emarsys platform.