Table of Contents

Findologic XML 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
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.

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
<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
<usergroups> Visibility of article, i.e. only visible to the exported usergroups 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
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>
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>
[...]
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>
[...]
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>
[...]
Using our export toolkit?

Creating a name element with libflexport.

summaries

[...]
<summaries>
  <summary><![CDATA[]]></summary>
  <summary usergroup=""><![CDATA[]]></summary>
  [...]
</summaries>
[...]
Using our export toolkit?

Creating a summary element with libflexport.

descriptions

[...]
<descriptions>
  <description><![CDATA[]]></description>
  <description usergroup=""><![CDATA[]]></description>
  [...]
</descriptions>
[...]
Using our export toolkit?

Creating a description element with libflexport.

prices

[...]
<prices>
  <price><![CDATA[]]></price>
  <price usergroup=""><![CDATA[]]></price>
  [...]
</prices>
[...]
It is important that you use “.” as decimal seperator.
Using our export toolkit?

Creating a price element with libflexport.

urls

[...]
<urls>
  <url><![CDATA[]]></url>
  <url usergroup=""><![CDATA[]]></url>
  [...]
</urls>
[...]
Using our export toolkit?

Creating an url element with libflexport.

images

[...]
<allImages>
  <images>
    <image><![CDATA[]]></image>
  </images>
  <images usergroup="">
    <image><![CDATA[]]></image>
  </images>
  [...]
</allImages>
[...]
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>
[...]
Using our export toolkit?

Creating a keyword element with libflexport.

usergroups

[...]
<usergroups>
  <usergroup><![CDATA[]]></usergroup>
  <usergroup><![CDATA[]]></usergroup>
  [...]
</usergroups>
[...]

Using usergroups to set the visibility of items

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

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.

Recommendation

Using our export toolkit?

Creating an <usergroup> element with libflexport.

bonuses

[...]
<bonuses>
  <bonus><![CDATA[]]></bonus>
  <bonus usergroup=""><![CDATA[]]></bonus>
  [...]
</bonuses>
[...]
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>
[...]
Using our export toolkit?

Creating a salesfrequency element with libflexport.

dateaddeds

[...]
<dateAddeds>
  <dateAdded><![CDATA[]]></dateAdded>
  <dateAdded usergroup=""><![CDATA[]]></dateAdded>
  [...]
</dateAddeds>
[...]
Using our export toolkit?

Creating a dateadded element with libflexport.

sorts

[...]
<sorts>
  <sort><![CDATA[]]></sort>
  <sort usergroup=""><![CDATA[]]></sort>
  [...]
</sorts>
[...]
Using our export toolkit?

Creating a sort element with libflexport.

visibilities

[...]
<visibilities>
  <visibile><![CDATA[]]></visibile>
  <visibile usergroup=""><![CDATA[]]></visibile>
  [...]
</visibilities>
[...]
Using our export toolkit?

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>
[...]
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.

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:

  1. Attributes are filters, properties are additional information on search results
  2. 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 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 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" encoding="UTF-8"?>
<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>
        <ordernumbers usergroup="PN3enVBRVH0To(/">
          <ordernumber>577LTK</ordernumber>
        </ordernumbers>
      </allOrdernumbers>
      <names>
        <name>Adidas Sneaker</name>
        <name usergroup="LNrLF7BRVJ0toQ==">Adidas Men's Sneaker</name>
        <name usergroup="PN3enVBRVH0To(/">Adidas Women's Sneaker</name>
      </names>
      <summaries>
        <summary>A cool and fashionable sneaker</summary>
        <summary usergroup="LNrLF7BRVJ0toQ==">A cool and fashionable sneaker for men</summary>
        <summary usergroup="PN3enVBRVH0To(/">A cool and fashionable sneaker for women</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 comes in various sizes and colors.</description>
        <description usergroup="PN3enVBRVH0To(/">With this women's sneaker you will walk in style. It comes in various sizes and colors.</description>
      </descriptions>
      <prices>
        <price>44.8</price>
        <price usergroup="LNrLF7BRVJ0toQ==">42.9</price>
        <price usergroup="PN3enVBRVH0To(/">39.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>
        <url usergroup="PN3enVBRVH0To(/">https://www.store.com/sneakers/women/adidas.html</url>
      </urls>
      <allImages>
        <images>
          <image>https://www.store.com/images/277KTL.png</image>
        </images>
        <images usergroup="LNrLF7BRVJ0toQ==">
          <image>https://www.store.com/images/277KTL.png</image>
        </images>
        <images usergroup="PN3enVBRVH0To(/">
          <image>https://www.store.com/images/577LTK.png</image>
        </images>
      </allImages>
      <allAttributes>
        <attributes>
          <attribute>
            <key>cat</key>
            <values>
              <value>Sneakers_Men</value>
              <value>Sneakers_Women</value>
              <value>Specials_Sale</value>
            </values>
          </attribute>
          <attribute>
            <key>cat_url</key>
            <values>
              <value>/sneakers/men</value>
              <value>/sneakers/women</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>
        <keywords usergroup="PN3enVBRVH0To(/">
          <keyword>fashion</keyword>
          <keyword>cool product</keyword>
          <keyword>women</keyword>
        </keywords>
      </allKeywords>
      <usergroups>
        <usergroup>LNrLF7BRVJ0toQ==</usergroup>
        <usergroup>PN3enVBRVH0To(/</usergroup>
      </usergroups>
      <bonuses>
        <bonus>3</bonus>
        <bonus usergroup="LNrLF7BRVJ0toQ==">5</bonus>
        <bonus usergroup="PN3enVBRVH0To(/">5</bonus>
      </bonuses>
      <salesFrequencies>
        <salesFrequency>15</salesFrequency>
        <salesFrequency usergroup="LNrLF7BRVJ0toQ==">5</salesFrequency>
        <salesFrequency usergroup="PN3enVBRVH0To(/">8</salesFrequency>
      </salesFrequencies>
      <dateAddeds>
        <dateAdded>2020-05-30T09:30:10</dateAdded>
        <dateAdded usergroup="LNrLF7BRVJ0toQ==">2020-07-30T00:00:00</dateAdded>
        <dateAdded usergroup="PN3enVBRVH0To(/">2020-06-30T00:00:00</dateAdded>
      </dateAddeds>
      <sorts>
        <sort>5</sort>
        <sort usergroup="LNrLF7BRVJ0toQ==">7</sort>
        <sort usergroup="PN3enVBRVH0To(/">6</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>44.8</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>44.8</value>
          </property>
        </properties>
        <properties usergroup="PN3enVBRVH0To(/">
          <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>44.8</value>
          </property>
        </properties>      
      </allProperties>
    </item>
  </items>
</findologic>
,