From Magento you will need:

• For Community Editions older than 1.8, and Enterprise Editions older than 1.13.1, 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 Emarsys API, and will not show the list of fields on the mapping page.
• Set your server’s PHP memory limit to a minimum of 512 MB. This is because some extension jobs are large and require increased PHP memory.
• Exclude the following path from any caching mechanism you are using: app/design/frontend/base/default/template/emarsys/javascripttracking.phtml. This is where the Web Extend data collection scripts will reside and caching will break their operation.

• AOE Scheduler (or similar) is not mandatory but highly recommended as this exposes the scheduled tasks visually and will help us to support you. Please note that AOE Scheduler is not available for PHP 5.6 and higher.
• Set your Magento Cron to run every one minute for Magento Enterprise editions, and every five minutes for Magento Community editions. 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.
• TCP port 21, 32000-35000 must be open (these are required for file transfer over FTPES).
• 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 web server (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).

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

• A fully set up and working Emarsys Marketing Platform account. 

• Your Emarsys merchant ID (this can be found on the Management > Predict Data Sources page in your Emarsys account). 
• Your Emarsys API credentials (for ongoing contact data synchronization).
• Your Emarsys FTP folder and credentials (Smart Insight customers only). 

• The installation package (if you would like to download it, please contact Emarsys Support).
• Add the IP address 185.4.123.111 and the range 217.175.192.0/24 (these are required for opt-in synchronization back from Emarsys to Magento) to an allowlist.

In addition to these, you will need to create the following in your Emarsys account:

• An external event and campaign for each one of your mapped Magento events (see below).
• All the custom data fields that you need to map to Magento Customer fields.
• Custom fields of the type Short Text field (max. 60 characters) with the following names:
  • Magento Customer ID
  • Magento Subscriber ID

• In Github, navigate to the /app/ folder and then copy the app folder and package.xml file to the Magento project root, e.g.: /var/www/html/magento/.

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

• Log out of the Admin module and then log in again.
• You will now see a new entry in the System > Configuration menu: Emarsys Connect.

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

As part of the integration package, the Web Extend data collection scripts will be installed on your Magento site. These track a variety of browse and purchase activity (including guest checkouts). For more information on these JavaScript commands and where they are installed, see the Web Extend JavaScript API Reference.

To enable these scripts, open the System menu and go to Configuration > Emarsys Connect > Web Extend and make the following settings.

• Enable Web Extend - Set this to Yes.
• Merchant ID - Your Emarsys merchant ID (this can be found on the Management > Predict Data Sources page in your Emarsys account).
• Test Mode - If set to Yes, enables the testMode command of the JavaScript API reference, enabling you to test your account without affecting your data consistency. For a live integration this must be set to No.
• Identify Registered Logged In Customer By - The external key that will identify the contact in Emarsys. In most cases, we recommend using the Email Address. See Selecting the Key Identifier below.

• Item Unique Identification - The key that will match the items with your product data feed. 

• Use Base Currency - Only relevant if you have multiple Magento stores which map to a single Emarsys account. 
  • If Yes, all prices will be converted to your default store currency before being sent to Emarsys.
  • If No, all prices will be sent in the local store currency.
• Track Prices With Taxes - If you have stores in different regions with different levels of sales taxes, you can choose to omit these taxes and send only the net prices to Emarsys.
  • If Yes, all prices will be sent including tax.
  • If No, all prices will be sent excluding tax.
• Use Ajax Update - If you we unable to exclude the template path from caching as describe in the Magento 1 requirements above, this will help you prevent Web Extend data from being cached.
  • If Yes, no Web Extend data will be cached. 
  • If No, you run the risk of data caching, which could cause data inconsistencies in Emarsys.
• Use jQuery - If your Magento site supports jQuery,  this should be your preferred option, otherwise the Ajax Update method will be used.
  • If Yes, no Web Extend data will be cached. 
  • If No, you run the risk of data caching, which could cause data inconsistencies in Emarsys.

When you have made your settings and clicked Save Config, the Web Extend scripts will added to your site's themes and templates and data collection will begin immediately.

To configure the Emarsys API connection, open the System menu and go to Configuration > Emarsys Connect > Suite settings.

Current queue

This shows how many new customers have registered on the site since the last data sync. This counter is reset to zero after every sync (this can sometimes take a few minutes, depending on network connectivity).

API settings

• Enabled – Set this to Yes to enable the plugin.
• API Endpoint– This can be one of two values:
  • Default - This is the recommended option and uses the standard Emarsys API URL for your environment (e.g. https://suitexx.emarsys.net/api/v2).
  • Custom URL - This allows you to modify the default URL if required.
  • CDN - For customers located outside Europe (e.g. in APAC), you can use a CDN to improve performance. If you think this will be a better option for you, please consult Emarsys Support as we will have to configure some settings on our side.
• Custom API URL – If you have selected this option above, enter your modified default URL here. Make sure you do not include a trailing / at the end of the URL or you will receive an error when mapping fields.
• Debug – If set to Yes, this logs additional integration events, which is useful when you want to enable additional debugging logs to check specific activities (e.g. tracking the synchronization activity as we start exporting contacts and sales files after installation). 
• Plugin profiler – If set to Yes, this logs the time and resources consumed by the plugin for performing any specific action. See: About logging, below.
• Clean module log files - This deletes the latest log files. If you leave your logging options enabled after the integration has been successfully installed,  you should do this regularly (daily). 
• Download module log files – Downloads the log files for whichever logging options you have enabled.
• Cron service API ping – This must be Enabled, since it allows the extension to establish that the connection is active and logs the errors when it is not (if Debug is set to Yes). Loss of connection will cause the API calls to queue, limiting the real-time features of the integration. This ping will will enable you to see when and why the connection was lost.
• Suite API Username and Suite API Password – Enter your Emarsys API credentials (not your Emarsys account credentials). These should have been provided during onboarding by Emarsys Support.
  Your Emarsys Account Owner can also create new API users and passwords on the Management > Security Settings page, see: API users.
• Click Save Config to save your settings.
• Click Test connection to check that you have entered these credentials correctly. The Test connection button should turn green to signal that the connection has been established between Magento and your Emarsys Marketing Platform account.

We recommend to keep both the logging options set to Yes until you have fully set up and tested this integration. This will help you (and us) identify the causes of any issues that arise.

The Plugin Profiler monitors the time and memory allocation of an application loading cycle at specific intervals. By enabling the Plugin Profiler setting, we can collect information regarding the overall time and resources consumed by the plugin for performing any specific action.

When this setting is enabled, it logs the related data into a log file called emarsys-profiler.log that can be downloaded via the Download module log files button and link.

The log file contains following data:

• Count - The number of times a particular code was used/executed.
• realmem and realmem_start - This column show the amount of memory allocated to PHP. It is a mix of the core PHP memory_get_usage() function without the TRUE parameter passed to it, minus timer values.
• emalloc and emalloc_start - This column shows additional PHP values that help to detect memory issues.

In some instances of Magento, enabling the Plugin Profiler can cause issues. If you receive such an error message from Magento, you can switch Plugin profiler to No if Debug is set to Yes. In this way, you will still be able to log some of the integration events, if not all of them.

Once installation is complete, you should turn both options to No.

From then on, should you feel that the integration is not performing as expected:

1. Clean the module log files
2. Enable both logging options
3. Debug the integration
4. Clean the log files again
5. Disable both logging options

An FTP connection is required for Smart Insight and Predict users. To configure this connection, open the System menu and go to Configuration > Emarsys Connect > Smart Insight > FTP Settings.

• Hostname, Username and Password - Enter your credentials as provided by Emarsys Support. If you are a Predict customer who does not use Smart Insight, you can enter your own server details here instead.
• Directory - If you have created a sub-directory on the server to separate the manual exports from the regular scheduled exports, enter that folder name here (preceded by /). 
• Use FTP over SSL(FTPS) - Set this to Yes (recommended).
• Use passive mode - Set this to Yes or No as per your IT requirements.
• Click Save Config when you are done.
• Click Test Connection to verify everything is working. Magento will display a message to confirm whether it is working or not.

Before you start, please read the following section to get an overview of how Magento and Emarsys handle contacts and their data.

Magento customers have a very complete customer profile offering a number of fields. Depending on your business model and needs, you will probably only be interested in a subset of these fields.

In contrast, Magento subscribers only have four fields available for synchronization:

• First name
• Last name
• Email address
• Subscription status (opt-in)

To map fields between Emarsys and Magento, go to System > Configuration > Emarsys Connect > Contact Synchronization and open the Field mapping section.

Click Update Schema to ensure that all your Emarsys fields are available in Magento.

Select each Magento field you want to synchronize, and the appropriate target field in the Emarsys application, and then use the right arrow to move the mapped pairs across.

Note: As well as the fields you select for mapping, three Magento fields are always included for synchronization by default:

• Opt-in
• Customer ID
• Subscriber ID

Once you have prepared your customer data as described above, you can perform the initial data load to import all your Magento customers and subscribers to Emarsys.

Open the System menu and go to Configuration > Emarsys Connect > Contact Synchronization and open the Synchronization Settings section.

• Enable Customers export and Enable Subscribers export - Set both of these to Yes to enable the two Export buttons (after you have made your export you should set them both back to No).
• Use Secure Notification URL - If your web shop URL starts with https://, this must be set to Yes. This can be set to No for test or staging installations.
• Synchronization mode – Ignore this for now.
• Background Runtime – Ignore this for now.
• Notification secret key – This is the password required for the export notifications.
• Key Id – Select your unique identifier for the contacts.

When you are finished, you can make the initial data load by clicking the two Export buttons. You can have both exports running at the same time, but you should not start them together as they both need a few seconds to initiate the export. The exact time will depend on the size of your database but the system will inform you if you start the second export too quickly.

When you make the initial data load, the following will happen:

• For Magento customers, all the fields defined in the Field Mapping above will be synced, along with the Opt-in and Customer ID fields.
• For Magento subscribers, only the First name, Last name, Email address, Opt-in and Subscriber ID are synced.

The sync will start at the next multiple of five minutes. If the process looks stuck, you may need to flush the Magento 1 cache, see: Troubleshooting.

Once the initial data load has been performed, you will need to define the settings for the ongoing synchronization of new data. 

In Synchronization settings section, make the following settings:

• Enable Customers export and Enable Subscribers export – Set these back to No to disable the two Export buttons, preventing an accidental sync of your entire contact database.
• Synchronization mode – Select Realtime-failsafe or Background only as per your requirements (see below).
• Background Runtime – Set the time of day for the daily data synchronization.

Click Save Config to save your settings. The next export take place at the scheduled time.

• From Magento to Emarsys

The Magento contact database is considered the Master database for contact details, and all values synchronized for the mapped fields will overwrite the existing values in the Emarsys application. For Magento customers, new contacts will be exported will the same fields as per the initial export. For Magento subscribers, only the Email address and Opt-in fields are exported, since the First name and Last name fields cannot be modified in Magento.

• From Emarsys to Magento

Once a day, at the specified Background runtime, Emarsys also checks if the Opt-in field of any Magento contacts has been modified. If so, this change is synchronized back to Magento.

However, it is strongly recommended not to change the opt-in status in the Emarsys application as it will take up to 24 hours to update to Magento, during which time the contact could possibly receive further (transactional) emails. Best practices would be to update it in Magento, so the Emarsys contact will be updated as specified in the synchronization mode.

You should map your Magento product attributes fields to the correct Emarsys product data fields, ensuring that your product data file has the correct columns and field types to conform to our standards. For more information, please see: Preparing your product data file.

To map the product attributes, go to Emarsys > Product Attribute Mapping.

Here you map the columns of the product data feed. For each Magento attribute, select the appropriate Emarsys field.

• Add Emarsys Attribute - If you are missing an Emarsys field, you can create the column header here. The field name will automatically have the prefix c_ added.

• Update Schema - Imports all the available Emarsys fields to Magento.
• Recommended Mapping - Auto-maps fields based on their names. This can be a helpful time-saver if you have a lot of fields.

When you are finished, click Save Mapping to save your settings.

Now go to System > Configuration > Emarsys Connect > Full Catalog Export. Here you configure your product data feed and select the product types to include in it.

• Enable Full Catalog Export - Set this to Yes. It does not matter if a scheduled export occurs before you have made your initial load as the entire product data file is always overwritten every time.
• Include Disabled Products - Includes products that are no longer available for sale. In most cases this should be set to Yes, to ensure long-term data consistency.
• Include Product types - Here you select which product types to include. Refer to the Magento documentation for more details.
• Start time - Sets the time of day for the product feed (in HH:MM:SS).
• Frequency - Set this to Daily. The options Weekly or Monthly should be used only if you are sure that you do not change your product data file more frequently than this.

When you click Save Config the product data file will be exported from Magento to Emarsys according to your defined schedule. With every export the entire file will be overwritten with the new one.

You should first make a bulk export of your historical sales data. To do this, go to System > Configuration > Emarsys Connect > Smart Insight.

If you have not already configured your FTP server as described in FTP Settings above, you should do so now.

• Smart Insight enabled – Set this to Yes.
• Export using email as identifier – Set this to Yes to ensure you do not create duplicate contacts. If No, the Customer ID will be used, which will disable the Export guest checkout orders option (since we do not have Customer IDs for guest checkouts, only email addresses). 
• Export guest checkout orders – Select Yes if you want to push anonymous order data to Smart Insight (this will be used to improve the product affinity and other metrics).
• Execute at - Set this to a fixed time that will not trigger an export before the initial data load is completed. For example, if the current time is 14:00, set it to 12:20. It is important that no scheduled feed takes place while the initial data load is being processed, otherwise you could end up with duplicate sales data in Emarsys.
• Include Bundle products - If set to Yes, this will include bundle products in the feed.
• Use Base Currency in Export - This must have the same value as Use base currency in the Web Extend data collection settings. This will ensure that both the data collected by Web Extend and the data loaded by Smart Insight are consistent in terms of currency and language.
• Calculate bundle price - Set to Yes if you want to include the total bundle price in the data file.

When you have made your settings, click Generate Now to export the last two years of order data and pass that to Emarsys. You should verify that the .csv file created contains all the orders of last the two years with all the required fields (product id, price, quantity, etc.) correctly filled.

The Emarsys web collection scripts will pass most of your sales data events to Emarsys, but there are some events that these scripts do not track, for example shipping information, expected delivery dates or payment methods with third-party providers such as PayPal.

You can pass this information to Emarsys and use it for Smart Insight segmentation or as part of an automated program by including these statuses in the export. 

On the same page, in the Order Statuses section, select the statuses for which orders should be exported. You can make multiple selection by holding down the CTRL key.

When you click Save Config, Magento will include orders which have transitioned to one of the selected statuses in the sales data synchronization feed.

When you have made your initial export, reset the Execute at field to the time of day or frequency that you require, and click Save Config.

Magento will export all the orders which have transitioned to one of the selected statuses since the last export, at the appointed time.

If you set the field Include Bundle products to No, your export file will contain only the product data:

If you set the field to Yes, then the Bundles will be included as an extra line in addition to the product data:

If you set the field Calculate the Bundle price to No, the price for each item in the Bundle is listed independently and the price for the Bundle is set to zero:

If you set this field to Yes, the Bundle price will display the total for all items in the Bundle and the items themselves will have their price set to zero:

For every Magento event you want to map, you will need to create the following in your Emarsys account:

• One external event per Magento event.
• One campaign per external event. These should be created directly in the campaign creation interface for that channel (Triggered Email, SMS, Mobile Engage, etc.). If you intend to follow up the initial message with further actions, you can include this in an Interactions program, but this is typically not the case for transactional messages.
• A list of personalization placeholders that you can map to the Magento variables for each event (see below).

When you have prepared your campaigns in Emarsys, open the Emarsys Email menu.

Since your Magento contacts are synchronized with Emarsys, you can of course include in your email content all the regular personalization variables available in the Emarsys application, including conditional content and section targeting. However, there may be important information about the event that triggers the email that is only available in Magento (for example, the URL of the confirmation link in a confirmation email).

To add this Magento content to your Emarsys email, you must add special Magento placeholders to the email content.

In your Emarsys account, add the placeholders to the email content, with a double-% either side (for example, the variable first_name should be written in the email content as %%first_name%%).

These Emarsys placeholders can be any text string and are only used to make sure the right values in the JSON object are added to the right place in the email. They do not reference the Emarsys database and do not have to be the string IDs of Emarsys fields. We recommend that you name them as closely as possible to the Magento variables you will match them to.

Once you know which placeholders are being used in which emails, and you have mapped the corresponding events, you need to map the Magento variables with the Emarsys placeholders. You will need to do this for each Magento event.

• On the Magento Emarsys Event Mapping page, click Placeholders next to the event in question.

• For each Magento variable, add the corresponding Emarsys placeholder.
• Click Save Mapping.

It is a good idea to check the JSON payload that will be transmitted to Emarsys, to make sure all the placeholders have been correctly mapped. Click JSON Request next to each event to display the object; now you can check the placeholders and see exactly what data is being passed to Emarsys without having to refer to the logs.

Once you have mapped your events and fields, check that your email campaigns are correctly configured in Emarsys.

• In your Emarsys account, for each campaign open the Email Settings. Make sure that the Recipient source is set to Generated through an event and then select the appropriate external event.

• In the Campaign Scheduling, make sure this is set to launch Exactly on event.

In your Magento account, go to System Configuration and from the left menu select Customer Configuration.

• For each of the available options you can define a transactional email. In this example we will look at Create New Account Options, which has three welcome emails as part of a double opt-in registration process.

• Under Default Welcome Emails, select the template you want to use and click Save Config.
• Repeat this step for the Confirmation Link Email and the Welcome Email.

Now the Emarsys email campaigns associated with the template will trigger every time the corresponding trigger is activated in Magento.

When you have finished your mapping, go to System > Configuration > Emarsys Connect > Transactional Mail setup and enable this functionality.

• In the Enable Emarsys transactional mails drop-down, select Yes.
• Click Save Config to save the settings.

From this point on, all the mapped events in Magento will trigger the corresponding external event in Emarsys. You can then link these events to whichever action in Emarsys that you want (e.g. launch email, SMS or Mobile Engage campaigns).

Once you have made your initial data loads and set up the schedule for regular synchronization of new data, you can take advantage of the data monitoring tools that Emarsys provides to make sure that the data flow is working properly.

These tools validate every data import into Emarsys. If an issue is identified, this is highlighted and a suggested solution offered.

The tools are located in your Emarsys application on the Predict Data Sources page.

If there is a new version of this integration, you will be informed via the Magento notifications. If you would like to downoad the latest version, please contact Emarsys Support. You then need to follow the steps described above in Installing the Emarsys module. All your settings and configurations will not be affected.

If you create new assets (fields, external events, etc.) in Emarsys, you will be informed via the Magento notifications. 

You can update your Magento interface at any time by clicking Update Schema on any of the pages where it appears.

When clicking the Field mapping drop-down on the Contacts synchronization page, if you see the message No fields available in Emarsys Suite for this website (please check API configuration) this means you have a trailing slash (/) at the end of your custom API URL. You should remove the trailing slash.

When you try to manually synchronize contact data fields and the export gets stuck, you should first check that your cron settings are ok. If they look correct, then flush the Magento 1 cache entirely.

When testing the integration (or after), you find that data is being attributed to the wrong session or contact, it may be that your Web Extend is being cached. You should open the Web Extend settings (System menu > Configuration > Emarsys Connect > Web Extend) and make sure that the Use Ajax Update or Use jQuery options are enabled, as appropriate.