As mentioned on the Prepare the Product Data page, this part of the documentation describes the requirements that your product data feed needs to fulfill in order to build Product Guides entirely yourselves with the excentos Workbench.
If you have more complex feeds (e.g. web services or XML feed), please return to the Prepare the Product Data section or contact excentos support if you have any questions regarding your data - we'll help you getting any data feed requirements covered.
Table of Contents:
Upload Requirements and Limitations
- The file has to be a CSV (comma-separated values) file. Only this file type is accepted.
- If your product data is written in an Excel sheet (.xls or .xlsx) or in an OpenDocument format (.ods) which are used by LibreOffice or OpenOffice, the file has to be exported to a CSV file (see Export the Product Data File into CSV).
Data Feed File Requirements
If you want to connect your product data directly yourselves to the Workbench, the product data CSV file needs to fulfill the following requirements (as mentioned above, please contact excentos for more complex feeds such as XML):
| Type / Field | Specification |
|---|---|
| File type | CSV file (preferred encoded as UTF-8) |
| Field separator | Needs to be one of the following: ',' (comma), ';' (semi-colon), ':' (colon), '|' (pipe), tab or whitespace character. |
| Text separator | Coherent text has to be surrounded by " " (double quote) or ' ' (single quote). One of them at the beginning of a cell; one at the end of a cell. This is especially important if the text contains a specified field separator. |
| Escape character | The escape character is used within the text separators. Normally this is a '\' (backslash), to escape a single double quote, another single double quote can also be used. |
| Decimal separator | Has to be a '.' (dot), e.g. '799.99'. All comma separated decimals (e.g. '799,99') cannot be converted into numbers at the moment. |
| Multiple values separator | If some attributes contain cells with more than one value in a cell (e.g. the attribute color with the values black and blue), these values need to be separated by a separator (e.g. a comma; such as "black,blue"). Otherwise these two values will be interpreted as one value and cannot be split by using the "Multi value" switch button in the data attribute table (see Upload your Product Data File, Multi Values). You can change the global Multiple values separator anytime as well as the local separator (for each attribute separately) in the Product Data view. |
| Units | Such as kilogram, currencies etc. should be in a separate field if the data field should be interpreted as a number. (we've marked this as suggestion only because the unit is only required if it shall be displayed in the Product Guide. The unit is not technically required, except if prices are displayed in the result list because we then need to know the currency) |
Hint
The field and text separator as well as the file type encoding and the escape character can be set during the uploading process of your product data file (local upload).
Required Fields and Their Names
The Workbench expects a fixed name convention for some core product attributes.
- The "Required" attributes in the table below are the minimal set of data that every Product Guide needs to work properly.
- The "Recommended" attributes are technically optional, but we recommend you using them in order to display certain information like the product name or price in the product recommendation card.
Attribute Mapping
Despite that fixed naming convention it is fortunately possible to map the underlying attribute names to your product attribute naming schema (see Attribute Mapping).
Hint
If you build up your product data from scratch, the easiest way to fulfill the data requirements is to start with the Template Data File.
General Data Attributes
General product attributes are identical across all product categories of your Shop / Website.
The required and recommended data attributes and the name conventions for the data fields are:
| Attribute Name | Required | Recommended | Remarks | Visible in Recommendation |
|---|---|---|---|---|
| id | X | - | Unique ID provided by the feed If your feed does not contain that kind of information, an internal generic id is created to distinguish all products. This internal id is not visible in the data or the Workbench at all. | - |
| name | (X) | X | Name of the product The name is not technically required, but makes it a lot easier for you and the end-users to identify products in the result list. |  |
| image | (X) | X | Product image URL, e.g. a URL to the product image on your website The image is not technically required, but makes it a lot easier for you and the end-users to identify products in the result list. | |
| price | - | X | Product price (dot-separated decimal number) | |
| manufacturer | - | X | Manufacturer or brand name | |
| detailUrl | - | X | URL to the product details page | |
| purchaseUrl | - | (X) | URL to shopping basket. We recommend to include it since the product recommendation can then directly perform a "add to basket" action without the user needing to visit the product details page first. However, this depends on the desired customer journey throughout your shop / website. This feature has to be supported by your website and furthermore implemented for your individual requirements. | |
| variantId | - | - | Master variant ID of a product. Useful if your product assortment contains e.g. color or size variants. excentos can collect them make sure only the master product is displayed in the product result list. | - |
| description | - | X | Product description text | |
| currency unit | (X) | Not strictly necessary, but cleaner. The currency can be directly included in the price attribute, too. | ||
| status / available / online etc | (X) | If you can not restrict your product feed to products actually available, please provide a suitable filter attribute to excentos | ||
| category | (X) | Having a category indicator for the product is often helpful. Please try to include the tree of parent categories (in a separate attribute if possible) | ||
| Push factors / merchandising information | (X) | If you have information available that helps excentos to optimize the product listing for your business (such as margin, stock levels), include them. |
All attribute names are case sensitive
That means that the name 'price' and 'Price' will be recognized as two different attributes (with small and capital 'p'). Please make sure that all attributes are written correctly to match the required/recommended attributes above.
Otherwise make sure that your own attribute names are mapped correctly. Else the corresponding information cannot be displayed or executed properly.
For more information on possible data attributes and which data might help to even improve the Product Guide, please also check https://www.excentos.com/en/documentation/data-feed-requirements.
Category-specific Product Data
Category-Specific Attributes describe the product itself, such as technical data, possible use-cases and everything that distinguishes one product from the other. For every Product Guide, we need all the category specific attributes like e.g. the screen resolution of a notebook computer, the shoe size of a mountaineering boot, the range of height adjustment of an office desk etc. The more data we have, the more powerful and detailed the Product Guide can be.
The categorry-specific attributes can have the same data structure (mostly the case with CSV files) or a separate data structure / different attributes per category (mostly the case with XML data structures).
Category-Specific Attributes are not required for the data sourcing option „third-party licensed data“.
Example of category-specific attributes
Typical CSV file with product data for, e.g., bicycles:
This is how the CSV file needs to look like if you open it in e.g. Excel if you have correctly set the text delimiters (in the example above we used a comma):
Data Feed for international rollouts
You can either provide
- individual feeds per market / country / etc.
- or tell excentos a filter criterion within a central feed from which excentos can decide in which market to include the product.
If prices, product names and descriptions differ, we recommend to provide separate data feeds for each market (although it would be technically possible to contain all markets in one feed).
