ChannelEngine: product feeds
About this article
This article describes product feeds, what is required to use them, how to set them up, and more.
Table of contents
Password-protected feeds and FTP feeds
Required, recommended, and optional fields
Generate parents or grandparents
Introduction
A product feed is a file that is available online (e.g.: on your FTP server or a public resource like Google Sheets) and can be used by ChannelEngine to import your product data.
Product feed format
Product feeds must be provided in XML or CSV format. A TXT format is also allowed, as long as the XML or CSV format is used. When using CSV, the following delimiters are allowed:
- Semicolon (;)
- Comma (,)
- Pipe (|)
- Tab ( )
Each product must have a unique Merchant product number, which makes the product unique in ChannelEngine's database. Commonly used attributes are the SKU, the EAN or a unique ID from the source system. Make sure to map the correct attribute for this identifier, as mistakes may lead to products not appearing on ChannelEngine.
Password-protected feeds and FTP feeds
It is possible to import data from product feeds that are available via HTTP(S) or FTP(S), and are secured with a password.
HTTP(S)
To import a feed using HTTP basic authentication, use the following format:
https://[Username]:[Password]@[YourHost]/[FileName].xml
E.g.: https://testuser:1234@myshop.com/feed.xml
(S)FTP(S)
To import a feed using FTP, use the following format:
ftps://[Username]:[Password]@[YourHost]/[FileName].xml
Depending on the protocol used, adjust the above format to start with ftps
, sftp
, or ftp
.
E.g.: ftps://testuser:1234@myshop.com/feed.xml
Take into account that special characters are automatically converted to their HTML-encoded counterparts when using a URL, which can cause issues with authentication. Therefore it is advised to not use special characters (e.g.: $ # % ^ * : @) in your password, to prevent any authentication errors.
FTP access with a key file
It is not possible to add a feed protected by a .PPK key file to gain access to an FTP server. If this is an option you would like to see added to ChannelEngine in future, please refer to the ChannelEngine Ideas Board.
Set up a feed
Product feeds can be managed and added under the Product feed overview, which is accessible by selecting the product feed box in the dashboard – or by selecting Products > Product feeds in the left-hand side menu.
It is possible to use multiple product feeds, as long as there are no duplicate identifiers in leading feeds. I.e.: each Merchant product number should only be available in one leading product.
Feed operations
As well as adding a feed with the Add feed button, there are other operations that can be performed from the Product feed overview. There are also some feed-specific characteristics visible.
- Name - the name given to the feed.
- URL - the URL where the feed can be downloaded from.
- Type - the type of feed (CSV or XML), and if it is a leading or additional feed.
- Most recent import - the timestamp of the latest import of the feed by ChannelEngine.
- Next import - the timestamp of the next scheduled import of the feed.
- Status - the result of the current or last import of the feed.
- Validation report - redirects you to a separate page which shows the number of active, inactive, and new products from the last import. It also shows which products could not be imported and why, and lists warnings for products that have mapped attributes with invalid data.
- Edit - allows you to edit an existing product feed. This redirects you to the feed mapping.
- Delete - deletes an existing product feed. Bear in mind that this also marks all products in the feed as deleted, if the feed is a leading one.
- Start import - forces the import of a product feed manually. Make sure not use this too often in short succession, as data in product feeds does not have to be updated very frequently – and it increases the load on ChannelEngine's services.
Add a feed
Once you select the + Add feed button, you are asked to input the location of the feed.
Select the correct delimiter, if using a CSV feed (i.e.: what character separates individual columns in the CSV), or the product node in case of an XML feed (i.e.: what tag marks an individual product in the feed). Select Continue when the correct value is selected. The suggested correct value is highlighted in green, but this is based on how often a specific character is encountered, so make sure to verify it.
The product nodes available in the dropdown are based on the number of occurrences of elements, or subnodes, in the feed. The minimum is of two occurrences.
The following example results in two nodes: <product> and <price>. As it has only one subnode – and two is the minimum for a workable product attribute –, <info> is not included.
<xml>
<price>
<sku>1</sku>
<price_in_EUR>40</price_in_EUR>
</price>
<price>
<sku>2</sku>
<price_in_EUR>40</price_in_EUR>
</price>
<price>
<sku>3</sku>
<price_in_EUR>40</price_in_EUR>
</price>
<product>
<sku>4</sku>
<title>awesome</title>
<description>something</description>
<price>40</price>
</product>
<product>
<sku>5</sku>
<title>awesome</title>
<description>something</description>
<price>40</price>
</product>
<product>
<sku>6</sku>
<title>awesome</title>
<description>something</description>
<price>40</price>
</product>
<product>
<sku>7</sku>
<title>awesome</title>
<description>something</description>
<price>40</price>
</product>
<info>
<sku>8</sku>
</info>
<info>
<sku>9</sku>
</info>
</xml>
Feed settings
Once you select Continue after setting the correct delimiter or product node, the feed details page loads. At the top of this page, you see a section with product feed settings.
- Name - the name of the product feed. If you plan to use multiple feeds, make sure to distinguish them by using different names. E.g.: Stock feed supplier 1, Product feed refurbished items, Product translations feed - DE.
- Select the delimiter or product node - this is the delimiter or product node you selected for the feed. It is possible to change it in an existing feed, but there is a risk of undesired results. Make sure not to change this setting unless you know what you are doing.
- Additional - marks a feed as additional. Additional feeds are meant to update attributes of existing products (e.g.: stock, content, etc.)
- Use comma separator in numbers - by default, ChannelEngine's servers are set to the US/international locale. This means that for numbers (i.e.: prices, dimensions, etc.), ChannelEngine expects a period as the decimal separator (e.g.: EUR 9.95). If your feed uses a European locale and numbers with a comma as the decimal separator (e.g.: EUR 9,95), make sure to enable this setting to prevent prices from being 100 times higher.
- Generate parent products - if this setting is enabled, ChannelEngine automatically generates parent products if a parent SKU is mapped – and no parent product is available in the feed.
- Generate grandparent products - if this setting is enabled, ChannelEngine automatically generates grandparent products if a grandparent SKU is mapped – and no grandparent product is available in the feed.
Mapping feeds
Below the settings, you can see the feed mappings that need to be set to import products and its data in the correct fields in ChannelEngine. These feed attributes have to be mapped to ChannelEngine attributes.
Mapping columns
There are three columns for mapping:
- Left column - lists the name of the attribute on ChannelEngine. At the top, you see ChannelEngine specific attributes such as the EAN, the Merchant product number, and the Stock. In the custom fields section, it shows the name you assigned to a custom attribute.
- Center column - shows the mapped attribute from your feed. If the EAN of the product is located at the attribute EAN, for example, you need to map that. In the initial load of the feed, suggested attributes are highlighted in green and show a light bulb icon. This disappears once the mappings are saved.
- Right column - shows the preview of a specific value for that attribute. The first ten items found in the feed are available for preview. This is a good way to check if the attribute you select has the correct values.
For each product feed you add, it is possible to map an attribute under the center column. However, if you use a separate feed for the stock, many attributes do not have to be mapped for that specific feed – only the Merchant product number and Stock attributes.
There are two options for not mapping an attribute in a feed:
- Not mapped - Clear value - useful when the field should be a fixed value. The fixed value can be mapped in channel mapping.
- Not mapped - Keep value - useful when another product feed already fills this field.
In most situations, it is advised to use Not mapped - Keep value as a value. Using Clear value removes product information during every import of that feed if there is something to be removed, and if it is mapped in a different feed it triggers an update with every feed import. This can cause undesired results. E.g.: if you have a product selection rule based on an attribute with a value and feed 1 sets it, but feed 2 clears it, the product is removed and added every x minutes from the channel.
Custom fields
Next to the ChannelEngine-specific attributes you can map, there is also the option to add and map your own custom data attributes or fields.
If you select the + Custom fields option, you see a list of available attributes that can be used for custom fields. Green attributes are already mapped to a ChannelEngine field or custom field. Orange attributes have not been mapped yet. It is possible to add an attribute as a custom field that is already used for another field.
To remove custom fields that have already been added, you can use the Custom fields management on ChannelEngine.
Leading and additional feeds
ChannelEngine allows for two types of product feeds: leading feeds and additional feeds.
Leading feed
A leading product feed contains the core products, and is what is used to create or remove products on ChannelEngine.
- Must contain unique products, so the Merchant product number should not be available via a different feed or another type of data import.
- Using multiple leading feeds is possible, as long as the Merchant product numbers do not overlap.
- When a product is created by one feed, the product gets the ID of that feed. If a product is no longer available in that specific feed, the product is marked for deletion.
- Can be used to create parent or grandparent products, but not simultaneously.
Additional feed
An additional feed contains extra information to update existing products coming from a leading feed. This is useful if you have a separate stock feed you want imported more often, or if you have product data such as translations coming from a different system.
- Must contain the Merchant product number of the products you want to update.
- Cannot be used to create new products.
- Cannot be used to delete new products.
- Cannot be used to create parent or grandparent products.
Required, recommended, and optional fields
Required
The following attributes are needed to create a viable product on ChannelEngine. In theory, only a Merchant product number is enough, but managing products and channels like this is harder and more time-consuming.
Field | Description | Example |
Name | Product name | Black t-shirt with crew neck |
Description | Product description | A simple black t-shirt from Fancy T-Shirts Inc. |
Price | Product price (incl. VAT) | 49.95 |
Stock | Product stock | 25 |
Merchant product number | Your unique product number | 192354 |
EAN | Product GTIN (EAN, ISBN, UPC) | 8710400311140 |
Image link | Deep link to the product's image | http://www.theshirtshop.com/images/products/192354.jpg |
Category | The product's full category path (with each category separated by >) | Men's > t-shirts > crew neck |
Recommended
While not mandatory, it is highly recommend to provide the following attributes in your feed.
Field | Description | Example |
Catalog price | MSRP (incl. VAT) | 59.95 |
Purchase price | Product purchase price (excl. VAT) | 35.00 |
VAT % | VAT percentage | 21.00 |
Brand | Product brand name | Fancy T-Shirts Inc. |
Vendor product number | Manufacturer/Supplier product number | FTI-BLK-XL |
Size | Product size | XL |
Color | Product color | black |
Optional
The following fields are not required, although in some situations they may be conditionally required (e.g.: MerchantGroupNo).
Field | Description | Example |
Parent SKU | The Merchant product number of the parent product, it connects parent and child products | 192350 |
Grandparent SKU | The Merchant product number of the grandparent product, it connects grandparent and parent products | 192 |
Details | The product's details | A simple t-shirt. Color: black. Brand: Fancy T-Shirts Inc. |
URL* | Deep link to the product's details page | http://www.theshirtshop.com/ products/192354-black-t-shirt-with-crew-neck.html |
Discount % | The difference between the sale price and the MSRP in percentage | 47.92 |
Margin % | The margin between the price and purchase price in percentage | 30 |
Shipping cost | Product shipping costs | 5.95 |
Shipping time days | Delivery time indication | Ordered before 22:00, shipped today. |
Extra image link x | Deep link to the product's additional images | http://www.theshirtshop.com/ images/products/192354-1.jpg |
* = Only for affiliate networks/click channels.
Other additional fields might be added to the feed. These fields can be used to filter products on ChannelEngine, or to be passed along to one of the mappable attributes.
Delete fields
Occasionally, you may need to delete a field from your product feed. When you delete a field, ChannelEngine removes the value from that field following the next feed import.
Formatting and encoding
If you want to include special characters or content in descriptions or other attribute values (e.g.: HTML in an XML file, or quotation marks in a CSV file), make sure to properly 'escape' them.
XML
For XML you need to include the value between CDATA tags, like in the example below:
<description><![CDATA[This basic t-shirt has a <i>print</i> with a funny text. <br><br>The fabric is made of 92% cotton and 8% elastane.]]></description>
CSV
For CSV you need to use a quotation mark to escape special characters, like the quotation mark itself ("), a comma (,), or a new line ( ). If your attribute value has meaningful spaces, the entire value should be enclosed in quotation marks. For an example of part of a CSV row containing attribute values that need to be escaped, see below:
id, "This basic t-shirt has a ""print"" with a funny text. <br><br>The fabric is made of 92% cotton, 5% elastane and 3% awesomeness.", phone number, title,
Encoding
ChannelEngine uses UTF-8 as the default encoding for all data. If you do not specify the encoding for your product feed or if it is in an encoding format other than UTF-8, odd characters appear on product data. It is highly recommended to provided all data in UTF-8 formatting to prevent incorrect decoding.
Generate parents and grandparents
If a leading feed does not contain parent or grandparent products, these can be automatically created by ChannelEngine. It is required that the feed containing children already have a shared identifier grouping them, which could be used as the Merchant product number for the parent.
Parents and grandparents can be created the following options:
- Generate parent products
- Generate grandparent products
A generated product can be recognized by Parent (generated icon) or Grandparent (generated icon) in the product detail view.
What information is copied/set?
For both generated parent and grandparent
- Stock, Grandparent SKU, and EAN are set to null (empty)
- Values, including custom fields, are copied from the first parent/child below it
- The name of the new product is the longest common prefix, minus punctuation marks at the end
New parent
- Size is set to null (empty)
New grandparent
- Size and color are set to null (empty)
Examples of feeds
The following examples can help you understand the concepts and guidelines mentioned in this guide:
Comments
0 comments
Article is closed for comments.