OXID eCommerce integration

Connect your OXID eShop system Episerver Campaign and manage your shop's customer data via our omnichannel marketing platform1. The entire recipient management is carried out in Episerver Campaign, from registration to the opt-in process right through to updating of the recipient data and unsubscriptions. The integration allows for the quick and secure sending of high volumes of transactional emailsA transactional email is 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 mailings via our servers. You can also import product data into Episerver Campaign and insert this into a mailing template. The integration provides you with the benefits of a sound infrastructure, a good reputation and the resulting very high delivery rates of Episerver Campaign.

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

Installation in your Episerver Campaign client

The OXID integration in your Episerver Campaign client will be set up for you by customer support. To do this, we need the following information from you:

  • What recipient data is requested on registration?
    Your client's recipient lists are also adjusted, the recipient list contains one column per data field. The standard configuration is described in the Newsletter registration section.
  • What product data is transferred to Episerver Campaign ?
    Your mailing template is configured accordingly, so that this data is available in the product paragraphs. The standard configuration is described in the Regular campaign emails section.
  • The SSH key
    Create a key pair for secure data transfer as in this documentation and send the public key and the key fingerprint separately to Episerver.
  • The sending domain
    To make it possible to send emails via the server, the sending domain must be delegated to Episerver.

If you wish to use several different versions (e.g., different shops) with the integration, you will need several clients or sub-clients. If you have any questions, contact customer support.

The customer support team also configures the SMTP server in your client for sending system emails from the OXID shop. The customer support team will send you the following information, which you will need to store in your OXID shop:

  • SMTP user
  • SMTP password

Store this data in the basic settings of your OXID shop. Specify the server smtpapi.campaign.episerver.net as the SMTP server.

In the system mailing that you are using for the 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}

Installation in your OXID shop

You will receive an installation file from customer support for the installation of the OXID integration into your online shop. You need to install this file on your shop's server. To do so, you need an FTP access for your shop server. Proceed as follows:

  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. If you want to use the integration to make available additional image sizes and formats for product images to send in mailings, the image generation of additional image sizes within OXID must be activated. 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');
  6. If you are using OXID eShop Professional Edition 4.10 or OXID eShop Enterprise Edition 5.3, you can skip this step and continue with the next step. If you are using an older version, configure this as described in Appendix A – Configuration of older versions.
  7. Activate the module in your shop's administration area. To do so, in your OXID shop's administration area, click Extensions and Modules. Select optivo and click Activate at the bottom.

    If you are using the Enterprise Edition of OXID and wish to work with several Episerver Campaign clients, you need to activate the Episerver Campaign module for each shop client individually.

Configuration

To configure your OXID shop for automatic data exchange with Episerver Campaign, perform the following steps:

  1. In the left-hand navigation list, click optivo broadmail and Settings and then select your shop. Or, in the OXID EE version, select the shop that you wish to configure.
  2. Enter the authorization code in the Main tab.

    The authorization code is required for authentication purposes when transferring registration data to Episerver Campaign. You can find the code in your Episerver Campaign client in the Administration menu, under the API overview menu item. Switch to the Recipient lists tab. Select the recipient list where the registration data is to be transferred, and then click Manage authorisation codes.

  3. Enter the opt-in ID in the Master tab.

    You can find the opt-in ID in your Episerver Campaign client in the Administration menu, under the API overview menu item. Here, switch to the 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.

  4. Go to the Item export tab 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.

    The option of generating additional image sizes must be activated on the server to generate images in the specified sizes during export. For more information, read the installation instructions at the beginning of this documentation. If you are using standard image sizes, you do not need to make any configurations here.

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

  5. Go to the Log export tab to configure and download the log file for the newsletter subscriptions from the OXID shop. The log file contains all recipients whose data cannot be transferred to Episerver Campaign , e.g. because it was not possible to establish a connection to the server. First, enter the export period. If you wish to include all data, including the data that has already been exported, activate the Include already exported entries option.
  6. To start the log-file generation, click Start export.

    Once the data has been exported successfully, a confirmation message will be 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.

    There is also the option of setting up an automatic time-controlled export for the log file. However, in this case, the recipient data is sent to the configured email address in unencrypted format. We therefore expressly advise against using 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 to in Episerver Campaign up to date.

  7. Go to the sFTP configuration tab and enter the user name, the SSH key, the client Ids and the client name. The user name will be provided by customer support. The private key of a previously generated key pair must be stored in the SSH key field. Information on how to generate a key pair and what information you need to send to Episerver can be found in our FTP documentation.
  8. Configure the sending of system emails (e.g., order confirmations) via the SMTP server. In the left-hand navigation list, click Master data and Basic settings and then select your shop. Or, in the Oxid EE version, select the shop that you wish to configure. In the Master tab on the right-hand side, enter the SMTP server, the SMTP user and the SMTP password. The standard SMTP server is: smtpapi.campaign.episerver.net. The user name and password will be provided by customer support.

Automatic time-controlled export

The automatic time-controlled export transmits product data from your OXID shop to Episerver Campaign at defined intervals. You can configure the automatic time-controlled export as follows:

  1. Establish an FTP connection to your OXID shop server.
  2. Set up a cronjob on the server that accesses the file optivo_artikel_export_cron.php at selected intervals (e.g. once per day). This file is included in the installation package. The cronjobs 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 all 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).

Note for users of OXID-EE

If your shop is a multi-client and you want to carry out an export for each client, then you will need to call up 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 have been configured. The base URL in this example is /var/www/oxid. For the shop with ID 1, the item export for all items including variants is configured; for the other shops, only the export of independent items 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

Recipient management

Newsletter registration

Registration for your newsletter is performed via the online registration form on your shop page as usual. The registration data is transferred to Episerver Campaign by means of 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)

Opt-in process

Before a newly registered recipient receives a newsletter, he/she must click on the activation link in the double-opt-in email to confirm that he or she has registered with this email address. With the OXID integration, 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 as well as in the OXID database. For more information, refer to Installation.

Unsubscribing

The option of unsubscribing from a newsletter service is prescribed by the regulator. An 'Unsubscribe' link must be included in all sent emails. The unsubscription process is controlled via Episerver Campaign. Alternatively, recipients can also 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 at any time via an online form. The changed data is automatically imported into the recipient list, so that this list always contains the most up-to-date data.

Sending mailings

System emails

The OXID integration allows you to send orders, shipping confirmations, invoices etc. via the transmission structure of Episerver Campaign. You can create your transaction emails in your OXID system as usual. Emails are delivered via the server, which guarantees high delivery rates and real-time sending even for high-volume transmissions.

Regular campaign email

For regular transmissions, Episerver Campaign contains all recipient data as well as the product data from your OXID shop system. This allows you to create regular newsletters, re-marketing campaigns, recommendations etc. for your customers and newsletter recipients. The mailings can be personalized using the recipient data, and can be enhanced with product data, recommendations as well as cross 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 (e.g. 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
(e.g.: shirt in different sizes, from 29.99 €)
oxvarmaxprice For main items, this field contains the highest price
(e.g.: 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)

1 This feature is only available in Germany, Austria and Switzerland.

back to top Episerver image




Episerver | Updated: 2019-02-19 | Send feedback to us