xml_export_documentation:xml_format
This is an old revision of the document!
FINDOLOGIC XML format
- 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.
- You can either write your own export script, provide a completely finished XML-file for the import, or use a plugin provided by FINDOLOGIC.
- 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
<?xml version=“1.0” encoding=“UTF-8”?>
[…] <summaries /> <descriptions /> <usergroups /> […]
Overview
Item | Short Description | Tag required | Value required | Will be searched |
---|---|---|---|---|
<item id=“”> | Unique identification number | Yes | Yes | No |
<ordernumbers> | Article number or order number | 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 |
<urls> | URL to the article page, must be absolute | Yes | No | No |
<images> | URL to the article image, must be absolute. Type “thumbnail” is used in the FINDOLOGIC Smart Suggest. | Yes | No | No |
<keywords> | Keywords linked to current article | Yes | No | Yes |
<usergroups> | Visibility of article, i.e. only visible to the exported usergroups. see how to generate usergrouphashes | 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 |
<attributes> | Article categories and attributes. Will be filters | Yes | No | Yes, also filterable |
<properties> | Additional information of article to be shown on search result listing | Yes | No | No |
Attributes and properties in XML-feed | ||||
Using properties for product variants in search results |
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 attributeversion
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.
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 (nousergroup
-attribute) or limited to a single usergroup via theusergroup
-attribute. The general information is only shown if there is no specific information for the usergroup of the specific user.
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, …
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.
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>.
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>.
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 format99.99
.
“.”
as decimal seperator.
Creating a price 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 leadinghttp[s]
, which leads the user to the product-detail-page.
Creating an url element with libflexport.
images
[...] <allImages> <images> <image><![CDATA[]]></image> <image type="thumbnail"><![CDATA[]]></image> </images> <images usergroup=""> <image><![CDATA[]]></image> <image type="thumbnail"><![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” image has to be exported.
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.
Creating a keyword element with libflexport.
usergroups
[...] <usergroups> <usergroup><![CDATA[]]></usergroup> <usergroup><![CDATA[]]></usergroup> [...] </usergroups> [...]
<usergroups>
contains 1+<usergroup>
-tags.<usergroup>
contains a usergroup to which the product is visible.- If the
<usergroup>
-tag is set in the search-request, only products matching the group is returned. - By using the
<usergroup>
-tag you can set specific images, keywords, etc. (see in the documentation, if specific tags can be used with usergroups) for specified usergroups. - In case of more than 128 usergroups, please contact support@findologic.com, in order to adjust default settings.
- The value in the CDATA-block of the
<usergroup>
-tag will be encoded as described below to prevent a manipulation of the search-requests (e.g. R-rating):
Creating an usergroup element with libflexport.
Calculating the usergroup-hash
The usergroup-hash is composed of two components:
- the shopkey (e.g.
A6039131315BE9F868E358D5AC784405
) - The combined usergroups (z.B. 'at_ratedR')
These components are put together with xor
and base64 and thus can be decoded.
Example:
$shopkey = 'A6039131315BE9F868E358D5AC784405'; $usergroup = 'at_ratedR'; $hash = base64_encode($shopkey ^ $usergroup); // = 'IEJvQVhFVlVh' $usergroup_decoded = ($shopkey ^ base64_decode($hash)); // = 'at_ratedR';
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.- If you have product pushing enabled in your customer login, be aware that these values will override the current values at the concerned products in the bonus field.
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.
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 is2002-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
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
<salesFrequency>
-values, please contact our support team. - You should not use negative values as
<sort>
-values.
Creating a sort 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 anusergroup
-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
)
Creating an attribute element with libflexport.
<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
and sub-cat_url's
for the main- and sub-categories, that an article is assigned to.
/
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> [...]
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 ausergroup
attribute.- If
usergroup
is given in the request, only the properties explicitly exported for thisusergroup
will be returned - If a
usergroup
is given in the request, but no<properties/>
are exported for thisusergroup
, the default<properties/>
are returned (ie. the<properties/>
withoutusergroup
)- 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')
<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.
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:
- All color-variants displayed for parent (master)-product.
- While hovering over the variant picture - appropriate image should be displayed.
- By click on a color-variant or on an image the page of the product with the right color should be opened.
How the XML 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:
[...] <allProperties> <properties> <property> <key>variants</key> <value><![CDATA[ { "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" } } ]]></value> </property> </properties> </allProperties> [...]
Example XML
- findologic.xml
<?xml version="1.0"?> <findologic version="1.0"> <items start="10" count="1" total="30"> <item id="01120c948ad41a2284ad9f0402fbc7d"> <allOrdernumbers> <ordernumbers> <ordernumber>277KTL</ordernumber> <ordernumber>4987123846879</ordernumber> </ordernumbers> <ordernumbers usergroup="LNrLF7BRVJ0toQ=="> <ordernumber>377KTL</ordernumber> </ordernumbers> </allOrdernumbers> <names> <name>Adidas Sneaker</name> <name usergroup="LNrLF7BRVJ0toQ==">Adidas Men's Sneaker</name> </names> <summaries> <summary>A cool and fashionable sneaker</summary> <summary usergroup="LNrLF7BRVJ0toQ==">A cool and fashionable sneaker for men</summary> </summaries> <descriptions> <description>With this sneaker you will walk in style. It's available in green and blue.</description> <description usergroup="LNrLF7BRVJ0toQ==">With this men's sneaker you will walk in style. It's comes in various sizes and colors.</description> </descriptions> <prices> <price>44.8</price> <price usergroup="LNrLF7BRVJ0toQ==">45.9</price> </prices> <urls> <url>https://www.store.com/sneakers/adidas.html</url> <url usergroup="LNrLF7BRVJ0toQ==">https://www.store.com/sneakers/mens/adidas.html</url> </urls> <allImages> <images> <image>https://www.store.com/images/277KTL.png</image> <image type="thumbnail">https://www.store.com/images/thumbnails/277KTL.png</image> </images> <images usergroup="LNrLF7BRVJ0toQ=="> <image>https://www.store.com/images/277KTL.png</image> <image type="thumbnail">https://www.store.com/images/thumbnails/377KTL.png</image> </images> </allImages> <allAttributes> <attributes> <attribute> <key>cat</key> <values> <value>Sneakers_Men</value> <value>Specials_Sale</value> </values> </attribute> <attribute> <key>cat_url</key> <values> <value>/sneakers/men</value> <value>/specials/sale</value> </values> </attribute> <attribute> <key>vendor</key> <values> <value>Adidas</value> </values> </attribute> <attribute> <key>color</key> <values> <value>green</value> <value>blue</value> </values> </attribute> </attributes> </allAttributes> <allKeywords> <keywords> <keyword>fashion</keyword> <keyword>cool product</keyword> </keywords> <keywords usergroup="LNrLF7BRVJ0toQ=="> <keyword>fashion</keyword> <keyword>cool product</keyword> <keyword>mens</keyword> </keywords> </allKeywords> <usergroups> <usergroup>LNrLF7BRVJ0toQ==</usergroup> <usergroup>cHBw</usergroup> </usergroups> <bonuses> <bonus>3</bonus> <bonus usergroup="LNrLF7BRVJ0toQ==">5</bonus> </bonuses> <salesFrequencies> <salesFrequency>5</salesFrequency> <salesFrequency usergroup="LNrLF7BRVJ0toQ==">5</salesFrequency> </salesFrequencies> <dateAddeds> <dateAdded>2002-05-30T09:30:10</dateAdded> <dateAdded usergroup="LNrLF7BRVJ0toQ==">2002-05-30T00:00:00</dateAdded> </dateAddeds> <sorts> <sort>5</sort> <sort usergroup="LNrLF7BRVJ0toQ==">7</sort> </sorts> <allProperties> <properties> <property> <key>sale</key> <value>1</value> </property> <property> <key>novelty</key> <value>0</value> </property> <property> <key>logo</key> <value>http://www.shop.de/vendor.png</value> </property> <property> <key>availability</key> <value><![CDATA[<span style="color: green;">3 days</span>]]></value> </property> <property> <key>old_price</key> <value>99.9</value> </property> <property> <key>Basic_rate_price</key> <value>99.9</value> </property> </properties> <properties usergroup="LNrLF7BRVJ0toQ=="> <property> <key>sale</key> <value>0</value> </property> <property> <key>novelty</key> <value>0</value> </property> <property> <key>logo</key> <value>http://www.shop.de/vendor.png</value> </property> <property> <key>availability</key> <value><![CDATA[<span style="color: green;">3 days</span>]]></value> </property> <property> <key>old_price</key> <value>99.9</value> </property> <property> <key>Basic_rate_price</key> <value>89.9</value> </property> </properties> </allProperties> </item> </items> </findologic>