1. Einleitung
Die Suchfunktion ist nur eine von vielen Funktionen, die Kunden an eine Online-Präsenz stellen. Sie muss intuitiv bedienbar sein und relevante Ergebnisse liefern.
SmartSearch bündelt diese Anforderungen mit einer hochperformanten Suchlösung, die auf umfangreichen Webseiten einsetzbar ist. Durch eine hohe Trefferqualität und einen optimalen Suchkomfort werden Kunden auf der Webseite gebunden.
Mittels SmartSearch Connect lassen sich die Funktionalitäten von SmartSearch und FirstSpirit optimal verbinden. Mit sehr wenig Aufwand ist es möglich die mittels FirstSpirit erstellte Webseite mit einer performanten Suche auszustatten. Aktualisierungen und neue Inhalte finden sich direkt in den Suchergebnissen wieder.
Das Ziel des Moduls ist eine einfache und schnelle Verknüpfung zwischen diesen Systemen. Dabei wurde darauf geachtet, so wenig Installations- und Konfigurationsaufwand wie möglich zu erzeugen. Aus diesem Grund wurde bewusst darauf verzichtet mit jedem FirstSpirit-Projekt kompatibel zu sein. So ist es aktuell noch nicht möglich Projekte zu verwenden, in denen Fragmente verwendet werden.
2. Installation und Konfiguration
Für die Verwendung der Funktionalitäten des SmartSearch Connect-Moduls ist die Installation und Konfiguration unterschiedlicher Komponenten notwendig. Die dafür erforderlichen Schritte werden in den nachfolgenden Unterkapiteln erläutert.
2.1. Konfiguration der Projekt-Komponente
Für den Einsatz von SmartSearch Connect ist eine projektspezifische Konfiguration notwendig. Diese wird über die Projekt-Komponente vorgenommen, die dem Projekt hinzuzufügen ist. Öffnen Sie dafür den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften → Projekt-Komponenten.
Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Selektieren Sie nach dem Klicken auf [Hinzufügen] die SmartSearch Connect ProjectApp und bestätigen Sie die Auswahl mit [OK]. Die Projekt-Komponente wird anschließend der Liste im Hauptpanel hinzugefügt und muss im nächsten Schritt noch konfiguriert werden (vgl. Abbildung Auswahl zur Konfiguration der Projekt-Komponente). Selektieren Sie dafür den Eintrag in der Liste und öffnen Sie den zugehörigen Konfigurationsdialog über [Konfigurieren] (vgl. Abbildung Dialog der Projekt-Komponente).
Zunächst kann hier ein Name für die in SmartSearch automatisch zu erzeugenden Datengenerator und PreparedSearch konfiguriert werden. Wird das Feld leer gelassen, so wird der aktuelle Projektname hierfür herangezogen.
Über den sich darunter befindlichen Knopf Initialize in SmartSearch! können der oben konfigurierte Datengenerator und die PreparedSearch zu jedem Zeitpunkt erstellt werden ("Initialisierung"). Auch hier wird der aktuell gespeicherte Projektname herangezogen, sollte obiges Feld leer sein. Das Ergebnis des Aufrufs kann dem Serverlog entnommen werden, da dort die Initialisierung ausgelöst wird.
In der Konfiguration des Projektes ist es notwendig den URL Creator einzustellen, der auch in Generierung eingestellt ist, die für die Erstellung der Webseite verwendet wird. Neben dem URL Creator muss der in der Generierung verwendete Prefix angegeben werden. Nur so kann sichergestellt werden, dass die URLs der Suchtreffer auch auf die entsprechenden Seiten verweisen.
In der Liste Media types kann ausgewählt werden, welche Medien mittels SmartSearch Connect an SmartSearch übertragen werden sollen. In dieser Liste werden nur Dateiendungen textuell verarbeitbarer Dateien angezeigt, welche im Projekt vorhanden sind. Diese Liste muss also während der Nutzung eines Projekts um neue Endungen ergänzt werden.
Standardmäßig liefert SmartSearch die URLs der Originalauflösungen für Bilder. Wenn URLs in anderen Auflösungen verwendet werden sollen, können diese in den Bildauflösungen auswählt werden. SmartSearch Connect stellt nicht sicher, dass die Bilder von außen zugänglich sind. Dies muss im Projekt sichergestellt werden.
| Es werden nur Medien verarbeitet, die in FirstSpirit referenziert sind. So wird sichergestellt, dass diese von außen erreichbar sind. |
Über die Liste Image resolutions können Auflösungen ausgewählt werden, für die bei Bildern URLs generiert werden sollen. Die URL zur Originalauflösung wird immer generiert. Sollen weitere Auflösungen verwendet werden, beispielsweise für eine Vorschau bei den Suchtreffern, dann muss diese Auflösung in der Liste ausgewählt werden. Auch die Verwendung von Remote-Media ist möglich. Dafür müssen die in der Liste ausgewählten Auflösungen auch im Remote Projekt vorhanden sein. Der Prefix für die URLs von Remote-Media wird aus der Konfiguration des Remote Projektes (ServerManager für das Projekt, in dem die Medien eingebunden werden) gezogen.
Die Dokumente in SmartSearch enthalten standardmäßig nur die Metadaten des entsprechenden Elements in FirstSpirit. Sollen die Metadaten vererbt werden, dann muss dazu der Haken bei Inherit meta data gesetzt werden.
| Die Vererbung bezieht sich nicht auf den Mechanismus um Elemente vom SmartSearch Index auszuschließen. An dieser Stelle greift die Vererbung in der Struktur auch ohne diese Konfiguration. |
Die SmartSearch API bietet zwei verschiedene Versionen der API. Die beiden Versionen unterscheiden sich hauptsächlich in der Verarbeitung der Hierarchien aus FirstSpirit.
Unter Configure API Request kann die Verwendung eines extra Ausgabekanals konfiguriert werden. Eine detailliertere Beschreibung dazu ist im Kapitel SmartSearch Ausgabekanal zu finden.
2.2. SmartSearch Objekt Vorlagensatz
SmartSearch Connect wurde so konzipiert, dass möglichst wenig Schritte notwendig sind, um Inhalte aus einem FirstSpirit Projekt in SmartSearch verarbeiten zu können. Es ist auf diesem Weg schnell möglich die ersten Ergebnisse im Index zu sehen. Für projektspezifische Anpassungen kann das Groovy Script des Datengenerators in SmartSearch verwendet werden. Wenn dieses aber nicht ausreichend ist, bietet SmartSearch Connect die Möglichkeit mittels eines Vorlagensatzes ein SmartSearchObject an SmartSearch zu übergeben. Dazu muss in dem entsprechendem FirstSpirit Projekt ein Vorlagensatz angelegt werden. Dieser muss zwingend SmaSeJSON heißen und als Zieldatei-Erweiterung JSON haben. Der Vorlagensatz kann mit der üblichen Vorlagensyntax gestaltet werden. Es muss sichergestellt sein, dass es sich bei der Ausgabe um ein valides JSON handelt, dass dem SmartSearchObject Anforderungen entspricht.
In der Konfiguration der SmartSearch Connect ProjectApp kann eingestellt werden, wie das SmartSearch Object verwendet werden soll. Es gibt dabei drei Optionen: * Use only FormData - Hier bei wird das SmartSearchObject nicht verwendet. * Use FormData and SmartSearchObject - Hierbei werden sowohl das SmartSearchObject als auch die FormData Informationen beachtet. * Use only SmartSearchObject - Hier bei wird nur das SmartSearchObject beachtet.
| Die Informationen aus dem exemplarischen JSON, die in den Zeilen 2-13 stehen, werden immer an SmartSearch gesendet (inklusive Metadaten). Die Informationen die unterhalb von page stehen, werden nur übermittelt, wenn die FormData Informationen zur Übermittlung ausgewählt ist. Bei Datensätze verhält es sich etwas anders. Hier gibt es keine page sondern FormData liegt direkt auf der root-Ebene. |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
"fsType":"PageRef",
"name":"smart_thermostats",
"displayName":"Thermostate Übersicht",
"identifier":"d8c8bd3f-3268-44aa-aa38-91c192b3ce8c",
"uid":"smart_thermostats",
"uidType":"SITESTORE_LEAF",
"fsTitle":"Thermostate Übersicht",
"fsToJsonVersion":"1.2",
"fsUrl":"https://www.smartliving.com/Produkte/Thermostate-Übersicht.html"
"metaFormData":{
},
"page":{
"fsType":"Page",
"name":"prod_overview",
"displayName":"Produktübersicht",
"identifier":"c8efd7ab-4744-412f-b58c-7273b2855790",
"translated":true,
"uid":"prod_overview",
"uidType":"PAGESTORE",
"template":{
"fsType":"PageTemplate",
"name":"Standard",
"displayName":"Standard",
"identifier":"1b6428fc-f157-44ce-a3b9-ceb8800a2476",
"uid":"standard",
"uidType":"TEMPLATESTORE"
},
"formData":{
"pt_add_sections":{
"fsType":"CMS_INPUT_TOGGLE",
"name":"pt_add_sections",
"value":true
},
"pt_create_section":{
"fsType":"FS_BUTTON",
"name":"pt_create_section",
"value":{
}
},
.
.
.
},
"fsGenericApiVersion":"v1",
"smartSearchDocument":{
"title":"Produktübersicht"
}
}
2.2.1. SmartSearchObject Anforderungen
Über das SmartSearch Object ist es möglich Inhalte in ein SmartSearch Connect Dokument zu schreiben. Dabei überschreiben Inhalte, die im SmartSearchObject stehen die Inhalte, die z.B. im FormData stehen. Das nachfolgende Beispiel zeigt einen Vorlagensatz eines Pagetemplates. In diesem Fall würde der title des SmartSearch Dokumentes mit dem title aus dem Pagetemplate überschrieben.
{
"title":"$CMS_VALUE(pt_title)$"
$CMS_VALUE(#global.getPage().getBodyByName("content"))$
}Damit SmartSearch das JSON verarbeiten kann, darf dieses nur eindimensional aus Strings und String Arrays bestehen. Eine Verschachtelung ist nicht möglich.
| SmartSearch Connect verarbeitet Datensätze anders als dies aus FirstSpirit bekannt ist. Die Datensätze werden eigenständig übermittelt ohne in ein Seitentemplate eingebunden zu sein. Daher kann es sein, dass das JSON eines Datensatzes in der Vorschau anders aussieht als das JSON, dass an SmartSearch gesendet wird. |
2.3. Ausschließen von Elementen aus dem SmartSearch Index
SmartSearch Connect schreibt standardmäßig alle Elemente in den SmartSearch Index. Soll die Möglichkeit gegeben sein, dass dies direkt in FirstSpirit unterbunden werden kann, dann ist es notwendig das Projekt zu erweitern.
2.3.1. Ausblenden von Seiten
Für das Ausblenden von Seiten ist es notwendig, die Metadaten um eine Eingabekomponente zu erweitern. Es muss sich dabei um ein CMS_INPUT TOGGLE handeln und diese muss den Namen md_smartsearch_noindex haben.
<CMS_INPUT_TOGGLE name="md_smartsearch_noindex" type="radio" hFill="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Hide"/>
</LANGINFOS>
<ON>
<LANGINFO lang="*" label="On" description="Hide this site from search index."/>
</ON>
</CMS_INPUT_TOGGLE>Werden die Metadaten so wie oben beschrieben eingebunden, werden sie z.B. auch im Inhaltebereich angezeigt. Beachtet werden sie aber nur im Strukturbereich. Deshalb ist es sinnvoll mittels einer Regel die Metadaten nur im Strukturbereich anzuzeigen.
<RULE>
<WITH>
<EQUAL>
<PROPERTY name="STORETYPE" source="#global"/>
<TEXT>sitestore</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY name="VISIBLE" source="md_smartsearch_noindex"/>
</DO>
</RULE>| Das Ausblenden von Seiten funktioniert auch über Ordner. Hierbei ist zu beachten, dass Änderungen an Ordnern nur nach einer Vollgenerierung oder der Änderung einer betroffenen Seite greift. |
2.3.2. Ausblenden von Datensätzen
Da Datensätze nicht über Metadaten verfügen, ist es hier notwendig den entsprechenden Tabellen im Datenbank-Schema eine zusätzliche Spalte vom Typ boolean hinzuzufügen. Wichtig ist dabei, dass die Spalte smartsearch_noindex heißen muss. Damit die Daten der Spalte auch gepflegt werden können, muss der Tabellenvorlage noch eine entsprechende Eingabekomponente hinzugefügt werden.
| Seiten und Datensätze, die bereits im Index vorhanden sind aber durch ein Setzen des entsprechenden Feldes ausgeblendet werden sollen, werden erst nach einer Vollgenerierung aus dem Index gelöscht. Das Eventing greift an dieser Stelle nicht. |
2.3.3. Entfernen von Daten über SmaSeJSON-Templating
Die Standardbehandlung von First Spirit Content erzeugt Feldnamen und Feldwerte in Abhängigkeit von der Struktur und der Benennung der genannten Elemente. In einigen Fällen kann es notwendig sein, diese automatisch generierten Inhalte zu entfernen, z. B. wenn der Inhalt aus rechtlichen Gründen oder aus Gründen des Datenschutzes nicht durchsucht oder gar indiziert werden soll. Wenn die SmaSeJSON-Vorlage aktiv ist, können Feldwerte aus den automatisch generierten Daten entfernt werden, indem ein leerer String im entsprechenden JSON übergeben wird.
Der Code im folgenden Beispiel hat als Ergebnis der SmaSeJSON-Vorlage zur Folge, dass alle zuvor automatisch generierten Werte für das Feld FS_pt_supersecret nicht indiziert werden:
{
"FS_pt_supersecret" : ""
}| Einige Felder und Feldwerte werden auf der SmartSearch-Seite generiert und aktualisiert, nachdem die Entität vom FirstSpirit-Modul gesendet wurde. Änderungen dieser Werte in der SmaSeJSON-Vorlage werden möglicherweise nicht in den indizierten Daten wiedergegeben. Wenn Änderungen nicht reflektiert werden, ist es ratsam, die GroovyScript Enhancer der entsprechenden Datengeneratoren sowie die SmartSearch-Dokumentation in Bezug auf Felder und Feldwerte zu überprüfen. |
3. Vollgenerierung
Zur initialen Befüllung von SmartSearch ist eine Vollgenerierung notwendig. Beim Hinzufügen der Projekt-Komponente wird in der Auftragsverwaltung der Projektkonfiguration automatisch ein neuer Auftrag angelegt und unter den Aktionen der Eintrag [SmartSearch push] hinzugefügt.
Durch Ausführen dieses Auftrages wird in SmartSearch ein neuer Datengenerator und eine neue Prepared Search mit dem Präfix FS_ und dem konfigurierten Namen angelegt.
Nach einer erfolgreichen Vollgenerierung werden alle Daten, die vor der Vollgenerierung bereits im Index waren und durch diese nicht aktualisiert wurden gelöscht. Es sind somit nur noch aktuelle Dokumente im Index.
4. Teilgenerierung
Um SmartSearch auch nach einer Teilgenerierung auf dem neuesten Stand zu halten ist es notwendig, den Auftrag der Teilgenerierung um eine Aktion vom Typ Skript zu erweitern. Dieses Skript muss hinter der eigentlichen Generierung eingebunden werden und folgenden Inhalt haben:
#! executable-class
com.espirit.smartsearch.initialdeployment.PushPreviousGenerationExecutable
5. Eventing
Um die Inhalte in SmartSearch so aktuell wie möglich zu halten, gibt es neben den Generierungen das Eventing. Hierbei werden Änderungen (Anlegen, Löschen und Editieren von Elementen) direkt nach der Freigabe der Elemente innerhalb FirstSpirit an SmartSearch geschickt. Damit eventgetriebene Übertragen der Daten in Richtung SmartSearch, durch redaktionelle Anpassungen im ContentCreator ausgelöst werden, muss der genutzte Workflow bestimmte Anforderungen erfüllen. Konkret muss der Workflow z.B. abhängige FirstSpirit-Elemente freigeben, sobald ein Objekt freigegeben wird. Bei Freigabe einer Seite müssen z.B. die abhängigen Seitenreferenzen freigegeben werden. Um dieses Verhalten herzustellen, kann das Modul BasicWorkflows verwendet werden.
6. Medien
Bei der Verarbeitung von Medien durch SmartSearch Connect unterscheidet sich das Vorgehen bei Bildern und Dateien. Daher wird in den folgenden Kapiteln das jeweilige Vorgehen genauer beschrieben.
6.1. Bilder
SmartSearch Connect bzw. SmartSearch verarbeitet keine Bilder. Es werden also keine Informationen aus Bildern gezogen. Bilder werden meist als Vorschau für Suchergebnisse benötigt. Hierfür ist in der Regel eine bestimmte Auflösung vorgesehen. Welche Auflösungen für URLs benötigt werden kann in der Auswahl zur Konfiguration der Projekt-Komponente eingestellt werden.
| Zu den Standardfeldern in SmartSearch gehört das Feld thumbnail. Dieses wird durch SmartSearch Connect nicht befüllt. Für ein Thumbnail ist es somit notwendig die entsprechende Auflösung in der Konfiguration auszuwählen und die entsprechende Auflösung in den Suchtreffern zu verwenden. |
6.2. Dateien
SmartSearch verarbeitet Dateien in Formaten wie PDFs und DOCX. Dabei werden die Dateien selber nicht von SmartSearch Connect an SmartSearch geschickt. Für die Verarbeitung werden die Dateien von SmartSearch heruntergeladen. Die entsprechende URL wird von SmartSearch Connect übermittelt. Für dieses Vorgehen ist es somit zwingend notwendig, dass die Dateien für SmartSearch erreichbar sind.
| Wird das Eventing verwendet, kann dies dazu führen, dass die Verarbeitung einer Datei angestoßen wird, bevor die Datei für SmartSearch erreichbar ist. Für Dateien ist somit ein regelmäßiges Volldeployment notwendig. |
| In einem Remote Projekt muss bei der Verwendung von Dateien folgendes beachtet werden: Die Erzeugung von Events für Dateien erfolgt in diesem Fall nur bei Erstellung bzw. Bearbeitung der Dateien im Remote Projekt. Bei einer Vollgenerierung wiederum werden nur die Dateien aus dem Ausgangsprojekt beachtet. Für diesen Fall wird empfohlen auch für das Remote Projekt SmartSearch Connect zu konfigurieren und den dadurch erzeugten Datengenerator über eine PreparesSearch mit dem Ausgangsprojekt zusammenzuführen. |
7. Datensätze
SmartSearch Connect überträgt Datensätze an SmartSearch über eine eingetragene Vorschauseite am entsprechenden Template. Gibt es mehrere Templates für einen Datensatz-Typen wird automatisch das Template mit den meisten Eingabefeldern gewählt. Die Datensätze werden dann unabhängig von einem potentiellen Ausschluss der Vorschauseite (siehe Ausblenden von Seiten) in den Index übertragen. Der Hintergrund hier ist, dass Datensätze auch bei einer Single-Page Application z.B. im Zusammenspiel mit dem CaaS in die Suche eingebaut werden können. Sollen bestimmte Datensätze nicht in den Index übertragen werden, kann dies mittels Ausblenden von Datensätzen oder Entfernen von Daten über SmaSeJSON-Templatingverhindert werden. Zudem empfehlen wir, Content-Projektionsseiten mittels Ausblenden von Seiten immer aus der Indexierung auszuschließen, um doppelte Daten im Index zu vermeiden. Andernfalls befinden sich Datensätze mehrfach im Index. Auch Content-Projektionen, die als Übersichtsseiten dienen, sind meist nicht relevant für die Suche.
| Aus technischen Gründen ist es notwendig, dass das Template, das zu einem Datensatz gehört eine Vorschauseite angegeben ist. Dies impliziert eine Verwendung des Datensatzes. Die entsprechende Seite sollte aber mittels Ausblenden von Seiten vom Suchindex ausgeschlossen werden. |
8. Was geschieht in SmartSearch?
Sendet ein FirstSpirit-Projekt mit dem exemplarischen Namen Demo das erste Mal Daten in Richtung SmartSearch, so werden dort die benötigen Elemente automatisch angelegt:
Dies beinhaltet zum einen ein Datengenerator vom Typ API mit dem Namen FS_Demo:
Zum anderen wird eine PreparedSearch mit dem Namen FS_Demo angelegt.
An dieser Prepared Search ist der zugehörige Datengenerator bereits ausgewählt:
8.1. Datengenerator
Mit Ausnahme der kurzen Momente in denen Daten an SmartSearch übertragen werden, steht der durch das Modul erzeugten Datengeneratoren dauerhaft auf dem Status API Bereit. An dieser Stelle sei erwähnt, das ein Statuswechsel im Cockpit nicht sichtbar ist wenn die Datenübertragung sehr schnell abläuft und nicht viel Zeit in Anspruch nimmt. Des Weiteren ist der Empfang der Daten im Log nur mit dem Loglevel DEBUG sichtbar. Dieser kann in der Datei logback-spring.xml wie folgt konfiguriert werden:
<logger name="de.arithnea.haupia.datageneration.crawler.api.reactive" level="DEBUG"/>Datengeneratoren vom Typ API können weder gestartet noch gestoppt werden, da sie permanent auf Daten warten.
Daten die an den Datengenerator übertragen werden, werden nach 30 Sekunden in den Solr-Index übertragen. Dieser Zeitraum kann (zu Testzwecken) mit Hilfe der Umgebungsvariable API_CRAWLER_COMMIT_WITHIN auf dem SmartSearch-System auf z.B. eine Sekunde reduziert werden. Diese Konfiguration ist jedoch nicht für den produktiven Einsatz vorgesehen:
export API_CRAWLER_COMMIT_WITHIN=10008.2. PreparedSearch
Die vorkonfigurierte PreparedSearch ist direkt nach dem Empfang der Daten per REST abrufbar. An ihr können wie gewohnt z.B. Facetten gepflegt werden. Die Facette fsType enthält den Typ der aus FirstSpirit exportierten Entität:
Eine bekannte und wichtige Konfiguration zur Nutzung der PreparedSearch ist das Hinzufügen bestimmter Felder (z.B. der Link zur Ressource) zur Ausgabe, so dass beim Abfragen der Schnittstelle das Ergebnis mit der von FirstSpirit generierten URL ausgegeben werden:
| Die Liste der Feldnamen pro Datengenerator im Cockpit ist gecached. Es kann einige Minuten dauern bis der Cache gefüllt wird, nachdem die ersten Daten an SmartSearch übertragen wurden. |
8.3. Datenverarbeitung
Wie im Kapitel Konfiguration der Projekt-Komponente beschrieben, kann in der Konfiguration der ProjectApp unter dem Punkt Configure API Request die zu verwendende API Version ausgewählt werden. Die gewählte Version hat Einfluss auf die Art und Weise in der die aus FirstSpirit übertragenen Daten durch SmartSearch verarbeitet werden. Bei beiden Versionen werden textliche Inhalte im content zusammengefasst. Der Unterschied liegt unter anderem in der Verarbeitung von Eingabekomponenten, die als Facetten verwendet werden können. Dazu zählen z.B. Datumsfelder und Dropdowns.
Die Art und Weise, wie die Struktur aus FirstSpirit in ein flaches SmartSearch Dokument umgewandelt wird, ist der Hauptunterschied zwischen den beiden API Versionen, und wird im folgenden Kapitel beschrieben.
8.3.1. API Version V1
Bei der API Version V1 sind die Felder im Dokument wie folgt aufgebaut: FS_L*_NAME. FS_ ist dabei der Prefix um zu verdeutlichen, dass dieses Element aus FirstSpirit kommt. L*_ bildet die Tiefe des Elements in der Struktur bei FirstSpirit ab. Dabei ist * ein numerischer Wert. Der NAME ist der Name der Eingabekomponente. Die Eingabekomponente st_title befindet sich bei FS_L5_st_title dementsprechend auf der 5. Ebene. Die Ebenen sind dabei beispielsweise die Seitenreferenz, die Seite und dort eingehängt ein Absatz.
8.3.2. API Version V2
Bei der API Version V2 beginnen die Felder im Dokument ebenfalls mit einem FS_. Danach folgt aber bereits der Name der Eingabekomponente. Für die Tiefe des Elements werden die Namen der Eingabekomponenten gegebenenfalls kombiniert. Als Trenner dient dabei ein ___. Das Element FS_pt_slider___st_description enthält die Beschreibung, die unterhalb eines Sliders eingehängt ist. Ist der Name nicht eindeutig, weil z.B. der gleiche Absatz mehrfach eingehängt ist, dann werden die Inhalte als multi value gespeichert, sofern der Feldtyp dies zulässt. Diese Verarbeitung ist intuitiver als bei der API Version V1, weil bei dieser die Tiefe nur schwer vorhersagbar ist ohne die genaue Templatestruktur im Projekt und damit die im Hintergrund erzeugte JSON-Datei zu kennen.
| Es wird empfohlen die API Version V2 zu verwenden. Der Fokus der weiteren Entwicklung wird bei dieser Version liegen. |
9. Usecases
In den Kapiteln dieses Abschnittes werden einige Usecases und Best Practises aufgelistet.
9.1. Headless Szenario im Zusammenspiel mit dem CaaS
Bei der Implementierung einer Suchlösung für Headless Portale ist die Behandlung von URLs von Elementen ein wichtiger Aspekt der besondere Aufmerksamkeit erfordert. Die Voraussetzung für alle nachfolgenden Schritte und Maßnahmen ist die Implementierung des Content-as-a-Service (CaaS) mit dem entsprechenden Modul im entsprechenden Projekt.
Der Unterschied bei der Verwendung von SmartSearch in einem Headless Szenario, im Gegensatz zu einer Seitensuche ist, dass das Suchergebnis keine eindeutige URL zurückliefern kann. Für diesen Fall ist die Verwendung der FirstSpirit UUID der bevorzugte Weg. Diese ist bereits in den Daten von SmartSearch und dem CaaS enthalten. Über diese UUID kann der zum Suchtreffer passende Datensatz im CaaS abgefragt werden. Wie diese Datensätze für Suchende aufbereitet wird liegt in diesem Fall im Frontend. Besonders wenn, wie bei der klassischen Ansicht, das Auswählen eines Suchergebnisses auf eine bestimmte Seite führen soll, auf der der Datensatz eingebunden ist.
In der Projektkonfiguration muss zunächst für das Projekt ein anderer 'URLCreator' ausgewählt werden.
Die meisten 'URLCreator’en (z.B. 'Default URLs') erzeugen statische URLs, die die gesamte Webadresse enthalten, während der 'CaaS Connect Url Factory' CaaS-Pfade erzeugt, die sich auf die Position der Inhalte innerhalb der CaaS-Plattform beziehen.
Werden Inhalte bei aktiviertem 'CaaS Connect Url Factory' an SmartSearch übertragen, so enthalten sie im Suchindex im Feld 'link' die entsprechende URLs um die Daten im CaaS abzurufen.
Sollen statische URLs (wie sie z.B. der 'URLCreator' 'Default URLs' generiert) im Suchindex verfügbar sein, so kann alternativ wie im folgenden erläutert vorgegangen werden.
Um am CaaS eine PageRef abzufragen, ist eine folgende URL nötig (vgl. Dokumentation):
https://<tenant>-caas-api.e-spirit.cloud/<tenant>/<project_uuid>.release.content/<page_ref_uuid>.<lang_country>Während diese bei Nutzung der 'CaaS Connect Url Factory' in das Feld 'link' indiziert werden, sind sie bei Nutzung anderer 'URLCreator’en aus verschiedenen Informationsquellen zusammenzusetzen.
Aus der CaaS Modulkonfiguration kann der Part 'https://<tenant>-caas-api.e-spirit.cloud/<tenant>/<project_uuid>.release.content/' entnommen werden: Hierzu im der Projektkonfiguration den Menüpunkt 'Project components' aufrufen und danach die Komponente 'CaaS Connect Project App' aufrufen. Der benötigte Part 'https://<tenant>-caas-api.e-spirit.cloud/<tenant>/<project_uuid>.release.content/' findet sich dort im Feld 'CaaS REST API endpoints' → 'Release Collection API'.
Der Part '<page_ref_uuid>' entspricht der UID aus dem FirstSpirit Context (vgl. Dokumentation). Diese ist als Wert 'identifier' immer in SmartSearch verfügbar, wenn die Daten über SmartSearch Connect übertragen wurden. Im JSON welches von SmartSearch Connect übertragen wird liegt dieses in folgender Form vor:
{
"fsType":"PageRef",
(...)
"identifier":"c8a158a3-2ba3-427c-a7e4-7d41d9844464",
(...)
}Wird eine PageRef freigegeben und somit an SmartSearch übertragen, so ist der Wert 'identifier' in den Daten des entsprechenden Datengenerators verfügbar.
Das Locale welches im Part '<lang_country>' gefordert ist, ist im JSON nicht enthalten, muss also entsprechend zur den übermittelten Daten hinzugefügt werden.
Hierzu muss der JSON Ausgabekanal konfiguriert und aktiviert werden, wie im Abschnitt SmartSearch Objekt Vorlagensatz erläutert. In den Vorlagensatz der entsprechenden Elemente, im folgenden einer 'PageRef', kann das Locale wie folgt hinzugefügt werden:
{
"locale":"$CMS_VALUE(#global.locale)$",
}Wird nun eine PageRef freigegeben und somit an SmartSearch übertragen, so ist der Wert 'locale' in den Daten des entsprechenden Datengenerators verfügbar.
Mit den Informationen aus der Projektkonfiguration und den Daten welche an SmartSearch übertragen wurden kann die PageRef und alle mit ihr verbundenen im CaaS gespeicherten Informationen abgefragt werden.
Hierzu kann eine PreparedSeach in SmartSearch angelegt werden, welche die Felder 'identifier' und 'link' in einem Suchergebnis verfügbar macht. Verbunden mit den Informationen aus der FirstSpirit Projektkonfiguration können so anhand eines Suchergebnisses Inhalte statt per statischer URL an den CaaS APIs abgerufen werden.
10. Bekannte Probleme und Abgrenzungen
In den folgenden Abschnitten werden bekannte Probleme für diese Version aufgelistet.
10.1. FirstSpirit-Projektname
Derzeit sollte der Projektname in FirstSpirit möglichst keine Leerzeichen beinhalten. Während der Export nach SmartSearch mit einem Leerzeichen zwar funktioniert, kann es dennoch zu nicht abschätzbaren Nebeneffekten kommen, da Leerzeichen für Datengenerator- sowie PreparedSearch-Namen nicht zulässig sind.
10.2. Umbenennen von Projekten in FirstSpirit
Um die vom FirstSpirit-Modul in SmartSearch automatisch angelegten Datengeneratoren und PreparedSearches erkennbar zu machen, folgen sie oben genanntem Namensschema.
Dies hat zur Folge, dass das FirstSpirit-Projekt nicht umbenannt werden darf, da SmartSearch diese Anpassung nicht übernehmen kann. Für SmartSearch würden danach übertragene Daten zum Anlegen eines neuen Datengenerators sowie einer neuen PreparedSearch führen, und somit zu einem neuen Index.
10.3. Umbenennen von Auflösungen
In der Konfiguration der Projekt-Komponente können die Auflösungen die von SmartSearch Connect verarbeitet werden ausgewählt werden. Wird der Anzeigename einer Auflösung in FirstSpirit umbenannt, geht die entsprechende Auswahl in der Konfiguration verloren und muss erneut gesetzt werden.
10.4. Filter für Medien
In der Konfiguration der Projekt-Komponente können die Medientypen ("Media types") gepflegt werden, die von SmartSearch verarbeitet werden sollen. Bei dieser Funktion gibt es eine Einschränkung, wenn für ein Medium in verschiedenen Sprachen unterschiedliche Mediumtypen hinterlegt sind. In diesem Fall werden auch Medien übertragen, die nicht Konfiguration hinterlegt sind, wenn in einer anderen Sprache ein Medium vorhanden ist, das übertragen werden soll.
10.5. Verwendung von Medien
Medien, die mittels CMS_INPUT_IMAGEMAP eingebunden werden, werden nicht berücksichtigt. Das Gleiche gilt für Medien, die über FS_INDEX und Media Data Access Plugin (Media DAP) eingebunden werde.
10.6. Medien ohne verarbeitbaren textuellen Inhalt
Werden Medien an SmartSearch übertragen, so kann es geschehen dass SmartSearch aus diesen keinen Text extrahieren kann. Ein Beispiel für ein solches Medium wäre eine PDF Datei in der ausschließlich Bilder vorhanden sind. In diesem Fall würden diese nicht indiziert, da die Medienverarbeitung den Inhalt des Mediums in das Feld 'content' schreibt, welches nicht leer sein darf. Abhilfe kann geschaffen werden, indem ein vorhanderen Inhalt des 'content'-Felds aller Medien mittels eines Groovy Script Enhancers sichergestellt wird. Dies kann zum Beispiel geschehen indem für den Fall eines leeren 'content'-Feldes ein Standardtext oder der Inhalt eines anderen Feldes in das 'content'-Feld kopiert wird.
10.7. Nachträgliches Hinzufügen des noindex Flags im Datenbank-Schema
Wie im Kapitel Ausblenden von Datensätzen beschrieben, bietet SmartSearch Connect die Möglichkeit mittels eines Flags Datensätze aus dem Index auszuschließen. Wird dieses Flag erst nach der ersten Generierung mit einem default Wert hinzugefügt, dann greift dieses erst nach der ersten Änderungen an den betroffenen Datensätzen. Sollten bereits viele Datensätze vorhanden sein ist es somit empfehlenswert diese mittels Skript zu bearbeiten.
10.8. Struktur der Dokumente im SmartSearch Index
Der Aufbau der Dokumente im SmartSearch Index hängen stark von der Struktur des Projektes ab. Daher ist es nicht möglich eine generelle Aussage über die Struktur zu machen. Für das Verständnis, gerade während der Entwicklung, kann es aber sehr hilfreich sein, wenn man die Struktur besser versteht. Da diese auf dem durch FirstSpirit generierten json beruht, können die folgenden Skripte verwendet werden, um an den Aufbau des json zu gelangen. Zum Anwenden im SiteArchitect einen Rechtsklick auf die Seitenreferenz oder den Datensatz machen und dort auf Skript ausführen→Developer Scripts (public)→beanshellconsole. In der erscheinenden Console kann das entsprechende Skript ausgeführt werden.
Für Seitenreferenzen sieht das Skript wie folgt aus:
renderingAgent = context.requireSpecialist(de.espirit.firstspirit.agency.RenderingAgent.TYPE);
templateSource = "$CMS_SET(#global.json.dataRenderDepth, 1)$$CMS_SET(#global.json.formatVersion, 1.2)$$CMS_SET(#global.json.sectionTemplateRendering, false)$$CMS_SET(#global.json.useDefaultHtmlTemplateProvider, true)$$CMS_SET(#global.json.metaDataRendering, true)$$CMS_SET(#global.json.resolveDynamicContent, true)$$CMS_VALUE(json(#global.node))$";
renderObject = renderingAgent.createRenderer(templateSource).linkRoot(e);
jsonOutput = renderObject.render();Für Datensätze kann folgendes Skript verwendet werden:
renderingAgent = context.requireSpecialist(de.espirit.firstspirit.agency.RenderingAgent.TYPE);
templateSource = "$CMS_SET(#global.json.dataRenderDepth, 1)$$CMS_SET(#global.json.formatVersion, 1.2)$$CMS_SET(#global.json.sectionTemplateRendering, false)$$CMS_SET(#global.json.useDefaultHtmlTemplateProvider, true)$$CMS_SET(#global.json.metaDataRendering, true)$$CMS_SET(#global.json.resolveDynamicContent, true)$$CMS_VALUE(json(idProvider))$";
import de.espirit.firstspirit.access.store.Store;
renderObject = renderingAgent.createRenderer(templateSource).linkRoot(e.getProject().userService.getStore(Store.Type.SITESTORE, true));
renderObject.additionalContext("idProvider", e);
jsonOutput = renderObject.render();| Einige Felder, wie beispielsweise die ULR, Links von Bildern und der Titel, werden erst durch das Modul angefügt und sind somit nicht in der Ausgabe der Skripte vorhanden. |
11. Rechtliche Hinweise
SmartSearch Connect ist ein Produkt der e-Spirit AG, Dortmund, Germany.
Für die Verwendung des Modules gilt gegenüber dem Anwender nur die mit der e-Spirit AG vereinbarte Lizenz.
12. Hilfe
Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.