csv_export_documentation:csv_2_format

csv_export_documentation:csv_2_format

If your are using CSV-export for the data synchonization between your shop data and Findologic, the CSV-data provided by you has to be formatted in the way that is described below.

Unless you have an enterprise-contract the shop data will be imported by Findologic automated daily at a fixed time between 01:00 CET and 06:00 CET.

You can either write your own export script, provide a completely finished CSV-file for the import, or use a plugin provided by Findologic.

You can find a detailed description of all available colums in our CSV-format below.

The CSV-export should be provided as direct link to the CSV-file in the customer login - if needed with login and password (HTML basic access authentication).
Control characters ([#x01-#x08] | [#x0B-#x0C] | [#x0E-#x1F]) are not allowed in any value of the feed.
The summary, description and the attribute values should not contain any HTML-Tags. A warning will be shown during import and the tags get stripped automatically.

Demo CSV

The columns in particular

Column Description Has to have content Will be used for search
idUnique ID of the article Yes No
ordernumberArticle number(s) / SKU(s) of the article Yes Yes
nameName of the article, how it is displayed on the search result pages Yes Yes
summaryShort description of the article, which can be displayed optionally. No Yes
descriptionDetailed article description. No Yes
priceCurrently valid retail price incl. taxes (f.e. currents sales price). Must have a dot (.) as decimal delimiter only. Yes No
overriddenPriceRegular price of the article incl. taxes. No No
urlAbsolute or relative link to the article-detail-page. Yes No
image*Absolute or relative link to article image. We recommend to deliver the image in thumbnail-size. Export supports more than 1 product image. Just add another column image0, image1 and so on. Syntax is “imageX” where X is any number. No No
attrib_*Categories and attributes (used for filters) of the article. Yes Yes
keywordsKeywords, which are related to the article. No Yes
groupsGroups, which the article is related to. (f.e. subshops). No No
bonusBonusvalue related to the specific article. This is useful to push products on top of the search results. Must be a numeric value. No No
sales_frequencySalesfrequency of the article. “How often was the specific article sold?” Must not be negative. Yes No
date_addedThe date, on which the article was added to the shop. Use ISO-8601 as format. No No
sortThis value can be used to sort the articles and to have influence on the position of specific articles on the search result pages. Has to be an integer. No No
visibilities Indicates the visibility of all/some products No No
prop_* You can define additional information using the properties column. No No

Format

  • The CSV-file has to be UTF-8 encoded.
  • The columns of the CSV-file have to be seperated by a tab (\t).
  • The rows have to be seperated by “new line” (\n). (NOT carriage return)
  • If the text value of a column contains several words, it has to be in double quotation marks ().
  • Functional characters (return, \n, tab \t, etc.) have to replaced by a white space.
  • Escape sequences are used analog as in C / C++ / Java / PHP (f.e. A 17\” monitor “).
  • The first row has to contain the names of the columns, that are shown in the table above (f.e. id, ordernumber, etc.).
  • The names of the columns must not be in quotation marks.

The columns in detail


id

Unique ID of the article:

  • May contain letters and numbers.
  • Must not be longer than 255 characters.
  • Has to be unique - if there are duplicate ids only the first article with this id will be imported.

ordernumber

Ordernumber(s) / SKU(s) of the article:

  • May contain characters and seperators (except ”|“ and ”#“).
  • You can provide several ordernumbers seperated by ”|“. These can be used slave- / child-ordernumbers, SKUs, EAN/ISBN, etc.
  • Ordernumbers are not being searched error tolerant. If no exact match exists, the whole database is being searched.
  • In order to be able to find variations of the ordernumber, you can add these variations as seperate ordernumbers (f.e. 081512345|0815 - if the ordernumber should be found also by typing in the first 4 numbers).
This field should be used only for article numbers/EANs/SKUs and NOT for the number that a user gets when an order is being submitted in your shop.

name

Name of the article:

  • Must not contain HTML- or XML-formatting.

summary

Short description of the article:

  • Must not contain HTML- or XML-formatting.

description

Detailed description of the article:

  • Must not contain HTML- or XML-formatting.

price

The gross price (base price - incl. taxes) of the article.

  • Must have a dot (.) as decimal seperator.
  • Must not contain seperators for numbers larger than or equal to 1000.
  • Example: 24999.95 = right | 24,999.95 = wrong
  • For certain cases such as items without a price, intranet- or CMS-search, use a price of 0.00.

overriddenPrice

The gross price shown instead of the base price, for example Now only 39.95$ instead of 59.95$ –> base price=59.95, overriddenPrice=39.95.

  • The same rules as in the column price (described above) apply.

url

The URL, which links to the article-detail-page.

  • May be relative or absolute.
  • If a relative URL is given, it will be appended to the search result page URL.

image

The URL, which links to the article image.

  • May be relative or absolute.
  • If a relative URL is given, it will be appended to the search result page URL.
  • All image columns need to be numbered, starting with image0, continuing with image1, and so on.

attrib_*

  • Each attribute gets its own column, that will be used as filters. Here you can find our documentation about filter configuration.
  • The column name will be “attrib_” + “FILTERNAME”. Examples: “attrib_color”, “attrib_size”, “attrib_cat”, “attrib_vendor”
  • For an attribute with multiple values, use a comma “,” as separator. If a comma is used within the value, it must be escaped like \. A comma in column name must not be escaped.
attrib_color attrib_vendor attrib_cat attrib_Sport
blue,black Nike Running Basic\,Sports

categories

  • Categories must be given with the key attrib_cat. This is important!
    • Sub-categories have to be separated with an underline character _.
    • For example, an article from the category Bikes > Mountain Bikes has to look like this: Bikes_Mountain Bikes

attrib_cat_url (Category paths for navigation)

In order to use Findologic Navigation with Direct Integration, the parameter attrib_cat_url has to be added with the category path. If a product is shown in several categories, all paths have to be exported.

You have to export both main-attrib_cat_url's and sub-attrib_cat_url's for the main- and sub-categories, that an article is assigned to.

For example for a product, which is assigned to the following categories …


vendor

  • Vendors (manufacturers) must be given with the key vendor. This is also very important!

keywords

Keywords, that you specify for the given article. As this column has a big influence on the calculation of the results, please fill this colums very senseful in order to get the best search results.

  • Keywords have to be seperated by a comma (”,“).
  • Keyword may contain more than one word (“hiking shoe”).
  • Example: hiking shoe, mountains

groups

This parameter can be used to assign given articles to certain groups. These groups can be used to seperate search result for subshops or customer-groups.

  • Have to be seperated by a comma (”,“).
  • The values have to be strings.
  • There is a maximum of 1 024 groups supported per export.
  • If the value of a group contains more than one word, you have to replace the whitespaces with ”+“.
  • Example: uk_01,uk_02,ger_01,ger_02,rest+of+the+world.
  • The maximum character limit of each group ist 255.
  • To get search results for specific group - use parameter group in request, e.g. via hidden input field in the search form.

—-

bonus

With this value, you can influence the ranking of certain articles.

  • The bonus ranking is computed after the following formula: ( 1 + bonus ), meaning that a bonus of 1 will double this articles relevance.
  • Negative values are allowed, if you want to lower the ranking of the article.
  • To boost an article, we recommend using a value from 1 to 3.
  • To lower the ranking of an article, we recommend a value from 0 to -0.9.
Please note, that the value -1 will be overridden with the value -0.9 in the import.

sales_frequency

Amount of sold items of the given article.

  • This value has to be an integer (whole number), whose value is bigger as or equals 0.
  • This value will be computed into ranking calculation.
  • This value can also be used as a sort criteria.
If you use PlentyMarkets (version 6 or higher) it is not possible to export a value for sales frequency
Please note, that negative values will be overridden with the value 0 in the import.

date_added

The date, on which the article was added.

  • The date hast to be given in the Use ISO-8601 format.
  • This value can be used as a sort criteria.

sort

Freely choosable integer (whole number) value to sort articles on the search result page.

  • Articles may be sorted ascending or descending after this value.
  • This value can also be used as a sort criteria.

visibilities

  • The visibility must be set in the column visible.
  • The column visible is an optional column, if it did not exist all products will be visible.
  • The column visible must contain lowercase true (or 1 as a replacement) for visible initial state or lowercase false (or 0 as a replacement) for invisible initial state.
  • If the column value is blank or one of the values (True, faLse, yes, no, -1 ….) , this will cause validation warnings, and will use true as fallback value.

prop_*

  • The values in this column won't be used by for the calculation of the search results.
  • All informations given here can be used for your specific needs.
  • F.e.: stock information, shipping details, etc.
  • The column name must be prefixed with “prop_”. Example “prop_shipping”, “prop_stock”

Using properties for product variants in search results

If you want to show different variations (colors, sizes etc.) of a certain product in your shop and you want to display those variants in specific product-cards on the search result page, it can be realized by following the steps described below (example for colors):

Functionality:

  1. All color-variants displayed for parent (master)-product.
  2. While hovering over the variant picture - appropriate image should be displayed.
  3. By click on a color-variant or on an image the page of the product with the right color should be opened.

1. 2. 3.

How the content of the variants-property should look like:

You have to provide an appropriate property (for example “variants”) for every parent-product by using a JSON-string. Here is an example of this property:

  {
   "Mud" : {
    "VariantIconPic" : "https://www.shop.com/media/jacket_mud_variant_icon.jpg",
    "productPic" : "https://www.shop.com/media/jacket_mud_variant_pic.jpg",
    "productUrl" : "https://www.shop.com/jacket_mud"
   },
   "Black" : {
    "VariantIconPic" : "https://www.shop.com/media/jacket_black_variant_icon.jpg",
    "productPic" : "https://www.shop.com/media/jacket_black_variant_pic.jpg",
    "productUrl" : "https://www.shop.com/jacket_black"
   },
   "Red" : {
    "VariantIconPic" : "https://www.shop.com/media/jacket_red_variant_icon.jpg",
    "productPic" : "https://www.shop.com/media/jacket_red_variant_pic.jpg",
    "productUrl" : "https://www.shop.com/jacket_red"
   },
   "Navy" : {
    "VariantIconPic" : "https://www.shop.com/media/jacket_navy_variant_icon.jpg",
    "productPic" : "https://www.shop.com/media/jacket_navy_variant_pic.jpg",
    "productUrl" : "https://www.shop.com/jacket_navy"
   }
  }

Exporting variants with parent id

This export format is still in BETA.

This format allows the export of variant specific attributes. Those attributes can then be used to filter for the variant and not just the parent product.

  • Example: A shirt in size=M is available in red, but the same shirt in size=L is only available in blue.
This export format is not supported by default.

This export format is not set as default and must be activated by Findologic.Please contact our technical support if you have any questions regarding this export format.


Format

  • A parent product must contain all ordernumbers of its variants and each variant needs a dedicated ordernumber as well.
  • A variant export must contain a column called parent_id
  • Variant products must follow the parent product immediately, without any other parent products in between.
  • Header column names (id, parent_id, price etc.) shouldn't be wrapped in quotes/parentheses.
  • Only the attributes of the parent have a effect on the outputAttributes.
  • Attributes which should be applied to all variants must be defined in the attributes field of the parent.
  • ItemVariants/children without attributes will break the export.
  • A child must not contain keywords. This will break the export.
  • Prices of variant items won't be used for sorting.
  • Only parent products are available for Push Rules and Bonus Values.