Product elements and product data
General Overview
Product elements are an optional feature, allowing you to use data from external sources in the Design Editor for emails. They are mostly used for information about products from e-commerce systems. This requires that your e-commerce system can export product data to CSV or XML files.
Data provision
Overview of data processing and formatting
Product data is processed in five stages:
- You provide your product data either as a CSV file or as an XML file. If you use CSV files, you upload these to Optimizely's server through SFTP. If you prefer not to use SFTP for CSV uploads, a special upload page can be provided within Campaign. If you use XML files, you upload them to your own server.
- Optimizely support creates a job in Campaign which imports the data.
- Optimizely support combines your CSV or XML data file with a mapping. This determines which fields will be available in the Design Editor. The combination of your data with a mapping is called product feed.
- Optimizely support creates one or more customer-specific product layouts that determine how information from your product feed is styled and displayed.
- You add product elements to your message drafts to show products from your feed. In a product element, product data is rendered according to a product layout.
Four CSV formats for product data are supported:
- Campaign's own format (see CSV Structure below),
- Oxid,
- Magento,
- Shopware.
You can later update your CSV product data file yourself through SFTP, or in the Campaign UI. Of course you can also update an XML file hosted by you at any time.
Note
When updating product data, make sure the data's structure does not change so that the mapping still fits.
Supported contents
The product data interface can load the following data for each product element:
- the product’s unique ID, name and category
- up to 10 strings e.g. a heading, a product description, or a price
- up to 3 text links, such as calls to action (e.g. "Buy now")
- up to 6 images (specified as a URL of an image file), including alt texts
- up to 6 image links that lead to additional information by clicking an image
- up to 20 strings with additional data
Product layouts and product elements
As mentioned in Data processing and formatting above, product layouts are required for using product elements. Product layouts are created by Optimizely on request. This service is subject to charge per layout.
A layout can be applied to a product feed if the data fields match. The same layout may be applicable to data from CSV files and also to data from XML files, if the data from both sources are mapped so that the resulting product feed fits the layout.
Data from a product feed is available in the Design Editor through product elements. Just like any other elements, you add these by dragging them from the side panel to the design area. The product feed does not contain any formatting, so you need to select a product layout when adding a product element.
After a product element is added to a message draft, its content is static, so that all recipients get the same content. If the data from the feed is not exactly what you want to send to your recipients, you can override individual values within a product element (see Overriding values in a product element below).
The settings for a product element in the Design Editor for emails, with a preview for the mobile version.
CSV structure
For your CSV files, you can use formats from different systems, see Data processing and formatting above. Optimizely Campaign's own format uses following column headings:
"id";"name";"category";"text1";"text2";"text3";"text4";"text5";"text6";"text7";"text8";"text9";"text10";"link1Text";"link1Url";"link2Text";"link2Url";"link3Text";"link3Url";"image1ImageUrl";"image1AltText";"image1Link";"image2ImageUrl";"image2AltText";"image2Link";"image3ImageUrl";"image3AltText";"image3Link";"image4ImageUrl";"image4AltText";"image4Link";"image5ImageUrl";"image5AltText";"image5Link";"image6ImageUrl";"image6AltText";"image6Link";"additionalData1";"additionalData2";"additionalData3";"additionalData4";"additionalData5";"additionalData6";"additionalData7";"additionalData8";"additionalData9";"additionalData10";"additionalData11";"additionalData12";"additionalData13";"additionalData14";"additionalData15";"additionalData16";"additionalData17";"additionalData18";"additionalData19";"additionalData20";When configuring the CSV export, observe the following:
- The CSV file must be RFC-compliant. Technical notes are contained in RFC 4180.
- Use UTF-8 without BOM.
- Use the semicolon (;) as a separator.
- If the product data includes quotation marks, escape these in the CSV file by using double quotation marks. The product data import fails if quotation marks from your content are misinterpreted as code. Example: If your data contains words in quotation marks, e.g. "Savoir Vivre.", put the quoted text in double quotation marks in the CSV file: ""Savoir Vivre"". The first quotation mark of each pair serves as an escape character.
XML structure and file
Your XML files must be based on the following structure. You may not add any lines but you can leave out lines you do not need.
<?xml version="1.0" encoding="UTF-8"?>
<element>
<property name="id">123456</property>
<property name="text1"><![CDATA[<b>Text field 1</b>]]></property>
<property name="text2"><![CDATA[Text field 2]]></property>
<property name="text3"><![CDATA[Text field 3]]></property>
<property name="text4"><![CDATA[Text field 4]]></property>
<property name="text5"><![CDATA[Text field 5]]></property>
<property name="text6"><![CDATA[Text field 6]]></property>
<property name="text7"><![CDATA[Text field 7]]></property>
<property name="text8"><![CDATA[Text field 8]]></property>
<property name="text9"><![CDATA[Text field 9]]></property>
<property name="text10"><![CDATA[Text field 10]]></property>
<property name="link1Text"><![CDATA[Text for link 1]]></property>
<property name="link1Url"><![CDATA[URL for link 1]]></property>
<property name="link2Text"><![CDATA[Text for link 2]]></property>
<property name="link2Url"><![CDATA[URL for link 2]]></property>
<property name="link3Text"><![CDATA[Text for link 3]]></property>
<property name="link3Url"><![CDATA[URL for link 3]]></property>
<property name="image1ImageUrl"><![CDATA[Image URL for image 1]]></property>
<property name="image1AltText"><![CDATA[Alternative text for image 1]]></property>
<property name="image1Link"><![CDATA[Link for image 1]]></property>
<property name="image2ImageUrl"><![CDATA[Image URL for image 2]]></property>
<property name="image2AltText"><![CDATA[Alternative text for image 2]]></property>
<property name="image2Link"><![CDATA[Link for image 2]]></property>
<property name="image3ImageUrl"><![CDATA[Image URL for image 3]]></property>
<property name="image3AltText"><![CDATA[Alternative text for Image 3]]></property>
<property name="image3Link"><![CDATA[Link for image 3]]></property>
<property name="image4ImageUrl"><![CDATA[Image URL for image 4]]></property>
<property name="image4AltText"><![CDATA[Alternative text for image 4]]></property>
<property name="image4Link"><![CDATA[Link for image 4]]></property>
<property name="image5ImageUrl"><![CDATA[Image URL for image 5]]></property>
<property name="image5AltText"><![CDATA[Alternative text for image 5]]></property>
<property name="image5Link"><![CDATA[Link for image 5]]></property>
<property name="image6ImageUrl"><![CDATA[Image URL for image 6]]></property>
<property name="image6AltText"><![CDATA[Alternative text for image 6]]></property>
<property name="image6Link"><![CDATA[Link for image 6]]></property>
<property name="additionalData1"><![CDATA[Additional information 1]]></property>
<property name="additionalData2"><![CDATA[Additional information 2]]></property>
<property name="additionalData3"><![CDATA[Additional information 3]]></property>
<property name="additionalData4"><![CDATA[Additional information 4]]></property>
<property name="additionalData5"><![CDATA[Additional information 5]]></property>
<property name="additionalData6"><![CDATA[Additional information 6]]></property>
<property name="additionalData7"><![CDATA[Additional information 7]]></property>
<property name="additionalData8"><![CDATA[Additional information 8]]></property>
<property name="additionalData9"><![CDATA[Additional information 9]]></property>
<property name="additionalData10"><![CDATA[Additional information 10]]></property>
<property name="additionalData11"><![CDATA[Additional information 11]]></property>
<property name="additionalData12"><![CDATA[Additional information 12]]></property>
<property name="additionalData13"><![CDATA[Additional information 13]]></property>
<property name="additionalData14"><![CDATA[Additional information 14]]></property>
<property name="additionalData15"><![CDATA[Additional information 15]]></property>
<property name="additionalData16"><![CDATA[Additional information 16]]></property>
<property name="additionalData17"><![CDATA[Additional information 17]]></property>
<property name="additionalData18"><![CDATA[Additional information 18]]></property>
<property name="additionalData19"><![CDATA[Additional information 19]]></property>
<property name="additionalData20"><![CDATA[Additional information 20]]></property>
</element>When creating XML files, observe the following:
- For the file name, use the product ID (the same value as in the file, see below).
- As the file type, use XML, but do not use a file name extension. Example: Do not use wellness.xml as a file name, use only wellness. instead, with the dot at the end.
- Use UTF-8 character encoding.
For the file's contents, observe the following:
- In the first property row, enter the product ID between the <property> tags. Note: Use only letters and numbers for the product ID. Example: <property name="id">123456</property>
- In all remaining lines, insert the value between brackets, after CDATA.
- In the rows text1 to text10, enter up to ten strings for your product offer. Text field 1, Text field 2, etc are placeholders. These strings can include a heading for the product offer, the product name, the product description, the price, the manufacturer, and so on. Adapt the content to your needs. Example: <property name="text1"><![CDATA[Wellness Weekend]]></property>
- In the link-related rows, enter link texts and link targets (URLs) for up to three links. Example: <property name="link1Text"><![CDATA[Book now]]></property> <property name="link1Url"><![CDATA[http://www.example.com/wellness]]></property>
- In the image-related rows, enter up to six sets of image sources (URLs), alt texts and link targets. Example: <property name="image1ImageUrl"><![CDATA[http://www.example.com/pool.jpg]]></property> <property name="image1AltText"><![CDATA[An indoor swimming pool]]></property> <property name="image1Link"><![CDATA[http://www.example.com/wellness]]></property>
- In the lines for additional data, enter any other values you want to use, such as metadata for the program logic of the HTML layouts.
XML data retrieval and user experience
To make product data available in the Design Editor, provide the XML files on your server in the exact location that you agreed on with Optimizely support.
The product data interface for the Design Editor is more flexible than the old version for the Template Kit Editor. You can still retrieve XML files from a URL like this: [Base-URL]?id=[Product-ID] But now you can also use the pattern: [Base-URL]/[Product-ID]
The data from XML files is not stored in your Campaign client like data from CSV files but instead retrieved from your own servers whenever needed. This leads to a difference in user experience: When selecting a product in the Design Editor, the form field for product IDs is not a drop-down field but a simple text field because retrieving all possible IDs from another server would decrease performance. This means that users must know the ID of the product they want to add when editing a message draft.
Updating your CSV product data file (UI)
Note
This procedure will overwrite your existing product data. Make sure not to lose any data that you still need!
Context: If it is supported by your Campaign configuration, you can update your product data by uploading a new CSV file through the UI. Make sure there are no changes to the structure of your data. The name of the uploaded file is not important, it will automatically be adjusted. Prerequisites: You are logged in in Optimizely Campaign. You have the permission Special Pages. The file with updated product data is available on your local system.
- In the menu bar, go to More... > Upload File. Note: Depending on your configuration, the menu entry may have a different name.
- Click Choose File.
- Select the file with the updated product data.
- Click Upload. → Your existing product data file is replaced with the new file.
Updating your CSV product data file (SFTP)
Note
This procedure will overwrite your existing data. Make sure not to lose any data that you still need!
Context: You can update your product data by uploading a new CSV file, as long as there are no changes to the structure of your data. Prerequisites: You have SFTP access to your CSV import folder. An import job was created by Optimizely support.
- Start your FTP client.
- Connect to your CSV import folder on the Optimizely server.
- Upload the new product data file, using the exact same name, overwriting the old file. → Your existing product data file is replaced with the new file.
Working with product data
Adding a product element to a message draft
Prerequisites: You see a message draft in the Design Editor. A product feed and a product layout are available in your client.
- In the side panel, in the Content tab, find the product element.
- Drag the element to the desired position in the design area. → A new, empty product element is added to your message draft.
- In the new element, click Edit... → You see the menu Product, the tab Layout and Product Selection is selected.
- In the field Feed, select the feed that contains the desired product.
- In the field Product Layout, select the layout you want to use.
- In the field Product Selection, select the product you want to show in the message draft. Note: If your product feed is based on XML files, you have to manually enter the product ID here.
- Check if the previews for desktop and mobile view look as expected.
- Click Apply. → The product element shows the product from the product feed.
Overriding values in a product element
Context: If the content from the product feed is not quite right for your message draft, you can replace the values of individual variables within a product element. This applies only to the current product element and does not change the content of the product feed. Prerequisites: You see a message draft with a product element in the Design Editor.
- Select the product element.
- In the side panel, in the section Content properties, click Edit... → You see the menu Product, the tab Layout and Product Selection is selected.
- Open the tab Overrides.
- Click + Override. → A new line with two fields is added to the menu.
- In the field Column (Variable), select the variable for which you want to define a new value.
- In the field Content, enter the value you want to use for this product element. Note: You can use simple HTML tags like <b> for bold or <i> for italic here.
- Click Apply. → The product element shows the new value.
Deleting an override
Prerequisites: You see a message draft with a product element in the Design Editor. The product element contains at least one override.
- Select the product element.
- In the side panel, in the section Content properties, click Edit... → You see the menu Product, the tab Layout and Product Selection is selected.
- Open the tab Overrides.
- Find the override you want to delete.
- In the line of the override, click (Remove line).
- Click Apply. → The override is deleted.
Adjusting the layout of a product element
Warning
This feature is meant for experts, make sure your changes are safe and responsive.
Context: If you want to change the look of an individual product element, you can adjust the pre-defined layout. Prerequisites: You see a message draft with a product element in the Design Editor.
- Select the product element.
- In the side panel, in the section Content properties, click Edit... → You see the menu Product, the tab Layout and Product Selection is selected.
- Open the tab HTML Layout.
- Activate the toggle Local overwriting of HTML and Velocity code.
- Adjust the code as desired.
- Click apply. → The changes are applied to the product element. The pre-defined layout is not affected.