xml_export_documentation:xml_2

Findologic XML 2.0 export format

Our toolkit libflexport which exports product data according to the XML export patterns of this page is now available via the following Github repository. https://github.com/findologic/libflexport/tree/master

If your are using XML-export for the data synchronization between your shop data and Findologic, the XML-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.

Export script can be written with Findologic export library or by your own.

You can find a detailed description of all available tags in our XML-patterns below.

The latest XML scheme for validation can be found on Github: Findologic XML-Schema. Check your XML against the scheme and see if your export XML is valid: https://www.corefiling.com/opensource/schemaValidate.html

Link to the script-file that triggers XML-export has to be provided in the customer login - if needed with login and password (HTML basic access authentication).

Findologic supports all encodings. It just needs to get mentioned at the start of the XML e.g. <?xml version=“1.0” encoding=“UTF-8”?>

The parent tags must be exported (summaries, descriptions, etc.), but can be closed itself (can be empty), if the child tags are not required. For example like that:

[…] 
<summaries /> 
<descriptions /> 
<usergroups /> 
[…]

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.

Overview

Item	Short Description	Tag required	Value required	Will be searched
`<?xml version=“…” encoding=“…”?>`	Specifies the encoding	Yes	Yes	No
`<item id=“”>`	Unique identifier	Yes	Yes	No
`<ordernumbers>`	Article number, EAN or SKU	Yes	No	Yes
`<names>`	Article name, as usually shown on the result page	Yes	Yes	Yes
`<summaries>`	Summarized article description	Yes	No	Yes
`<descriptions>`	Detailed article description	Yes	No	Yes
`<prices>`	Current article price including taxes	Yes	Yes	filterable only
`<overriddenPrices>`	Strike-through price including taxes	No	No	No
`<urls>`	URL to the article page, must be absolute	Yes	Yes	No
`<images>`	URL to the article image, must be absolute.	Yes	No	No
`<keywords>`	Keywords linked to current article	Yes	No	Yes
`<groups>`	Visibility of article, i.e. only visible to the exported groups	Yes	No	No
`<bonuses>`	Bonus value to rank certain articles higher than others	No	No	No
`<salesfrequencies>`	Amount of sold items of this article	Yes	No	No
`<dateAddeds>`	Date current article was added	Yes	No	No
`<sorts>`	Value for custom sorting of search results	No	No	No
`<visibilities>`	Indicates the visibility of all/some products	No	No	No
`<attributes>`	Article categories and attributes. Will be filters	Yes	Yes	Yes, also filterable
`<properties>`	Additional information of article to be shown on search result listing	Yes	Yes	No
`<variants>`	Product variants	Yes	Yes	No
	Attributes and properties in XML-feed

Wrapper

<?xml version="1.0" encoding="UTF-8"?>
<findologic version="">
    <items start="" count="" total="">
        <item id="">
            [...]
        </item>
        <item id="">
            [...]
        </item>
        [...]
    </items>
</findologic>

<findologic> has to have the attribute version containing the version of the format.
<items> gives information about the start-pointer (start), how many products are exported per step (count) and how many products exists in the shop in total (total). For more information see Export
<items> may contain 1+ <item>-tags.

Due to runtime limitations the XML-export has to be paginated.

You have to use double quotes to seperate XML attributes like “count” or “total”. Single quotes are not supported at the moment.

Using our export toolkit?

You can find the information about how to setup our export library on our Github wiki page.

item

[...]
<item id="">
  [...]
</item>
[...]

<item> holds all the information for a single item, identified by a unique ID.
Every information in the <item>-tag can be general (no usergroup-attribute) or limited to a single usergroup via the usergroup-attribute. The general information is only shown if there is no specific information for the usergroup of the specific user.

Using our export toolkit?

Creating an item with our export library is that simple.

ordernumbers

[...]
<allOrdernumbers>
  <ordernumbers>
    <ordernumber><![CDATA[]]></ordernumber>
    <ordernumber><![CDATA[]]></ordernumber>
  </ordernumbers>
  <ordernumbers usergroup="">
    <ordernumber><![CDATA[]]></ordernumber>
  </ordernumbers>
  [...]
</allOrdernumbers>
[...]

<allOrdernumbers> contains 1+ <ordernumbers>-tags, distinguished via the usergroup-attribute.
<ordernumbers> contains 1+ <ordernumber>-tags.
<ordernumber> contains an article-number like internal arcticle number, EAN, ISBN, …

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.

Using our export toolkit?

Creating an ordernumber element with libflexport.

names

[...]
<names>
  <name><![CDATA[]]></name>
  <name usergroup=""><![CDATA[]]></name>
  [...]
</names>
[...]

<names> contains 1+ <name>-tags, distinguished via the usergroup-attribute.
<name> contains the title of the product.

Using our export toolkit?

Creating a name element with libflexport.

summaries

[...]
<summaries>
  <summary><![CDATA[]]></summary>
  <summary usergroup=""><![CDATA[]]></summary>
  [...]
</summaries>
[...]

<summaries> contains 1+ <summary>-tags, distinguished via the usergroup-attribute.
<summary> contains the short-summary of the product.
We recommend to remove all HTML tags from the summary, e. g. <div>, <p>, <table>.

Using our export toolkit?

Creating a summary element with libflexport.

descriptions

[...]
<descriptions>
  <description><![CDATA[]]></description>
  <description usergroup=""><![CDATA[]]></description>
  [...]
</descriptions>
[...]

<descriptions> contains 1+ <description>-tags, distinguished via the usergroup-attribute.
<description> contains the long-description of the product.
We recommend to remove all HTML tags from the description, e. g. <div>, <p>, <table>.

Using our export toolkit?

Creating a description element with libflexport.

prices

[...]
<prices>
  <price><![CDATA[]]></price>
  <price usergroup=""><![CDATA[]]></price>
  [...]
</prices>
[...]

<prices> contains 1+ <price>-tags, distinguished via the usergroup-attribute.
<price> contains the price of the product in the format 99.99.

It is important that you use “.” as decimal seperator.

Using our export toolkit?

Creating a price element with libflexport.

overriddenPrices

[...]
<overriddenPrices>
  <overriddenPrice><![CDATA[]]></overriddenPrice>
  <overriddenPrice usergroup=""><![CDATA[]]></overriddenPrice>
  [...]
</overriddenPrices>
[...]

<overriddenPrices> contains 1+ <overriddenPrice>-tags, distinguished via the usergroup-attribute.
<overriddenPrice> contains the price of the product in the format 99.99.

It is important that you use “.” as decimal seperator.

Using our export toolkit?

Creating an overriddenPrice element with libflexport.

urls

[...]
<urls>
  <url><![CDATA[]]></url>
  <url usergroup=""><![CDATA[]]></url>
  [...]
</urls>
[...]

<urls> contains 1+ <url>-tags, distinguished via the usergroup-attribute.
<url> contains the URL of the product with leading http[s], which leads the user to the product-detail-page.

Using our export toolkit?

Creating an url element with libflexport.

images

[...]
<allImages>
  <images>
    <image><![CDATA[]]></image>
  </images>
  <images usergroup="">
    <image><![CDATA[]]></image>
  </images>
  [...]
</allImages>
[...]

<allImages> contains 1+ <images>-tags, distinguished via the usergroup-attribute.
<images> contains 1+ <image>-tags.
<image> contains an URL of an image.
If there is no image for a product, the shop-specific “No Image Available” should be exported.

Using our export toolkit?

Creating an image element with libflexport.

keywords

[...]
<allKeywords>
  <keywords>
    <keyword><![CDATA[]]></keyword>
    <keyword><![CDATA[]]></keyword>
    [...]
  </keywords>
  <keywords usergroup="">
    <keyword><![CDATA[]]></keyword>
    [...]
  </keywords>
  [...]
</allKeywords>
[...]

<allKeywords> contains 1+ <keywords>-tags, distinguished via the usergroup-attribute.
<keywords> contains 1+ <keyword>-tags.
<keyword> contains a single keyword of the product.

Using our export toolkit?

Creating a keyword element with libflexport.

groups

[...]
<groups>
  <group><![CDATA[]]></group>
  <group><![CDATA[]]></group>
  [...]
</groups>
[...]

<group> contains 1+ <group>-tags.
<group> contains a usergroup to which the item is visible.
<group> the usergroup used as a third parameter in the Findologic-Snippet (after shopkey) has to have the exact same wording as the usergroup that is used in the data feed.

Using group to set the visibility of items

If no <group> is requested, all items are returned.
If a <group> is requested, only items with a matching <group> are returned.
- Example: If a Usergroup is set by usergrouphash=“employee” → <group><![CDATA[employee]]> </group> only products for which this usergroup is set are visible.

Unknown <group> is ignored, so that when requesting an unknown <group> all items are visible.

Using usergroups to set the visibility of single information relevant for a returned item

By using the usergroups attribute you can set specific images, keywords, price etc.
By using the usergroup attribute within XML tags, you can set specific item information for given usergroups.
If no usergroup is requested the default (non-usergroup) value is used for all tags. Therefore default (non-usergroup) tags are required for all elements in the data feed.
If a usergroup is requested the usergroup-specific value is used for all tags.
- Example: If the usergrouphash=“ employee ” is used → <name usergroup=“employee ”><![CDATA[Internal product title]]></name> the name set for this usergroup is used.
If an item has no usergroup-specific value for a tag then the default (non-usergroup) value is used.
- Example: request usergrouphash=“employee” → <names><name><![CDATA[Product title]]></name><name usergroup=“b2b”><![CDATA[B2B product title]]></name></names> → “Product title“ is used, cause this represents the default (non-usergroup) info.

Usergroup-specific <property> tags are defined at <properties> level. Usergroup-specific <property> tags are not merged with default <property> tags, therefore for each usergroup all the <property> tags for this usergroup must be exported.

To keep the export small, usergroup-specific tags should only be exported when they are different from the default (non-usergroup) tag.
<Attributes> cannot be usergroup-specific and therefore cannot be exported with a <usergroup> attribute.

Recommendation

In case of more than 128 <groups>, please contact support@findologic.com, in order to adjust default settings.
To avoid potential misunderstandings, preferably use alphanumeric values for usergroups (e.g. 18plus, B2B).

Using our export toolkit?

Creating an <group> element with libflexport.

bonuses

[...]
<bonuses>
  <bonus><![CDATA[]]></bonus>
  <bonus usergroup=""><![CDATA[]]></bonus>
  [...]
</bonuses>
[...]

<bonuses> contains 1+ <bonus>-tags, distinguished via the usergroup-attribute.
<bonus> contains a bonus value (between -0.9 and 3) to lower or raise the ranking of a product in general.

Please note, that the value -1 will be overridden with the value -0.9 in the import.

Using our export toolkit?

Creating a bonus element with libflexport.

salesfrequencies

[...]
<salesFrequencies>
  <salesFrequency><![CDATA[]]></salesFrequency>
  <salesFrequency usergroup=""><![CDATA[]]></salesFrequency>
  [...]
</salesFrequencies>
[...]

<salesFrequencies> contains 1+ <salesFrequency>-tags, distinguished via the usergroup-attribute.
<salesFrequency> contains a non-negative integer value for the salesfrequency which can be used for sorting.
If you want your default order to be dynamically calculated including the exported <salesFrequency>-values, please contact our support team.

Using our export toolkit?

Creating a salesfrequency element with libflexport.

dateaddeds

[...]
<dateAddeds>
  <dateAdded><![CDATA[]]></dateAdded>
  <dateAdded usergroup=""><![CDATA[]]></dateAdded>
  [...]
</dateAddeds>
[...]

<dateAddeds> contains 1+ <dateAdded>-tags, distinguished via the usergroup-attribute.
<dateAdded> contains the date and time, when this item was added to the store.
The value can be used for sorting, to list the most recent items first.
The XML datatype is xs:dateTime, a valid value is 2002-05-30T09:30:10
If only the date, but not the time is available, the time can be set to midnight, eg. 2002-05-30T00:00:00

Using our export toolkit?

Creating a dateadded element with libflexport.

sorts

[...]
<sorts>
  <sort><![CDATA[]]></sort>
  <sort usergroup=""><![CDATA[]]></sort>
  [...]
</sorts>
[...]

<sorts> contains 1+ <sort>-tags, distinguished via the usergroup-attribute.
<sort> contains a custom integer value which can be used for sorting.
If you want your default order to be dynamically calculated including the exported <sort>-values, please contact our support team.
You should not use negative values as <sort>-values.

Using our export toolkit?

Creating a sort element with libflexport.

visibilities

[...]
<visibilities>
  <visibile><![CDATA[]]></visibile>
  <visibile usergroup=""><![CDATA[]]></visibile>
  [...]
</visibilities>
[...]

<visibilities> contains 1+ <visible>-tags, distinguished via the usergroup-attribute.
<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.
The default value of the default visible element (non-usergroup) is true if it did not exist.
The default value of a visible element with the usergroup tag is the same value of the default visible element if it did not exist.
If the visible element value is blank or one of the values (True, faLse, yes, no, -1 ….) , this will cause validation errors.

Using our export toolkit?

Creating a visibility element with libflexport.

attributes

[...]
<allAttributes>
  <attributes>
    <attribute>
      <key><![CDATA[value]]></key>
      <values>
        <value><![CDATA[value]]></value>
        <value><![CDATA[value]]></value>
        [...]
      </values>
    </attribute>
    [...]
  </attributes>
</allAttributes>
[...]

<allAttributes> contains 1 <attributes>-tag.
- The <attributes>-tag must NOT have an usergroup-attribute.
<attributes> contains 1+ <attribute>-tags.
<attribute> contains a key/value set with 1 <key>-tag identifying the attribute and 1+ <value>-tags setting the values for the attribute.
Attributes are used in filters, navigation, shopping guides and for search-queries.Here you can find our documentation about filter configuration.
If you use a slider, do not export the values like this: 100 cm. Correct: 100. You can set the unit in the filter configuration in the Findologic customer account. If you export 100 cm it is not possible to use the range slider for this filter, because the range slider is only able to work with numeric values.
We recommend the following as a standard:
- cat: CDATA (e.g. Sneakers_Men an article in the category “Sneakers” and in the subcategory “Men”)
- cat_url: CDATA (e.g. for the category http://www.shop.de/sneakers/men.html the correct cat_url is /sneakers/men.html)
- vendor: CDATA (e.g. Adidas)

Using our export toolkit?

Creating an attribute element with libflexport.

In the attributes following tags are not allowed to be empty:

<attributes>
<attribute>
<key>
<value>

cat_url examples

In order to use Findologic Navigation with Direct Integration, the tag cat_url has to be added with the category path to the <attributes>-tag. If a product is shown in several categories, all paths have to be exported. For example for a product, which is assigned to the following categories …

… these cat_url's-values should be added to the <attributes>-tag.

<allAttributes>
  <attributes>
    <attribute>
      <key><![CDATA[cat_url]]></key>
      <values>
        <value><![CDATA[/presents]]></value>
        <value><![CDATA[/presents/champagne]]></value>
        <value><![CDATA[/wedding-presents]]></value>
        <value><![CDATA[/jacken&maentel]]></value>
        <value><![CDATA[/de/geschenke/champagner]]></value>
        <value><![CDATA[/en/presents/]]></value>
      </values>
    </attribute>
    [...]
  </attributes>
</allAttributes>

cat_url's have to be exported as relative paths.

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

The / at the end of the cat_url needs to be included if the category pages of your shop are ending with a /.

properties

[...]
<allProperties>
  <properties>
    <property>
      <key><![CDATA[value]]></key>
      <value><![CDATA[value]]></value>
    </property>
    <property>
      <key><![CDATA[value]]></key>
      <value><![CDATA[value]]></value>
    </property>
    [...]
  </properties>
  <properties usergroup="">
    <property>
      <key><![CDATA[value]]></key>
      <value><![CDATA[value]]></value>
    </property>
    <property>
      <key><![CDATA[value]]></key>
      <value><![CDATA[value]]></value>
    </property>
    [...]
  </properties>
  [...]
</allProperties>
[...]

Using our export toolkit?

Creating a property element with libflexport.

<allProperties> contains 1+ <properties>-tags, distinguished via the usergroup-attribute.
<properties> contains 1+ <property>-tags.
<property> contains a key/value set with 1 <key>-tag identifying the property and 1 <value>-tag setting the value for the property.
<properties> contains every information irrelevant to the search itself but relevant for displaying the products in the shop.
<properties> can contain a usergroup attribute.
- If usergroup is given in the request, only the properties explicitly exported for this usergroup will be returned
- If a usergroup is given in the request, but no <properties/> are exported for this usergroup, the default <properties/> are returned (ie. the <properties/> without usergroup)
  - Note: The whole <properties>-block without a usergroup is used as default in case no <properties>-block for the requested usergroup exists. In case a <properties>-block exists for the requested usergroup, but a certain <property> is missing, no default-value is available.
Following <property> Keys are not allowed for use:
- ordernumber
- image[0-9]+
- thumbnail[0-9]+
We recommend the following as a standard:
- Novelty: 0/1
- Sale: 0/1
- Free_shipping: 0/1
- Logo: CDATA (e.g. 'http://www.shop.de/logos/vendor_logo.jpg')
- Availability: CDATA (e.g. '<span class=“green”>10</span>')
- Delivery_time: CDATA (e.g. '<span class=“yellow”>5-9 days</span> if ordered today')
- Rating_value: Numeric (e.g. '4.5'; what is the rating of the product)
- Rating_amount: Numeric (e.g. '10'; how many people rated the product)
- Discount: Numeric (e.g. '10' to display ”-10 %“ or '12.90' to display ”-12,90 €“)
- Basic_rate_price: Numeric (e.g. '99.9')
- Basic_rate_unit: CDATA (e.g. '100g')

In the properties following tags are not allowed to be empty:

<properties>
<property>
<key>
<value>

Attributes and properties in XML-feed

Main differences between attributes and properties is:

Attributes are filters, properties are additional information on search results
Attributes can have several values, properties can have only one value.

Here is map of HTML-template with one product in results at the right side and filters at the left side.

If customer needs some information (like color/size/rating) in filters and in product-card in results as well, he should provide both: property and attribute.

Using variants in search results

[...]
<variants>
	<variant id="variant_3">
...
	</variant>
	<variant id="variant_4">
...
	</variant>
</variants>
[...]

A <variant> can contain the following data. This data is structured the same as for its parent.

ordernumber, required
attributes, required
name, optional
price, optional. (In case it is not set, the parent price will be used as default.)
groups, optional.
overriddenPrice, optional
properties, optional
urls, optional
images, optional

No other fields are allowed.

Currently it is not possible to use variants and usergroups together. Variants only work without usergroups. But using groups is still possible. So filtering by group is working fine.

Using our export toolkit?

Creating a variant element with libflexport.

Example XML

XML export, XML

Table of Contents

Findologic XML 2.0 export format

Overview

Wrapper

item

ordernumbers

names

summaries

descriptions

prices

overriddenPrices

urls

images

keywords

groups

Using group to set the visibility of items

Using usergroups to set the visibility of single information relevant for a returned item

Recommendation

bonuses

salesfrequencies

dateaddeds

sorts

visibilities

attributes

cat_url examples

properties

Attributes and properties in XML-feed

Using variants in search results

Example XML