Magento 1 integration

Note:  This topic is for administrators and developers with administration access rights in Episerver Campaign.

If you are using Magento 1 as e-commerce platform, you can integrate this with Episerver Campaign and manage customer data via Episerver's email marketing platform. The entire recipient management, from registration to the opt-in process through to updating of the recipient data and unsubscriptions, is done in Episerver Campaign. The Magento 1 integration allows for sending of transactional mailsA transactional mail is an email triggered by a recipient action (such as an order or purchase) or event (such as an anniversary). It is sent out subsequent to the event. and regular email campaigns via Episerver's server. You can also import product data into Episerver Campaign to display products in remarketing campaigns and recommendations.

Supported versions

Magento CE Magento EE
1.7 1.12
1.8 1.13
1.9 1.14

Installing the Magento 1 integration

The installation should be carried out by an administrator or Dev operator. For the integration, you need to install the Episerver Campaign extension in Magento. You need at least PHP 5.3 and phpseclib 0.3.6 on your Magento server (the official distribution from Version 0.3.6.). You can install this via PEAR: http://phpseclib.sourceforge.net/pear.htm.

Install the Episerver Campaign extension via the file system. You need an FTP connection to your server to transfer the installation package.

  1. Unpack the ZIP archive containing the installation onto your local PC.
  2. Establish an FTP connection to your Magento server.
  3. Copy the app folder to your Magento server.

Warning:  Test the installation and configuration first in a non-production (live) environment.

Configuring in Episerver Campaign

When setting up your Episerver Campaign extension, certain data should be available for the configuration. If you are operating several store views, stores and/or websites with a Magento installation, see Configuring multiple-clients.

Log in to your Episerver Campaign client and select the required clientThe working environment of Episerver Campaign, a client is a stand-alone and closed system that serves to organize your mailings. Campaign users can use one or more clients for your scenario.. Copy the following IDs and codes:

  • Client ID. Open the start menu and select Administration > API overview > SOAP API tab.
  • Authorization code. Open the start menu and select Administration > API overview > Recipient lists tab. Select the required recipient list and click Manage authorization codes. If no code is set up for the selected list, click Create authorization code.
  • Opt-in ID. Open the start menu and select Administration > API overview > Opt-in processes tab. Select the opt-in process that you want to use for the Magento store (see following section).
  • Opt-in link. Edit the system mailing you are using for the registration confirmation (opt-in) of customers from your Magento shop and replace the default field function for the opt-in link: {Double-Opt-In-Link} with the parameterized string: {Double-Opt-In-Link}?id={bmecssid}&code={bmecsscc}

Customer support will further configure in Episerver Campaign. Episerver needs the following information from your Magento shop:

  • The IP address of your Magento shop. This is stored in your client.
  • Forwarding email address. Should be an administrative email address to where ARF reports, bounces, spam, auto-replies and responses are sent.
  • The transmission domain of your shop. Must be delegated to Episerver and stored in your client as a transmission domain.

Importing recipient data

When setting up the integration, customer support sets up a recipient list with the standard fields from Magento in your Episerver Campaign client. The recipient list contains the following fields:

Field Type Description
email String Email address
salutation String User's title
firstname String First name
lastname String Last name
language String ISO code for the language from the StoreView via which the user has registered.
street String Street address
zip String Postcode or international ZIP code
city String City
state String State
country String Country

Apart from the mandatory email address and automatic language, fields are optional. To receive the data, create an expanded subscription form or an edit-profile form and integrate this into your shop pages.

Adding and exporting additional recipient data fields

In Magento, you can add recipient data called customer attributes to save with the default recipient data and export the data to Episerver Campaign. Customer attributes let you adapt your sales approach. You can use customer attributes like any other default value to personalize newsletters or to create highly customized customer segments.

Note:  The function to add customer attributes (steps 1-7) is not available in Magento Community Edition. Instead, there are third-party extensions available that add this functionality to the browser.

  1. Select Customers > Attributes > Manage Customer Attributes.
  2. Click Add New Attribute and define first the Attribute Properties.
  3. In the field Attribute Code, enter a unique internal name.
  4. In the Input Type drop-down list, select the desired data type.

    Note:  The export to Episerver Campaign only supports the field types Text Field, Text Area, Date and Yes/No.

  5. Define the further settings for the customer attribute.
  6. Click the Manage Label/Options tab and define the titles for the customer attribute, as you want them to be displayed in the admin back end and in the different languages of your shop. You must enter a title in the Admin field. If you leave the other fields empty, the Admin value is used for them as a default value.
  7. Click Save Attribute.
  8. Select System > Configuration > optivo broadmail.
  9. Open the HTTP-API panel and, in the the Customer Attributes to optivo list, select customer attributes you want to export to Episerver Campaign. Use CTRL to select multiple attributes.
  10. Click Save Config. The selected attributes are sent to Episerver Campaign at every HTTP API request.
  11. To process the sent data, communicate the field names and types of the customer attributes to customer support who configure the recipient lists in your Episerver Campaign client. When this is done, you can access the customer attributes in Episerver Campaign as a recipient field and can be used to create personalized content or target groupsA subset of recipients defined by rules and conditions and a logic relationship between them. For example, all recipients in the United Kingdom. based on these data.

Importing product data into a template

If you are configuring the product data export in Magento, you need a correspondingly equipped mailing template with a content interface to integrate the imported data into your mailings (for example in the form of recommendations or cross and upselling offers).

Note:  An individual template and the content interface are additional functions, subject to a charge, and are not part of the standard scope of supply for the Magento integration. For more information, contact customer support.

The Magento integration transfers the following product data to Episerver Campaign:

Field Type Description
id Long Product ID
name String Product title
category String Product category (final path)
description String Product description
short_description String Short description of the product
sku String Item number
product_url String URL to product landing page
price String Product price
special_price String Special price
special_from_date String Offer valid from
special_to_date String Special valid until
base_image String Product image
small_image String Downsized product image
thumbnail String Thumbnail image

Configuring in Magento

Open the system configuration tool in Magento, then, in the optivo menu, select the menu item optivo broadmail.

Note:  If a 404 error message (Page not found) appears, log out and log back in again.

General

Open the General area and complete the fields using the data that you copied from your Episerver Campaign client in the previous step:

Image: General configuration

  • Client ID. Client ID
  • Client Name. Optionally, enter the name of your Episerver Campaign client. This is used for orientation purposes, because the client ID can be difficult to remember.
  • Authorization Code. Authorization code
  • Opt-in ID. Opt-in ID

HTTP API

Open the HTTP-API area, enter the confirmation page URL for the double opt-inA practice in which a recipient consents to receiving email from the sender before any promotional email is sent. Recipients receive an email with a double opt-in link, which they must click to confirm their interest., and enter the confirmation page URLUniform Resource Locator. Also known as a web address such as http://world.episerver.com. for the unsubscription process in the second field.

Image: HTTP API area

Note:  The CMS page for the confirmation (Newsletter Confirm Page) or unsubscription (Newsletter Unsubscribe Page) can also be a CMS page created specially for this case.

SMTP API

Open the SMTP-API area and select whether you want to use the Episerver Campaign SMTP-API to send transaction mails. If you have select Yes here, enter the appropriate data in the following fields:

You also have to configure the Store Email Addresses in Magento. Open the Store Email Addresses menu item and, for the email addresses specified here, specify the domain you have delegated to Episerver during the SMTP setup.

Image: SMTP API area

FTP API

Open the FTP-API (Product Export) area and select whether you want to activate the product data export as per Episerver Campaign. If you select Yes here, fill in the following data fields with the corresponding information:

  • User name of the API user. This is provided by customer support.
  • Private key is encrypted. Select Yes from the list of options.
  • Private key. A key pair must be generated for data exchange via SFTP. See FTP access via SCP. Enter the private key here and inform Episerver of the public key.
  • Daily Export at. Select the time at which the daily product data export should take place.

    Image: FTP API area

Transactional mail address

In the System configuration, in the General menu, select the Store email addresses menu item. Open the mailing address that you want to use for your transactional mails via Episerver Campaign and enter a sender name and a sender address. The mailing address Sales representative is used as standard for transactional mails (for example, order confirmations). You can also configure a different mailing address (such as Adapted email 1). To store this mailing address for transactional mails, go to the Sales emails menu item in the Sales area, and select the corresponding mailing address for each sales campaign.

Image: Store email addresses

Note:  The transmission domain for the transactional mails must be delegated to Episerver and also be stored in your Episerver Campaign client as a transmission domain. The administration of the delegated domains is carried out by Episerver. Do not use your shop's main domain (example.com), but instead set up a subdomain for transactional mails (transactions.example.com) and delegate this subdomain.

Configuring transactional mails

You can configure and send a transactional mail for shop actions (orders, shipments, changes to customer and shipping data etc.) using Episerver Campaign. Adjust or set up corresponding templates in your Magento shop to do this. To create a template:

  1. Select SystemTransactional mails. Transactional mail templates are now displayed in a table.

    Note:  The Template Type column shows whether a template is configured for sending using the Magento shop (template type: HTML) or using Episerver Campaign (template type: optivo). You can change the template type so that templates, that are configured for sending via the Magento shop, are sent using Episerver Campaign. To do so, go to step 6.

  2. Click Insert New Template and from the Load default template area, select a template; empty templates cannot be created with Magento.
  3. Select an area schema from the list below. This schema determines the formatting of prices and dates.
  4. Click Load template to copy the content.
  5. In Template Information, enter a name for the template. This name is only used internally.
  6. Select the send with optivo broadmail check box. The two new fields optivo authcode and optivo bmmailid are now displayed.
  7. In optivo authcode, enter the authorization code for the recipient list that should be used for the transactional mail.

    1. Open the start menu and select Administration > API overview > Recipient lists.
    2. Select the required recipient list and click Manage authorization codes. A new window opens that displays a list of authorization codes for the selected recipient list.
    3. Copy the ID of the desired authorization code and enter it into the corresponding field in Magento. If no authorization code is currently available, click Create authorization code to generate a new code.

  8. In optivo bmmailid, enter the ID of the transactional mail in Episerver Campaign that you want to send with this transaction. The transactional mail must be set up in your Episerver Campaign client beforehand; see Transactional mails.
  9. Remove the HTML code from the Template content field.
  10. Enter recipient parameters to transfer with this template to Episerver Campaign using the following format:
    [parameter]={{var order.getOptivoBillingData('[variable]')}}

    Note:  Replace the string [parameter] with the name of the parameter in Episerver Campaign, and replace the string [variable] with the name of the variable used by Magento for the order object. For example, the line lastname={{var order.getOptivoBillingData('lastname')}} sends the surname of the recipient to Episerver Campaign. See Recipient and billing data for a list of recipient parameters.

  11. To add a parameter, start a new line.
  12. In addition to the variables provided by the function getOptivoBillingData, you can also send the shop-specific standard variables to Episerver Campaign to use them in the transactional email. Use the following format to do this:
    [parameter]=[variable]

    Note:  For each variable to be transferred, a corresponding field [parameter] is required in the target recipient list in Episerver Campaign. To insert a variable, click Insert Variable... and select the desired variable from the list. For example, the line: resetPassword={{htmlescape var=$customer.password}} sends a new password to the resetPassword field. This lets you send a transactional email to a recipient who has requested a new password.

  13. Likewise, enter order items that you want to send with this template to Episerver Campaign using the following format:
    orderPositions={{var order.getOptivoProducts('product_id','sku','name','price','qty_ordered)}}

    The five standard parameters (product ID, order number, name, price and quantity) are sent using the above format. If you do not require one of these parameters, you can remove it from the schema. If you want to send additional order parameters, you need to program a custom template. See Order details for a list of available order parameters and notes about templates.

    Note:  To carry out the programming, you need PHP knowledge and knowledge of the Magento object model.

  14. Click Save Template.

    Note:  The template is not activated when saved; that is, no transactional mails are sent using it.

    Image: New Email Template

  15. To activate the template and link it to an action, select SystemConfiguration.
  16. Locate the Sales section in the menu on the left and click Sales Emails. This displays actions that trigger a transactional mailA transactional mail is an email triggered by a recipient action (such as an order or purchase) or event (such as an anniversary). It is sent out subsequent to the event. to be sent.
  17. Open the panel for the desired action and select the desired template from the drop-down list (there is a template for each registered user and guest).

    Image: Sales section

Configuring multiple clients

Magento and Episerver Campaign provide the option of displaying multiple clients. Configure each individual client exactly as described in the configuration sections. Ensure that the clients are allocated correctly in Episerver Campaign and Magento. For each client, you need the client ID, client name, authorization code and opt-in ID. You can configure the confirmation pages for the opt-in and the unsubscription confirmation separately for each client, or you can use the same URLs for clients. The configuration for the SMTP-API and the FTP-API is global, and only needs to be carried out once.

Note:  To ensure that the clients are correctly allocated in Episerver Campaign and Magento, contact customer support to help you with the configuration.

Selecting a client in Magento

Clients are depicted in Magento via websites, stores and store views. See User Guide from Magento. The client selection section is at the top left-hand side of the configuration.

Image: Select client

Integrating the subscription form

Subscription to your newsletter is performed via the online registration form on your shop pages. The registration data is transferred to Episerver Campaign by means of an HTTP request. The standard template for the subscription form can be integrated onto any CMS page. Connection to Episerver Campaign is automatic when you are using the standard template. For standard newsletter subscriptions, only the email address is requested in the standard form. Magento also automatically transfers to Episerver Campaign the language in which new subscribers are registered in the Magento shop. You can use this information to send newsletters in different languages, for example.

To request additional recipient data, you need an extended subscription form. For this type of form, you need extended programming knowledge in HTML. See Importing recipient data for information about the data that you can request and process with the integration.

Integrating the subscription form on a CMS page

  1. In the top menu bar, go to the CMS menu item.
  2. In the Pages overview, go to the Manage content menu item.
  3. Select Add new page or edit an existing CMS page.
  4. In the Editor field, enter the following code fragment:
    {{block type="core/template" template="newsletter/subscribe.phtml"}}
  5. Click Save, or Publish.

    Image: CMS page in editor view

    Image: CMS page in front end view

Integrating the subscription form on category pages

  1. In the top menu bar, go to the Catalog menu item.
  2. In the Categories overview, go to the Manage categories menu item.
  3. Select the required category and a client (optional), and go to the Own design tab.
  4. Enter the following code fragment in the Editor field. Your subscription may have a different column layout and positioning, so adjust accordingly.
    <!-- Newsletter Box -->
    <reference name="right">
    <block type="newsletter/subscribe"
    name="right.newsletter"
    template="newsletter/subscribe.phtml"/>
    </reference>

    This code fragment integrates the subscription form into the right-hand layout column. If you want to integrate the newsletter into the left-hand column, replace the tag

    <reference name="right"> with the tag <reference name="left">

    and replace the attribute name="right.newsletter" with name="left.newsletter".

    Depending on the integration and to ensure a correct display on different end devices, you also may make changes in CSS.

  5. Click Save, or Publish.

    Image: Category page in editor view

    Image: Category page in front end view

Note:  Additional integration options
This section listed only the possible integration options from the back-end. The integration can also take place almost everywhere via the Magento template system. These changes require design experience and access to the Magento installation file system.

Error handling

Activating Magento logging

By default, general logs are written to the system.log file, and errors and exceptions to the exception.log file. You can change these file names at var/log/.

Activate writing log files in Magento for error analysis.

  1. Select System > Configuration.
  2. Click Progress and then Developer.

    Image: Log settings

  3. Set the Enabled option to Yes.

Activating developer module

To analyze errors and ensure that effective logging is taking place, activate the developer mode in Magento via .htaccess or directly in the index.php of Magento:

Image: Entering developer mode

The log file for the Episerver Campaign extension is located in the /var/log/ directory within the Magento installation. The name of the log file is optivo_broadmail.log.

Conflicts with other Magento extensions

There may be conflicts between the Episerver Campaign extension and other extensions if these extend the same Magento core functions. In particular, conflicts may occur in connection with other Magento extensions that also provide newsletter, SMTP or similar functions to the Episerver Campaign extension.

Furthermore, local code adjustments in the code pool local can lead to additional by-effects or side effects in the interplay.

During error analysis, pay attention to which extensions and in-house developments are integrated in the Magento installation.

Warning:  To prevent these types of conflicts and integration malfunctions, first install your Magento platform with the Episerver Campaign extension and other extensions being used onto a test system. Then, reproduce a range of different test scenarios there before carrying out the installation in a production environment.