Differences

This shows you the differences between two versions of the page.

--- xml_export_documentation:xml_format [2019/10/01 16:36]
lukas [usergroups]
+++ xml_export_documentation:xml_format [2023/01/25 14:14]
rihad [Using properties for product variants in search results]
@@ Line 1: / Line 1: @@
-===== FINDOLOGIC XML export format =====
+===== Findologic XML export format =====
@@ Line 5: / Line 5: @@
 </note>
-  * 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.
+  * 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.
+  * 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.
+  * Export script can be written with [[https://github.com/findologic/libflexport/wiki#initializing-the-exporter-with-a-specific-type|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: [[https://github.com/FINDOLOGIC/xml-export/blob/master/src/main/resources/findologic.xsd|FINDOLOGIC XML-Schema]]. Check your XML against the scheme and see if your export XML is valid: [[https://www.corefiling.com/opensource/schemaValidate.html]]
+  * The latest XML scheme for validation can be found on Github: [[https://github.com/findologic/xml-export/blob/main/src/main/resources/findologic_20.xsd|Findologic XML-Schema]]. Check your XML against the scheme and see if your export XML is valid: [[https://www.corefiling.com/opensource/schemaValidate.html]]
-<note>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).</note>
+<note>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).</note>
-<note>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"?>'' </note>
+<note>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"?>'' </note>
 <note>**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:** \\
@@ Line 26: / Line 26: @@
 [...]
 <html></pre></html></note>
+<note important>Control characters (**[#x01-#x08]** | **[#x0B-#x0C]** | **[#x0E-#x1F]**) are not allowed in any value of the feed.</note>
+<note important>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.</note>
 ----
@@ Line 32: / Line 37: @@
 ^ Item ^ Short Description ^ Tag required ^ Value required ^ Will be searched ^
 ^**''<?xml version=“...” encoding=“...”?>''**| Specifies the encoding  | Yes | Yes | No |
-^**''<[[#item]] id="">''**| Unique identification number  | Yes | Yes | No |
+^**''<[[#item]] id="">''**| Unique identifier  | Yes | Yes | No |
-^**''<[[#ordernumbers]]>''**| Article number or order number | Yes | No | Yes |
+^**''<[[#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 | No | No |
+^**''<[[#overriddenPrices]]>''**| Current article 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 |
-^**''<[[#usergroups]]>''**| Visibility of article, i.e. only visible to the exported usergroups. see [[xml_export_documentation:xml_format#Calculating the usergroup-hash|how to generate usergrouphashes]] | Yes | No | No |
+^**''<[[#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 |
@@ Line 74: / Line 81: @@
   * ''<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 [[xml_export_documentation:xml_request_and_response|Export]]
   * ''<items>'' may contain 1+ ''<item>''-tags.
+<note important>Due to runtime limitations the XML-export has to be [[https://docs.findologic.com/doku.php?id=xml_export_documentation:xml_request_and_response|paginated]].</note>
+<note important>You have to use double quotes to seperate XML attributes like "count" or "total". Single quotes are not supported at the moment.</note>
 <note tip>**Using our export toolkit?**
@@ Line 118: / Line 129: @@
   * ''<ordernumbers>'' contains 1+ ''<ordernumber>''-tags.
   * ''<ordernumber>'' contains an article-number like internal arcticle number, EAN, ISBN, ...
+<note>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.</note>
 <note tip>**Using our export toolkit?**
@@ Line 253: / Line 266: @@
   * ''<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.
+  * If there is no image for a product, the shop-specific "No Image Available" should be exported.
 <note tip>**Using our export toolkit?**
@@ Line 304: / Line 317: @@
   * ''<usergroup>'' contains 1+ ''<usergroup>''-tags.
   * ''<usergroup>'' contains a usergroup to which the item is visible.
-  * ''<usergroup>'' the usergroup used in the datafeed (e.g.'<name usergroup="employee") has to have the exact same name as the usergroup used as a parameter in the FINDOLOGIC-Snippet.
+  * ''<usergroup>'' 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 usergroups to set the visibility of items ===
@@ Line 332: / Line 345: @@
 === Recommendation ===
   * In case of more than 128 ''<usergroups>'', please contact [[mailto:support@findologic.com|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):
+  * To avoid potential misunderstandings, preferably use alphanumeric values for usergroups (e.g. ''18plus'', ''B2B'').
@@ Line 339: / Line 351: @@
 Creating an ''<usergroup>'' element with [[https://github.com/findologic/libflexport/wiki#usergroup|libflexport]].</note>
-=== 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: ===
-<code php>
-$shopkey = 'A6039131315BE9F868E358D5AC784405';
-$usergroup = 'at_ratedR';
-$hash = base64_encode($shopkey ^ $usergroup); // = 'IEJvQVhFVlVh'
-$usergroup_decoded = ($shopkey ^ base64_decode($hash)); // = 'at_ratedR';
-</code>
-----
 ==== bonuses ====
@@ Line 375: / Line 364: @@
   * ''<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.
 <note>Please note, that the value -1 will be overridden with the value -0.9 in the import.</note>
@@ Line 401: / Line 389: @@
   * ''<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.
-<note>Please note, that negative values will be overridden with the value 0 in the import.</note>
 <note tip>**Using our export toolkit?**
@@ Line 448: / Line 434: @@
   * ''<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.
+  * 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.
+<note tip>**Using our export toolkit?**
+Creating a sort element with [[https://github.com/findologic/libflexport/wiki#sort|libflexport]].</note>
+----
+==== visibilities ====
+<code xml>
+[...]
+<visibilities>
+  <visibile><![CDATA[]]></visibile>
+  <visibile usergroup=""><![CDATA[]]></visibile>
+  [...]
+</visibilities>
+[...]
+</code>
+  * ''<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.
 <note tip>**Using our export toolkit?**
@@ Line 482: / Line 492: @@
   * ''<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.[[customer_account:filter_configuration|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.
+  * 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")
@@ Line 503: / Line 513: @@
 ==== 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.
+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 ...
@@ Line 681: / Line 691: @@
 ----
+==== Using variants in search results ====
+<code xml>
+[...]
+<variants>
+	<variant id="variant_3">
+...
+	</variant>
+	<variant id="variant_4">
+...
+	</variant>
+</variants>
+[...]
+</code>
+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
+<note important>No other fields are allowed.</note>
+<note tip>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.</note>
 ==== Example XML ====
@@ Line 696: / Line 734: @@
         <ordernumbers usergroup="LNrLF7BRVJ0toQ==">
           <ordernumber>377KTL</ordernumber>
+        </ordernumbers>
+        <ordernumbers usergroup="PN3enVBRVH0To(/">
+          <ordernumber>577LTK</ordernumber>
         </ordernumbers>
       </allOrdernumbers>
@@ Line 701: / Line 742: @@
         <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's comes in various sizes and colors.</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==">45.9</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>
@@ Line 724: / Line 770: @@
         <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>
@@ Line 732: / Line 781: @@
             <values>
               <value>Sneakers_Men</value>
+              <value>Sneakers_Women</value>
               <value>Specials_Sale</value>
             </values>
@@ Line 739: / Line 789: @@
             <values>
               <value>/sneakers/men</value>
+              <value>/sneakers/women</value>
               <value>/specials/sale</value>
             </values>
@@ Line 766: / Line 817: @@
           <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>cHBw</usergroup>
+        <usergroup>PN3enVBRVH0To(/</usergroup>
       </usergroups>
       <bonuses>
         <bonus>3</bonus>
         <bonus usergroup="LNrLF7BRVJ0toQ==">5</bonus>
+        <bonus usergroup="PN3enVBRVH0To(/">5</bonus>
       </bonuses>
       <salesFrequencies>
-        <salesFrequency>5</salesFrequency>
+        <salesFrequency>15</salesFrequency>
         <salesFrequency usergroup="LNrLF7BRVJ0toQ==">5</salesFrequency>
+        <salesFrequency usergroup="PN3enVBRVH0To(/">8</salesFrequency>
       </salesFrequencies>
       <dateAddeds>
-        <dateAdded>2002-05-30T09:30:10</dateAdded>
+        <dateAdded>2020-05-30T09:30:10</dateAdded>
-        <dateAdded usergroup="LNrLF7BRVJ0toQ==">2002-05-30T00:00:00</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>
@@ Line 812: / Line 872: @@
           <property>
             <key>Basic_rate_price</key>
-            <value>99.9</value>
+            <value>44.8</value>
           </property>
         </properties>
@@ Line 838: / Line 898: @@
           <property>
             <key>Basic_rate_price</key>
-            <value>89.9</value>
+            <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>

xml_export_documentation:xml_format

Differences

Documentation overview

Useful links