Integrating FACT-Finder Search via XML

When integrating via XML you must convert the search query parameters into a URL and receive the search result back in a defined XML format. The result is obtained by submitting a URL such as:

$stringEscapeUtils.escapeHtml($body)

Result structure

<ff xsi:noNamespaceSchemaLocation="schema/7.2/ffresult.xsd">
   <searchStatus>resultsFound</searchStatus>
   <articleNumberSearchStatus>noArticleNumberSearch </articleNumberSearchStatus>
   <searchTimedOut>false</searchTimedOut>
   <fieldRoles>
      <fieldRole role="displayProductNumber">products_id</fieldRole>
      <fieldRole role="ean">products_ean</fieldRole>
      ...
   </fieldRoles>
   <productsPerPageOptions default="12" selected="24">
      <option value="12">
         <searchParams>...searchParams...</searchParams>
      </option>
      ...
   </productsPerPageOptions>  
   <searchControlParams>
      ...
   </searchControlParams>
   <searchParams>
     <searchPhrase>animation dvd</searchPhrase>
     <filters>
       <filter name="Category" exclude="false">DVD</filter>
     </filters>
     <channel>de</channel>
     <productsPerPage>20</productsPerPage>
     <followSearch>9840</followSearch>
   </searchParams>
   <breadCrumbTrail>
      <item no="0" type="search" value="dvd">
         <searchParams>...</searchParams>
      </item>
      ...
   </breadCrumbTrail>
   <singleWordSearch>
      <item nr="0" word="dvd" count="23">
         <record ...>...</record>
         ...
      </item>
      ...
   </singleWordSearch>
   <campaigns> ... </campaigns>
   <asn> ... </asn>
   <paging pageCount="3" currentPage="1" productsPerPage="20">
      <searchParams>...</searchParams>
      <settings>
         <linkCount>9</linkCount>
         <nextCaption>&gt;&gt;</nextCaption>
         <previousCaption>&lt;&lt;</previousCaption>
      </settings>
   </paging>
   <sorting>
      <sort description="sort.relevanceDescription" method="desc" selected="true">
         <searchParams>...</searchParams>
      </sort>
    </breadCrumbTrail>
   </sorting>
   <results count="42" bestSimi="9900" worstSimi="8210">
      <record nr="0" position="1" id="71004851" relevancy="99.0">
         <field name="Description">...here is the description...</field>
         <field name="Title">products title</field>
         ...
      </record>
      ...
   </results>
</ff>

An XSD schema description file exists to allow you to generate processing code (see http://your.server/FACT-Finder/ffresult.xsd). Many elements have a searchParams tag − this contains the search parameters associated with this step in URL format.

The articleNumberSearchStatus tag shows whether or not an article number search was carried out. Possible values here are resultsFound, nothingFound or noArticleNumberSearch.

If a timeout occurred during the search, the value true will be returned in the searchTimedOut tag, otherwise the value false is returned. A search that has timed out may not contain all matching products.

Status information

The value carried in the searchStatus tag indicates whether or not a result was found. Possible values are resultsFound, nothingFound and errorOccured.

Das Tag articleNumberSearchStatus zeigt auf, ob eine Artikelnummernsuche durchgeführt wurde oder nicht. Mögliche Werte sind hier resultsFound, nothingFound oder noArticleNumberSearch.

Falls während der Suche eine Zeitüberschreitung aufgetreten ist, wird in dem Tag searchTimedOut der Wert true zurückgeliefert, andernfalls steht hier der Wert false. Eine Suche, die die Zeit überschritten hat, beinhaltet unter Umständen nicht alle passenden Produkte.

searchParams Block

This block contains the search parameters that were passed. The query parameters for visualisation of the response data can be deduced from this section, and therefore you can also check that the parameters were correctly recognised.

fieldRoles-Block

Felder der FACT-Finder-Produktdatenbank können Rollen haben. In dieser Struktur berichtet FACT-Finder darüber welche Felder für welche Feld-Rollen konfiguriert wurden. Mögliche Rollen sind:

brand – Hersteller-Feld.
campaignProductNumber – Artikelnummer, über die Produkte aus dem Kampagnen-Manager referenziert werden.
deeplink – URL zur Produktseite.
description – Beschreibung des Produkts.
displayProductNumber – Artikelnummer, die zur Anzeige verwendet wird.
ean – EAN
imageUrl – URL zum Bild des Produkts.
price – Preis-Feld.
productName – Name des Produkts.
trackingProductNumber – Artikelnummer, die für des Tracking verwendet wird.
masterArticleNumber – Artikelnummer des Haupt-Artikels bei Produktvariationen.

Der Wert des XML-Elements ist der jeweilige Feldname. Ein Feld kann mehrfach vorkommen, wenn ihm mehrere Rollen zugewiesen wurden.

productsPerPageOptions Block

This block lists the options defined in the configuration regarding the number of products that can be displayed per page. The default option (default) and the currently selected option (selected) are passed as attributes. The option child blocks also contain the search parameters used to select the corresponding option.

breadCrumbTrail Block

This block lists the user’s previous steps (for example, in a search query, the filters that were set). It is normally used to create a breadcrumb trail that allows the user to jump back to a previous point.

<breadCrumbTrail>
   <item nr="0" type="search" value="12">
      <searchParams>
         the url for the initial search
      </searchParams>
   </item>
   <item nr="1" type="filter" value="DVD" associatedFieldName="Kategorie">
      <searchParams>
         the url for the filter
      </searchParams>
   </item>
</breadCrumbTrail>

singleWordSearch-Block

This section is only displayed if the option has been activated to search for the individual words of the search request in the event of no hits or poor results. In such cases, the individual words of the search request are separated and searched for individually, so that the user can view the results of these searches. This feature is disabled by default, for performance reasons.

Each component that would return a result is returned as an item element, which has as its attributes an index (nr), the word (word) and the expected number of hits (count). You can also display a specific number of preview products for the individual terms, which are then returned as the respective record tags within the item tag. The structure is identical to the tag in records.

<singleWordSearch>
   <item nr="0" word="dvd" count="23">
      <record ...>...</record>
      ...
   </item>
   ...
</singleWordSearch>

campaigns Block

This block is only contained in the result if you have activated the Campaign Manager module and a campaign is available for the search query that was submitted. You can find more detailed information about this block in the documentation for the associated module.

asn Block

See the After Search Navigation section of the documentation platform.

paging-Block

This block contains information regarding the page of the search results on which you are currently located (attribute currentPage) and how many pages there are (pageCount). The page count begins with 1. The maximum number of products that can be shown on a page is also indicated (productsPerPage). The <settings> block contains values that are configured in FACT-Finder Back Office. These include settings such as the number of paging links to be displayed in the details (<linkCount>, for example “1 2 3 4 5 6 7 8 … 13”). <nextCaption> contains the text for the link that points to the next page. <previousCaption> describes the link for the previous page.

If you want to call up another page, you only need to attach the desired page number to the URL specified in searchParams.

<paging pageCount="3" currentPage="1" productsPerPage="20">
   <searchParams>
 the url which can be used for the paging. You only have to add the page number at the end
   </searchParams>
   <settings>
      <linkCount>9</linkCount>
      <nextCaption>&gt;&gt;</nextCaption>
      <previousCaption>&lt;&lt;</previousCaption>
   </settings>
</paging>

sorting-Block

If there are multiple sort criteria, they are listed as sort elements in this block. The attribute name contains either the value Relevancy or the corresponding field name. description contains the name of the criterion, which can be shown on the interface. The remaining attributes provide information on the sort order (method) and whether the criterion has been selected (selected).

<sorting>
   <sort description="sort.relevanceDescription" method="desc" selected="true">
      <searchParams>
         the url for choosing the sorting
      </searchParams>
   </sort>
   <sort name="Price" description="sort.priceAsc" method="asc" selected="false">
      <searchParams> params again </searchParams>
   </sort>
   ...
</sorting>

results-Block

This section contains the details of the articles that have been found on this page. The count attribute indicates how many articles were found in total.

Each record tag represents an article. These have the attributes for the index (nr), the absolute position of the record inside the search result (position), the record ID (id) and similarity to the search term (relevancy). If you have not activated the idsOnly parameter, each record also contains the field information for the corresponding product. This information is returned in the child field element. The field name is given as an attribute (name) and the field content the value of the tag.

<results count="42">
   <record nr="0" position="1" id="71004851" relevancy="100.0">
      <field name="EAN">4011846012801</field>
      <field name="Category">DVD</field>
      <field name="Description"> here is the description of this product </field>
      <field name="Title">products title</field>
   </record>
   ...
</results>

Page Contents