Contents

Introduction

The following installation guide is compatible with the following Magento versions:

  • Community version 1.7
  • Community version 1.8
  • Community version 1.9
  • Magento Enterprise 1.12
  • Magento Enterprise 1.13
  • Magento Enterprise 1.14

Prerequisites

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

If you have ever used a previous Magento integration from Emarsys, please make sure that this has been uninstalled.

You will also need to do the following:

  • For Community Editions older than 1.8, and Enterprise Editions older than 1.13.1, make sure to replace the curl.php file located in MAGE_ROOT_DIR/lib/Varien/Http/Adapter/ (the replacement file is provided by Emarsys).
    The older curl.php file cannot handle the headers passed from the Suite API, and will not show the list of fields on the mapping page.
  • Make sure your server’s PHP memory limit is set to a minimum of 512 MB.
    This is because some extension jobs are large and require increased PHP memory.
  • Make sure the PHP SOAP extension is enabled on your Magento host. Your hosting provider can check this for you.
    This is needed to be enable to allow API communication between the Extension and Magento.
  • If Installed, AOE scheduler should be updated to the latest version.
    The old version has little-to-no documentation, and includes several bugs and functions that block the extension.
  • Set your Magento Cron to run on a 5-minutes basis.
    Some scheduled jobs are too large for the Magento scheduler to handle, and will timeout if attempted. You can check the Magento documentation for instructions on how to do this or ask your Magento provider to do it for you.
  • If you are using Smart Insight, ask Emarsys Support for the FTPS credentials. Also, make sure that your Magento hosting provider allows outgoing connections to the address exchange.si.emarsys.net over the ports TCP21 and TCP32000-32500.
    An FTPS/SFTP is required for SI data exports, and the connection must not be whitelisted.
  • Make sure you have the necessary access level to install extensions from the Magento Marketplace in your Magento shop.
  • Admin access to both the staging and production panels is required for Emarsys to support the Extension, as well as SSH access to your webserver (direct SSH access is preferred, but not mandatory, as long as there is a resource on your side that can access the server when required).
  • Create any custom fields in Emarsys that you will need to map the Magento fields to.
  • Create an additional two custom fields in Emarsys called:

    • Magento Customer ID
    • Magento Subscriber ID

    Please note that these field names are case-sensitive (e.g. Magento customer id won’t work).

Installing the Emarsys for Magento Package

You can obtain the Emarsys for Magento installation package from Emarsys Support (a request form is available from the Magento Marketplace).

Once you have the package, you should install it in your Magento shop as follows:

1. Install the package

  • Unzip the package and open the root folder.

    magento-1-package

  • Copy the contents (the app folder and package.xml file) to the Magento root folder.

2. Clear the Magento cache

  • Return to the Magento admin module and navigate to System > Cache Management and click Flush Magento Cache.

    magento-1-flush-cache

  • Log out of the Admin module and then log in again.
  • Now you will a new section for Emarsys Connect in the System page, Configuration menu:

    magento_sync_1

  • The Dashboard of the Magento Admin Panel will now also have a new entry Emarsys Email:

    magento-1-emarsys-email

    Configuring the Installation

You will now need to configure the installation.

1. Set up the Emarsys Suite API connection

First, configure the Emarsys API connection as follows:

  • Navigate to System > Configuration > Emarsys Connect > Suite settings.

    magento_install_3

In the API settings section, make the following settings:

  • Enabled – Select Yes to enable the plugin.
  • API Endpoint – Select the API endpoint value as required.
  • Custom API URL – Enter the URL as required.
  • Debug – We recommend always choosing Yes here to enable additional debugging logs. The logs are useful for tracking the export activity as we start exporting contacts and sales files later on.
  • Plugin profiler – This should normally be set to Yes. However, in some Magento versions, Debug and Plugin profiler cannot be enabled together, so this control has been added to give you the option of switching one of them off.
  • Clean module log files and Download module log files – These buttons can be used at a later stage to help you view and clear the log files as you proceed with the setup.
  • Cron service API ping – This must be Enabled, since it allows the extension to establish that the connection is still active. If the ping isn’t enabled, the API calls will begin to queue, limiting the real-time features.
  • Suite API Username and Suite API Password – Enter your Emarsys API credentials (not your Emarsys account credentials!), then click Test connection to check that you have entered these correctly. The Test connection button should turn green to signal that the connection has been established between Magento and your B2C Marketing Cloud account.
  • Click Save Config to save your settings.

Now, enable the logs as follows:

  • Click Download module log files
  • Click OK in the pop-up dialog.
  • The Download module log files button turns green and the link Click this link to download is displayed. Clicking this link downloads the logs.

Note: The above steps work only when the Debug option is Yes.

![magento_install_5](/assets/images/magento_install_4.png)

2. Configure the Contact Synchronization settings

Before you start, please read Synchronizing Contact Data With Magento to get an overview of how Magento and Emarsys handle contacts and their data.

After this, your first task is to map your contact database fields. Contact synchronization is based on the correct mapping of your Magento and Emarsys database fields, so you should already have made sure that you have already created all the fields in Emarsys that you want to map.

If you have forgotten a field, you can create it now but you will have to return to the Emarsys Events page and click Update Schema to add the fields to Magento.

Proceed as follows:

  • Navigate to System > Configuration > Emarsys Connect > Contact Synchronization and open the Field mapping section.

    magento_install_5

  • The fields FirstName, LastName and Email are mapped by default.
  • Select a Magento field from the list on the left and then select the corresponding Emarsys field from the list in the middle.
  • Click the right arrow to move the pair to the mapped fields list on the right.
  • Repeat this for all the fields you want to map.

Now, configure your synchronization settings as follows:

  • On the Contact Synchronization page, open the Synchronization settings section and make the following settings:

    magento_install_6

  • Enable Customers export and Enable Subscribers export – Select Yes for both these options to enable synchronization of both Magento contact types.
    Synchronization mode – Select Realtime-failsafe or Background only as per your requirements.
  • Background Runtime – Set the time of day for the daily data synchronization.
  • Contacts synchronization order – Select the order in which the data is synchronized (relevant for the opt-in status of contacts).
  • Notification secret key – This is the password required for the export notifications.
  • Key Id – Select your unique identifier for the contacts.
  • Click Save Config to save your settings.

Verify your settings by clicking the Export Customers button. This button should turn green to show that the configuration is correct and that the export is running in the background. Repeat for the Export Subscribers button.

Note: Clicking the Export Customers and Export Subscribers buttons too closely together will result in an error.

3. Verify Your Data Synchronization

To verify that your configuration is working, perform the following checks.

Verify customer sync to Emarsys

  1. Create a customer from the Magento backend or frontend.
  2. Click Export Customers
  3. Log in to your Emarsys account.
  4. Search for the customer using the in contacts by email option and entering their email address.
  5. In the Search Results page click the edit icon to open the contact properties.
  6. Verify whether the same customer is displayed or not.

Verify subscriber sync to Emarsys

  1. Create a subscriber from the Magento backend or frontend.
  2. Click Export Subscribers
  3. Follow the remaining steps as described above.

4. Configure your Smart Insight FTP Connection

If you are a Smart insight customer, follow the instructions in the Magento and Smart Insight article to configure and verify your data synchronization with Smart Insight.