Integration der FACT-Finder Suche per XML

Bei der XML-Integration müssen Sie die Parameter der Suchanfrage in eine URL konvertieren und erhalten das Suchergebnis als Rückgabe in einem definierten XML-Format. Sie erreichen die Rückgabe beispielsweise unter folgender URL:

$stringEscapeUtils.escapeHtml($body)

Rückgabestruktur

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

Für das Rückgabeformat existiert eine XSD-Beschreibungsdatei, sodass Verarbeitungscode generiert werden kann (siehe schema-Pfad in der Rückgabe). Bei vielen Elementen finden Sie ein searchParams-Tag, dieses beinhaltet die für diesen Schritt zugehörigen Suchparameter in URL-Form.

Statusinformationen

Der Wert, den Sie unter dem Tag searchStatus finden, gibt an, ob ein Ergebnis gefunden wurde oder nicht. Mögliche Werte sind resultsFound, nothingFound oder 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

Dieser Block beinhaltet die übergebenen Suchparameter. Aus diesem Abschnitt lassen sich zum einen die Anfrage-Parameter für die Darstellung herauslesen, zum anderen kann hierdurch überprüft werden, ob die Parameter korrekt erkannt wurden.

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

In diesem Block werden die in der Konfiguration definierten Optionen aufgelistet, wie viele Produkte pro Seite angezeigt werden dürfen. Als Attribute werden die Standardoption (default) und die aktuell ausgewählte Option (selected) übermittelt. Die untergeordneten option-Blöcke selbst enthalten auch noch die Suchparameter, um die entsprechende Option auszuwählen.

breadCrumbTrail-Block

In diesem Block werden die bisherigen Schritte des Benutzers (z. B.: Suchanfrage, gesetzte Filter) aufgelistet. Dieser Abschnitt wird im Normalfall für die Erstellung eines Brotkrümelpfads verwendet. Dies bietet dem Benutzer die Möglichkeit, zu einem früheren Punkt zurückzuspringen.

<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

Dieser Block wird nur angezeigt, wenn aktiviert ist, dass bei keinen Treffern oder schlechten Ergebnissen nach den einzelnen Worten der Suchanfrage gesucht werden soll. Die einzelnen Wörter der Suchanfrage werden in diesen Fällen aufgetrennt, und es wird einzeln nach ihnen gesucht, sodass der Benutzer sich das Ergebnis von diesen anzeigen lassen kann. Dieses Features ist aus Performancegründen standardmäßig deaktiviert.

Jeder Bestandteil, der Ergebnisse liefern würde, wird als item-Element zurückgeliefert, dieses besitzt als Attribute einen Index (nr), das Wort (word) und die zu erwartende Trefferanzahl (count). Zudem ist es möglich, für die einzelnen Begriffe eine bestimmte Anzahl von Vorschauprodukten anzeigen zu lassen, diese werden optional als jeweiliger record-Tag unter dem item-Tag zurückgeliefert. Der Aufbau ist identisch mit dem Tag unter records.

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

campaigns-Block

Dieser Block ist nur in der Rückgabe enthalten, wenn Sie das Modul Kampagnen Manager aktiviert haben und für die abgesetzte Suche eine Kampagne vorhanden ist. Genaueres zu diesem Block finden Sie in der Integrationsdokumentation des Moduls.

asn-Block

Informationen hierzu finden Sie in der Integrationsdokumentation „After Search Navigation“.

paging-Block

In diesem Block finden Sie Informationen darüber, auf welcher Seite des Suchergebnisses Sie sich befinden (Attribut currentPage) und wie viele Seiten es gibt (pageCount). Die Seitenzählung beginnt mit 1. Zudem wird angegeben, wie viele Produkte maximal auf einer Seite dargestellt werden (productsPerPage). Der <settings>-Block enthält Werte, die im FACT-Finder Backoffice konfiguriert wurden. Hier finden Sie die Einstellung, wie viele Paging-Links im Detail angezeigt werden sollen (<linkCount>, Beispiel: „1 2 3 4 5 6 7 8 … 13“). <nextCaption> enthält den Text für den Link, der zur nächsten Seite führt. <previousCaption> beschreibt den Link für die vorhergehende Seite.

Wenn Sie eine weitere Seite aufrufen wollen, so müssen Sie lediglich die gewünschte Seitenzahl an die URL unter searchParams anhängen.

<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

Falls es mehrere Sortierkriterien gibt, werden diese als sort-Elemente in diesem Block aufgelistet. Im Attribut name finden Sie entweder den Wert Relevancy oder den entsprechenden Feldnamen. description ist der Name des Kriteriums, dieser kann auf der Oberfläche angezeigt werden. Die restlichen Attribute geben Aufschluss über die Sortierreihenfolge (method) und ob das Kriterium gewählt ist (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

In diesem Abschnitt werden die Details zu den gefundenen Artikeln auf dieser Seite zurückgeliefert. Das Attribut count gibt an, wie viele Artikel insgesamt gefunden wurden.

Jedes record-Tag stellt einen Artikel dar. Dieser hat als Attribute einen Index (nr), die absolute Position des Datensatzes im Suchergebnis (position), die Datensatz-ID (id) und die Ähnlichkeit zum Suchbegriff (relevancy). Wenn Sie den idsOnly-Parameter nicht aktiviert haben, enthält ein record zudem die Feldinformationen des Produktes. Diese werden im darunterliegenden field-Element zurückgegeben. Der Feldname ist hierbei ein Attribut (name) und der Feldinhalt der Wert des Tags.

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

Auf dieser Seite