export_patterns:xml
  • If your are using XML-export for the data synchonization 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 XML-export has to be provided as direct link to the XML-file 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 /> 
[…]

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 No 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 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.

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.

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, …

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.

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

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

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.

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.

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. The type thumbnail is used in the Smart Suggest.
  • If there is no image for a product, the shop-specific “No Image Available” image has to be exported.

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.

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):

Calculating the usergroup-hash

The usergroup-hash is composed of two components:

  • the shopkey (e.g. ABCD0815)
  • The combined usergroups (z.B. 'at_ratedR')

These components are put together with xor and base64 and thus can be decoded.

Example:

$shopkey = 'ABCD0815';
$usergroup = 'at_ratedR';
$hash = base64_encode($shopkey ^ $usergroup); // = 'NDEmNgEN'
 
$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.

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.

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

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.

attributes

[...]
<allAttributes>
  <attributes>
    <attribute>
      <key><![CDATA[]]></key>
      <values>
        <value><![CDATA[]]></value>
        <value><![CDATA[]]></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.
  • 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)
    • brand: CDATA (e.g. Adidas)

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>
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 /.
In the attributes following tags are not allowed to be empty:
  • <attributes>
  • <attribute>
  • <key>
  • <value>

properties

[...]
<allProperties>
  <properties>
    <property>
      <key><![CDATA[]]></key>
      <value><![CDATA[]]></value>
    </property>
    <property>
      <key><![CDATA[]]></key>
      <value><![CDATA[]]></value>
    </property>
    [...]
  </properties>
  <properties usergroup="">
    <property>
      <key><![CDATA[]]></key>
      <value><![CDATA[]]></value>
    </property>
    <property>
      <key><![CDATA[]]></key>
      <value><![CDATA[]]></value>
    </property>
    [...]
  </properties>
  [...]
</allProperties>
[...]
  • <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
    • 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:

  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"?>
<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>brand</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/brand.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/brand.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>