OXID integration

Note:  Available only in Germany, Austria, and Switzerland.

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

If you are using OXID eShop 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 OXID eShop 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.

Supported versions

Community Edition Professional Edition Enterprise Edition
not supported 4.7 5.0
4.8 5.1
4.9 5.2
4.10 5.3

Client setup

The OXID integration in Episerver Campaign client is set up by customer support using the following information:

  • Recipient data. The client's recipient lists are adjusted so they contain one column per data field; see Newsletter registration.
  • Product data. Your mailing template is configured so that this data is available in the product paragraphs; see Regular campaign emails.
  • SSH key. Create a key pair for secure data transfer, and send the public key and key fingerprint to Episerver; see Transferring files through SCP.
  • Sending domain. To send emails via the server, the sending domain must be delegated to Episerver.

Note:  To use multiple versions for example different shops with the integration, will need multiple clients or sub-clients, contact customer support.

Configuring SMTP

Customer support also configures the SMTP server in your client for sending system emails from the OXID shop. You will receive an SMTP user and password to be stored in the basic settings of your OXID shop. Specify the server smtpapi.campaign.episerver.net as the SMTP server.

In the system mailing used for registration confirmation (opt-in) for customers from your OXID shop, replace the default field function {Double-Opt-In-Link} with the following parameterized string:

{Double-Opt-In-Link}?cl=newsletter&fnc=addme&lang=${user.data.oxlangid}&confirm=
${user.data.confcode}&uid=${user.data.oxid}

Installing the OXID shop integration

You will receive an installation file for the OXID integration. Install this file on the shop server using FTP access.

  1. Save the installation package to your PC.
  2. Unpack the installation package.
  3. Establish an FTP connection to your OXID shop server.
  4. Move the unpacked installation package to the root directory of your OXID shop.
  5. To make additional image sizes and formats available for product images in mailings, activate the image generation of additional image sizes within OXID. In the http/modules directory of the OXID server, search for the functions.php file. Open this file in an editor, and add the following code to the end of the file:
    // optivo broadmail functions
    include_once realpath( dirname( __FILE__ ) . '/optivo/functions.php');

    Note:  If you are using an older version as OXID eShop Professional Edition 4.10 or OXID eShop Enterprise Edition 5.3, see Configuring older versions.

  6. Activate the Episerver module in your shop's administration area by selecting Extensions > Modulesoptivo and click Activate at the bottom.

    Note:  If you are using the Enterprise Edition (EE) of OXID and want to work with multiple clients, you need to activate the Episerver Campaign module for each shop client individually.

    Image: Activate the module

Configuring the OXID shop

  1. Select optivo broadmail > Settings and select your shop. Or, in the OXID EE version, select the shop that you want to configure.

    Image: OXID Settings

  2. Enter the authorization code in the Main tab. This code is required for authentication when transferring registration data to Episerver Campaign. You can find the code in the Episerver Campaign client in the Administration > API overview > Recipient lists, then select the recipient list where the registration data is to be transferred, and click Manage authorisation codes.
  3. Enter the opt-in ID in the Main tab. You can find the opt-in ID in your Episerver Campaign client in the Administration > API overview > Opt-in processes tab. Copy the ID of the required opt-in mailing from the list and add this to OXID in the Opt-in ID field.

    Image: Main tab options

  4. Go to Item export and select the language of the exported file. The Export item including variants option only affects the ad-hoc export, and is not required for the configuration. Enter the additional image sizes for the export at the bottom of the panel.

    Activate the option to generate images in the specified sizes during export. If you are using standard image sizes, you do not need to make any modifications.

    Click Generate and upload export file to start an ad-hoc export. Also configure the automatic time-controlled export for data transfer to Episerver Campaign, to transfer the current data at defined intervals.

    Image: Article export tab

  5. Go to Log export to configure and download the log file for the newsletter subscriptions from the OXID shop. The log file contains recipients whose data cannot be transferred to Episerver Campaign, such as when a server connection cannot be established. Enter the export period. To include data that was already exported, activate the Include already exported entries option.

    Image: Log export tab

  6. Click Start export to start the log-file generation. When the data is exported successfully, a confirmation message is displayed, along with a link to download the export file (CSV). Each data set in the log file contains a column with a code that indicates the recipient action:
    • C. Recipient changed
    • U. Recipient unsubscribed
    • S. New recipient.

    You also can set up an automatic time-controlled export for the log file. However, the recipient data is sent to the configured email address in unencrypted format.

    Warning:  Do not use the automatic time-controlled export for the log file. The manually initiated ad-hoc export is defined as a standard fallback for the integration, to keep subscribers and unsubscribers that could not be automatically exported up to date.

  7. Go to sFTP configuration and enter Username, SSH key, client Ids, and client name. The user name is provided by customer support. The private key of a previously generated key pair must be stored in the SSH key field, see Transferring files through SCP.

    Image: sFTP tab

  8. Configure the sending of system emails, for example order confirmations, via the SMTP server. Select Master data > Basic settings > your shop. Or, in the Oxid EE version, select the shop that you want to configure. In the Master tab, enter the SMTP server, the SMTP user and SMTP password. The standard SMTP server is: smtpapi.campaign.episerver.net. The user name and password are provided by customer support.

Transmitting product data

The automatic time-controlled export transmits product data from your OXID shop to Episerver Campaign at defined intervals.

  1. Establish an FTP connection to your OXID shop server.
  2. Set up a Cron Job on the server that accesses the file optivo_artikel_export_cron.php at selected intervals, such as once per day. This file is included in the installation package. The Cron Jobs are called up based on the following scheme:
    sudo php [oxidRoot]/http/modules/optivo/optivo_article_export_cron.php [shopId] [exportVariants]

    Replace the term [oxidRoot] with the base URL of your OXID shop, and the term [shopId] with the ID of your shop. Set the term [exportVariants] to a value of 0 or 1 to regulate whether you want to export items including the variants (in this case set the value to 1) or only independent items and main items of a variant (in this case set the value to 0).

For OXID-EE implementations

If your shop is multi-client and you want to do an export for each client, you need to call the file optivo_artikel_export_cron.php for each shop. Enter the corresponding shop ID for each shop. In the following example, three shops with IDs 1, 2 and 3 are configured. The base URL in this example is /var/www/oxid. For the shop with ID 1, the export for items including variants is configured. For the other shops only the export of independent and main items is configured.

sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 67 1
sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 68 0
sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 69 0

Managing recipients

Registering a newsletter

Newsletter registration is done via the online registration form page on your shop. Registration data is transferred to Episerver Campaign through an HTTP request. The following data fields are transmitted with each data set:

Name Data type Description Mandatory field
Email String Recipient's email address – This field is also the recipient's unique ID
Title String Title (Mr/Ms) of the recipient
First name String Recipient's first name
Surname String Recipient's surname
Language String Language of the shop via which the customer has registered (transferred automatically)
custom String Any additional fields
oxlangid String Oxid-internal ID for the correct forwarding of the recipient following opt-in or unsubscription (transferred automatically)
oxid String Oxid-internal shop customer ID (transferred automatically)
confcode String OXID-internal test number (transferred automatically)

Opting in

Before receiving a newsletter, a new recipient must click the activation link in the double-opt-in email, to confirm the email registration. With the OXID integration, you can use an extended double-opt-in process from Episerver Campaign. The opt-in status is stored with a time stamp in the recipient list in Episerver Campaign and in the OXID database.

Unsubscribing

The unsubscribe from newsletter option service is prescribed by the regulator. An Unsubscribe link must be included in sent emails. The unsubscription process is controlled via Episerver Campaign. Alternatively, recipients can be unsubscribed in OXID. The status of your recipients is synchronized between OXID and Episerver Campaign.

Changing recipient data

Newsletter recipients can change their data via an online form. Changed data is automatically imported into the recipient list, so that this contains updated information.

Sending mailings

Sending system emails

The OXID integration lets you send orders, shipping confirmations, and invoices via the transmission structure of Episerver Campaign. You can also create transaction emails in OXID.

Sending regular campaign emails

For regular transmissions, Episerver Campaign contains recipient data and the product data from your OXID shop system. This lets you create regular newsletters, remarketing campaigns, and recommendations for customers and newsletter recipients. You can personalize the mailings using the recipient data, and enhance them with product data, recommendations, and cross-selling and upselling offers. The OXID integration transfers the following product data to Episerver Campaign:

Fieldname Description
id Oxid-internal product ID
Name Product name
category Main product category
isVariant This field indicates whether the item is a variant of a product (such as a different color)
oxparentid In the case of variants (see above), the ID of the associated product is specified here
oxartnum Item number in the OXID shop
oxean EAN (international item number) of the product
oxshortdesc Short description of the product
oxprice Product price
oxthumb URL to a thumbnail
oxicon URL to icon image
oxpic1 URL to original image
oxvarminprice For main items, this field contains the lowest price
(such as shirt in different sizes, from 29.99 €)
oxvarmaxprice For main items, this field contains the highest price
(such as T-shirt, from 19.99 to 29.99 €)
URL Absolute URL for the product's landing page
oxlongdesc Product description
image1...5 Absolute URLs for the user-defined image sizes according to the settings in the OXID integration (see also the sections Installation and Configuration)

Configuring older versions

To ensure correct functionality 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. when using an earlier version of OXID eShop Professional Edition 4.10 or OXID eShop Enterprise Edition 5.3, you must comment out the following lines of code in the class.phpmailer.php file:

if($this->Sender == '')
 
{ $result .= $this->HeaderLine('Return-Path', trim($this->From)); }
else
{ $result .= $this->HeaderLine('Return-Path', trim($this->Sender)); }

To comment out lines 967-971, add the following characters before and after the code then save the file:

/*
if($this->Sender == '')
 
{ $result .= $this->HeaderLine('Return-Path', trim($this->From)); }
else
{ $result .= $this->HeaderLine('Return-Path', trim($this->Sender)); }
*/