This installation guide describes the steps needed in order to configure the Emarsys cartridge for a Demandware website. It presupposes some degree of familiarity with the Demandware platform.

For a list of all the files in the cartridge, click here.

Contents

Prerequisites

Before you can install Emarsys for Demandware you need an Emarsys API account. Please contact Emarsys Support if you do not already have one.

This integration also requires the Demandware Integration Framework cartridge to be present on the Demandware instance. If you don’t have it already installed, proceed as follows:

  1. Download integrationframework.zip from the Demandware Xchange.
  2. Extract the contents to your local file system.
  3. 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.
  4. 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 Demandware 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:

  1. Download and extract the Emarsys integration files from the Demandware Marketplace to your local file system (e.g. the cartridge folder of your project).
  2. Inside site_template folder, modify the SiteGenesis folder name and the SiteGenesis references inside the .xml files to match your site name.
  3. Make a .zip file of the updated site_template folder. You will later need to import this into the Business Manager (see below).
  4. Import the cartridge into your workspace and link it to the Demandware 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.

demandware-configuration-sites

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.

demandware-configuration-business-manager-settings

After you have applied your changes, return to the Manage Sites page and click the Business Manager link.

demandware-configuration-business-manager-site

Add the int_emarsys and bm_emarsys cartridges to the cartridges path and click Apply.

demandware-configuration-cartridge-path

Importing site_template.zip

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.

demandware-configuration-upload-zip

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.

demandware-configuration-site-preferences

This will open the Emarsys Preferences.

demandware-configuration-emarsys-settings

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 (as per the above screenshot).
  • 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 Demandware 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.

demandware-configuration-admin-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.

demandware-configuration-activate-modules

Your integration is now complete and you can proceed with the Frontend setup and Contact synchronization tasks.

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.

demandware-enable-integration

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 Demandware account (this applies to registered users only), or by clicking the unsubscribe link in the emails received through the Emarsys platform.