Loading...

Last updated: Sep 24 2018

Area: Episerver Commerce, Episerver Campaign Applies to versions: Commerce 12.9.0 and up

Commerce-Campaign integration

The Episerver.Campaign.Commerce NuGet package integrates Commerce with Episerver Campaign (Reach). To achieve this integration, a mechanism periodically transfers the latest product data from Commerce to Campaign in a CSV format. (See Use CSV.) To carry out this transfer, Episerver.Campaign.Commerce provides a scheduled job, Export Product Data To Campaign. At regular intervals, the job collects Commerce product data and exports it to a CSV file in a specified format. The file is automatically transferred to an Episerver server. From there, it is imported to the Campaign system.

Integration details

Prerequisite

  • A key pair, as explained in FTP access via SCP (Windows). That article includes the step  "Transmit keys to Episerver," where you send the public key and the secret key (also known as a fingerprint) to Episerver. Then, Episerver grants access to the system for that key. When setting up the Commerce-Campaign integration, you convert that key to an SSH format. At that point, you use the key to authenticate the file transfer (as explained in episerver:campaign.SSHFilePath).

Transfer file information

  • Product ID
  • Product name
  • Product category, a string showing the category hierarchy delimited by hash tags (#). For example, Fashion#Mens#Mens Shoes.

Note: If a catalogue's category exceeds 10 levels, only the first 10 appear in the transfer file.

  • Text fields
  • Image fields
  • Link fields
  • Additional data fields

The transfer file elements are delimited by semicolons (;). If you want to open the file in Excel, choose semicolons at the Delimiter field.

Configuration settings

To enable this transfer, assign the following settings in your web.config file, within the episerver:campaign element.

Note: Work with the Episerver Campaign support team to obtain the file name, campaign client id, FTP information, and the path and passphrase to the SSH key file.

web.config setting Description

episerver:campaign.CatalogNames 

The list of Commerce catalogs to export, separated by semicolon (;). To export all catalogs, leave the list empty.

episerver:campaign.ExportProductFileName

The exported product file name. Must match the file name configured in the Campaign site.

episerver:campaign.CampaignClientId 

The campaign client id. Provided by Campaign.

episerver:campaign.FTPHostName 

The FTP host name. Provided by Campaign.

episerver:campaign.FTPPort 

The FTP port. Provided by Campaign. The default value is 22.

episerver:campaign.FTPUserName 

The FTP user name. Provided by Campaign.

episerver:campaign.SSHFilePath 

The path to the SSH key file from website root. This file is used to transfer the exported file to Episerver server in SFTP.
For example:
<add key="episerver:campaign.SSHFilePath" value="/campaign_ssh.key" />
or

<add key="episerver:campaign.SSHFilePath" value="/App_Data/campaign_ssh.key" />

episerver:campaign.SSHPassphrase 

The passphrase of the SSH key file. This value is optional. Leave it empty if you do not configure a passphrase for the SSH key.

episerver:campaign.MarketId 

The id of the market whose product data you want to get.

Note: If the FTP credentials are incorrect, the transfer file is generated in Commerce site but it cannot be transferred to Campaign server. The scheduled job fails.

The product data model

The ProductDataModel class (listed in the table below) contains the data being transferred to Campaign. Each instance of this class refers to a product item in the CSV template. For a more detailed description of product data, see Use CSV.

Item Description

Id

The product Id. A unique value for internal use within Campaign.

Name

The product's display name.

Category

The product category. For internal use within Campaign to organize products.

Text[1-10]

Custom text fields.

Link[1-3]

Product links, including link text and link URL.

Image[1-6]

Product images, including the image and navigation link.

AdditionalData[1-20]

Additional product data fields.

Customizing data

You can modify the way that product entries are collected for export, and customize the content of each product.
First, a market is selected (using the configured marketid in Configuration Settings). Next, catalogs are selected based on the market's default language, and products within those catalogs are collected. Since products are exported for marketing purposes, only products with a price are processed.

By default, all entries under the selected catalogs are collected. To modify the list of collected products, implement IProductLoader.GetEntries()

For each product entry, a data line item is created. The basic fields in that line item are product id, name and category. Other fields are optional. To customize that data, implement IProductFieldsHandler and override the corresponding methods.

  • PopulateCategoryFields(): populates the category path of the product, separated by the hash symbol (#). The Campaign system can process a maximum of 10 category levels.
  • PopulateTextFields(): populates the text values. Episerver provides these default Text field values:
      • Text 1: product category
      • Text 2: product code
      • Text 3: product URL
      • Text 4: product unit price
      • Text 5: product discounted price
  • PopulateImageFields(): populates image text and image link.
  • PopulateLinkFields(): populates links.
  • PopulateAdditionalDataFields(): populates additional data text.

Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/