1. Einleitung

Dieses Dokument zur Fehlerbehebung soll Ihnen helfen, verschiedene Fehlercodes zu verstehen und zu beheben, die bei der Verwendung von FirstSpirit Connect for Commerce auftreten können.

Fehlercodes dienen als wertvolle Anhaltspunkte, um zugrundeliegende Probleme in Software, Hardware oder Systemen zu identifizieren und zu beheben.
Die folgende Tabelle enthält Fehlercodes mit einer kurzen Beschreibung und möglichen Lösungsansätzen.

Bitte beachten Sie, dass dieses Dokument eine Reihe von gängigen Fehlercodes behandelt aber nicht alle Fehler, die auftreten können, enthält.

2. Fehlercodes

Code Beschreibung Mögliche Lösungsansätze

0000

Unbekannter Fehler.

1010

URL existiert bereits.

Verwenden Sie eine andere URL, die noch nicht verwendet wurden.

1020

Vorlage ist nicht zugewiesen.

Überprüfen Sie ihre Vorlagenzuweisung in der Bridge. Die verwendeten FirstSpirit Vorlagen müssen mit den Vorlagen des Shop-Systems übereinstimmen.
Siehe Vorlagenzuweisungs-Beispiel.

1030

Feld ist nicht eindeutig.

Der Eingabewert wird bereits verwendet. Hinterlegen Sie einen anderen Eingabewert für das entsprechende Feld.

1040

Pflichtfeld ist nicht ausgefüllt.

Geben Sie einen Eingabewert für das fehlende Pflichtfeld an.

2010

Seite existiert bereits in FirstSpirit.

Überprüfen Sie, ob die Seite im CaaS bereits existiert.

2020

Vorlage ist nicht zugewiesen.

Überprüfen Sie die Referenznamen der Seitenvorlagen im SiteArchitekten mit der Vorlagenzuweisung aus der Bridge Konfiguration. Im Referenzprojekt sind aktuell contentpage, content, homepage, landingpage, product und category als Vorlagen zugelassen.

2030

Ungültiger Seitentyp.

Verwenden Sie product, category oder content als type im Payload beim Erstellen einer neuen Shop-getriebenen Seite.

2040

Falsch formatierte displayNames.

Überprüfen Sie das Format von displayNames im Payload beim Erstellen einer Shop-getriebenen Seite. Das korrekte Format finden Sie im Create Page Unterkapitel unter Use Cases in der Frontend API Dokumentation.

2050

Ein notwendiger Parameter fehlt.

Überprüfen Sie, ob die Anfrage alle notwendigen Parameter enthält beim Erstellen einer Shop-getriebenen Seite. Die notwendigen Parameter finden Sie im Create Page Unterkapitel unter Use Cases in der Frontend API Dokumentation.

3010

FirstSpirit kann sich nicht mit der Bridge verbinden.

Öffnen Sie die Projekt-Komponenten` im ServerManager und überprüfen Sie den Eingabewert für das Feld Bridge API URL in der FirstSpirit Connect for Commerce - Project Configuration.

3020

FirstSpirit erhält 401 von der Bridge.

Öffnen Sie die Projekt-Komponenten im ServerManager und überprüfen Sie die Eingabewerte für die Felder Benutzername und Passwort in der FirstSpirit Connect for Commerce - Project Configuration.

3050

FirstSpirit kann sich nicht mit der ContentCreator Extension verbinden.

Öffnen Sie die Projekt-Komponenten im ServerManager und überprüfen Sie den Eingabewert für das Feld ContentCreator-Extension in der FirstSpirit Connect for Commerce - Project Configuration.

8010

Frontend API Server kann sich nicht mit dem CaaS verbinden.

Überprüfen Sie die hinterlegte CaaS URL Ihres Backend-Services, welcher das frontend-api-server Modul beinhaltet. In unserer Referenzimplementierung finden Sie die Konfiguration unter config/default.yaml für die caasURL Variable.

Die korrekte CaaS URL können Sie unter Projekt-Komponenten im ServerManager in der CaaS Connect Project App einsehen.

Stellen Sie außerdem sicher, dass Ihre CaaS Instanz, zum Beispiel mittels Postman, unter der angegebenen URL erreichbar ist. Sollte dies nicht der Fall sein, wenden Sie sich bitte an unseren Technical Support.

8020

Frontend API Server erhält 401 vom CaaS.

Überprüfen Sie den hinterlegten CaaS API-Schlüssel, die Projekt UUID und die Tenant ID Ihres Backend-Services, welcher das frontend-api-server Modul beinhaltet. In unserer Referenzimplementierung finden Sie die Konfiguration unter config/default.yaml für die apiKey, projectID und tenantID Variablen.

Den korrekten CaaS API-Schlüssel, die Projekt UUID sowie die Tenant ID können Sie unter Projekt-Komponenten im ServerManager in der CaaS Connect Project App einsehen.

8030

Frontend API Server kann sich nicht mit dem Navigation Service verbinden.

Überprüfen Sie die hinterlegte Navigation Service URL Ihres Backend-Services, welcher das frontend-api-server Modul beinhaltet. In unserer Referenzimplementierung finden Sie die Konfiguration unter config/default.yaml für die navigationServiceURL Variable.

Die korrekte Navigation Service URL können Sie unter Projekt-Komponenten im ServerManager in der Navigation Project Configuration einsehen.

Stellen Sie außerdem sicher, dass Ihre Navigation Service Instanz, zum Beispiel mittels Postman, unter der angegebenen URL erreichbar ist. Sollte dies nicht der Fall sein, wenden Sie sich bitte an unseren Technical Support.

8040

Frontend API Server erhält 401 vom Navigation Service.

Überprüfen Sie die hinterlegte Projekt UUID Ihres Backend-Services, welcher das frontend-api-server Modul beinhaltet. In unserer Referenzimplementierung finden Sie die Konfiguration unter config/default.yaml für die projectID Variable.

Die korrekte Projekt UUID können Sie entweder unter Projekt-Komponenten im ServerManager in der CaaS Connect Project App oder Navigation Project Configuration einsehen.

8050

Absatz kann mittels TPP nicht anlegt werden.

Überprüfen Sie, ob die Seite bereits in FirstSpirit existiert. In diesem Fall muss die bereits existierende Seite aus dem CaaS gelöscht werden.

8060

Seite wird nach Erstellung nicht im CaaS gefunden.

Überprüfen Sie, ob die Seite im CaaS angelegt wurde und existiert. Ist dies nicht der Fall muss das CaaS-Deployment überprüft werden. Stellen Sie sicher, dass Ihre CaaS Instanz, zum Beispiel mittels Postman, erreichbar ist und die CaaS Konfiguration im Backend-Service valide ist.

8070

Fehlender Parameter in Anfrage an den Frontend API Server für findPage.

Stellen Sie die benötigten Parameter im Payload bereit. Diese sind unter FindPageParams in der Frontend API Dokumentation einsehbar.

8080

Fehlender Parameter in Anfrage an Frontend API Server für fetchNavigation.

Stellen Sie die benötigten Parameter im Payload bereit. Diese sind unter FetchNavigationParams in der Frontend API Dokumentation einsehbar.

8090

Seite kann aus unbekannten Gründen nicht angelegt werden.

3. Mögliche Auswirkungen bei angepassten Formularfeld-Bezeichnungen

In FirstSpirit werden die für eine Shop-Seite relevanten Daten in Formularfeldern hinterlegt, deren Bezeichnungen sich – wie im Getting-Started-Dokument beschrieben – flexibel anpassen lassen.

Wird die Umbenennung dieser Formularfelder jedoch unvollständig oder fehlerhaft durchgeführt, können verschiedene Fehlfunktionen auftreten. Einige davon werden im Folgenden erläutert.

3.1. Fehlende Aktualisierung von Seitenvorlagen & Erzeugung einer Seite über die Frontend API

Damit das Anlegen einer Seite über die Frontend API reibungslos verläuft, müssen die relevanten Einstellungen sowohl im Frontend-API-Server als auch im Connect for Commerce FirstSpirit-Modul korrekt aufeinander abgestimmt sein.

Kommt es in FirstSpirit bei der Suche nach einer Seite zu einer Abweichung zwischen der im Formularfeld verwendeten Bezeichnung und dem im Template bzw. Content in CaaS hinterlegten Namen, kann die gewünschte Seite nicht gefunden werden. Erfolgt anschließend eine Neuanlage dieser Seite, führt dies zu einer Inkonsistenz:

FirstSpirit legt zwar eine neue Seite samt zugehöriger Seitenreferenz an, die Informationen zur Shop-Seite enthält, berücksichtigt dabei jedoch nicht, ob bereits eine Seite mit dem gleichen Typ und derselben ID existiert. Da eine Filterung nach diesen Werten nur dann möglich ist, wenn die korrekten Formularfeld-Bezeichnungen verwendet werden, entstehen verwaiste Seitenreferenzen.

Das manuelle Anpassen des Seitenobjekts oder ein händisches Eintragen der korrekten Daten ins Template beheben die Inkonsistenz nicht. Stattdessen muss die Seite neu angelegt werden, sobald alle notwendigen Anpassungen vollständig umgesetzt und gegebenenfalls verwaiste Seiten entfernt wurden.

Dieser Umstand verdeutlicht, wie wichtig es ist, alle erforderlichen Anpassungsschritte in einem einzigen Durchlauf umzusetzen. Zwar ist die Reihenfolge der Schritte nicht festgelegt, doch eine schrittweise oder teilweise Migration führt zu den genannten Inkonsistenzen.

3.2. Inkompatibilität der Frontend API

Damit das Feature zuverlässig eingesetzt werden kann, ist eine aktuelle Version der Frontend API erforderlich. Mit Version 1.5.0 wurde das Feature eingeführt. Darüber hinaus muss das Backend korrekt konfiguriert sein. Ausführliche Informationen hierzu finden sich in der Frontend API Documentation.

3.3. CaaS Index-Probleme

Bei Problemen mit dem CaaS-Index kann es hilfreich sein, bestehende Indizes zu entfernen. Dazu sind REST-Anfragen an den konfigurierten CaaS notwendig.

3.3.1. Aktuelle Indizes laden

Die aktuell vorhandenen Indizes können über folgende Abfrage geladen werden. Sollte weder die Verwendung von Node.js noch von Postman möglich sein, reicht die rohe Antwort in nicht formatierter Form aus.

  • Postman

  • cURL

  • HTTP

Wir stellen zur vereinfachung eine Postman-Kollektion bereit. Diese kann durch einen Klick heruntergeladen und importiert werden. In dieser Kollektion werden die benutzereigenen Variablen jeweils in der Collection bzw. in den einzelnen Ordnern gespeichert.

Als Alternative zu Postman kann diese Anfrage auch mit cURL abgeschickt werden. Das unten stehende Beispiel setzt die Anfrage ab und formatiert bei installiertem Node.js zusätzlich das zurückerhaltene JSON, sodass es leserlicher ist.

# Anfrage senden und Antwort speichern
response=$(
  curl -sb \
    --header 'Authorization: Bearer <CaaS API Schlüssel>' \
    --location 'https://<CaaS URL>/<Tenant ID>/<Projekt-UUID>.<preview oder release>.content/_indexes')

log () {
  # JSON-Antwort formatieren
  node -e "console.log(util.inspect($1, {showHidden: false, depth: null, colors: true}))"
}

# Antwort ausgeben
log "$response"

Zur Veranschaulichung die HTTP-Definition:

GET /<Tenant ID>/<Projekt-UUID>.<preview oder release>.content/_indexes HTTP/1.1
Host: <CaaS URL>
Authorization: Bearer <CaaS API Schlüssel>

3.3.2. Bestimmte Indizes löschen

Die Indizes, die für die Formularfelder angelegt wurden, sind eindeutig benannt. Sie folgen dem Schema idx_pageType_pageId_lang_country_with_[Seitentyp-Feldname]_and_[Seiten-ID-Feldname].

Der vor Einführung der Konfigurationsmöglichkeit für Formularfelder angelegte Index besitzt den statischen Namen idx_pageType_pageId_lang_country. Dieser kann, solange er nicht manuell gelöscht wird, weiterhin verwendet werden.

Es ist wichtig, dass keine anderen Indizes gelöscht werden, weil diese für die Performance des Projektes essenziell sind.

# Anfrage senden und Antwort speichern
curl \
  --request DELETE \
  --header 'Authorization: Bearer <CaaS API Schlüssel>' \
  --location 'https://<CaaS URL>/<Tenant ID>/<Projekt-UUID>.<preview oder release>.content/_indexes/<Index-Name>'

4. Automatisierter Verbindungstest

Die Funktion "Verbindungstest" hilft dabei, Bridge-Fehler auf einfache Weise zu identifizieren. Der Verbindungstest-Dialog im ServerManager ist nicht für die automatische Ausführung konzipiert. Repetitives Auslösen ist daher zeitaufwändig und somit nicht immer hilfreich.

Um mögliche Fehler mit der Verbindung von FirstSpirit zur Bridge möglichst schnell erkennen zu können und um Fehler zu entdecken, die nur sporadisch über einen längeren Zeitraum auftreten, stellt Connect for Commerce eine Executable bereit, die wie nachfolgend beschrieben für die geplante bzw. mehrmalige Ausführung eingerichtet werden kann.

4.1. Auftrag konfigurieren

Um einen Auftrag für den Verbindungstest zu erstellen, müssen die folgenden Schritte befolgt werden:

Schritt 1: Erstellen eines Standard-Auftrags:

  1. Öffnen Sie die Auftragsverwaltung im ServerManager.

  2. Klicken Sie auf Hinzufügen.

  3. Wählen Sie Standard-Auftrag und fahren Sie fort.

  4. Der Auftrag sollte einen passenden Namen erhalten, z. B. "Verbindungstest".

  5. Basierend auf den Anforderungen sollten manuelle, einmalige oder regelmäßige Ausführungen konfiguriert werden.

  6. Falls erforderlich, können Benutzerberechtigungen gesetzt werden.

  7. Fahren Sie mit dem nächsten Schritt im Tab Aktionen fort.

automated bridge testing schedule properties de
Abbildung 1. Konfiguration des Auftrags

Schritt 2: Hinzufügen eines Skripts als Aktion

  1. Klicken Sie im Tab Aktionen auf Hinzufügen und wählen Sie Skript ausführen aus der Liste. Klicken Sie auf Übernehmen.

  2. Geben Sie dem Skript einen passenden Namen, z. B. "Verbindungstest".

  3. Das untenstehende Skript kann eingefügt und gemäß den Anweisungen im nächsten Abschnitt angepasst werden.

automated bridge testing schedule actions de
Abbildung 2. Auftragsskript

4.2. Skript-Parameter

Die von Connect for Commerce für den Verbindungstest bereitgestellte Executable arbeitet mit mehreren Parametern. So kann das Verhalten den eigenen Anforderungen angepasst werden.

  • Anfragen (Requests):
    Array von TestConnectionRequest

  • Verzögerung (Delay):
    Die Zeit zwischen jedem Verbindungstest-Aufruf in Sekunden.

  • Gesamtzeit (OverallTime):
    Die Gesamtzeit, nach der das Intervall enden soll, ebenfalls in Sekunden.

Anfragen

Um die durch die Executable durchzuführenden Tests zu konfigurieren, muss ein TestConnectionRequest erstellt werden. Es wird eine HTTP-Methode und der Pfad zum zu testenden Endpunkt benötigt. Die Basis-URL der Bridge-Konfiguration wird hierbei übernommen - siehe Beispiel:

requests.add(TestConnectionRequest.withParams("HEAD", "/categories/tree"));

In einem Durchlauf werden alle Testfälle parallel ausgeführt. Fügt man mehr Testfälle hinzu, erhöht dies die Anzahl der pro Durchlauf innerhalb des geplanten Zeitfensters durchgeführten Tests. Dadurch können mehrere Endpunkte in einem einzigen Durchlauf getestet werden. Danach wird der eingestellte Delay-Wert abgewartet und es beginnt ein neuer Durchlauf.

Verzögerung (Delay)

Das Intervall zwischen dem Start jeder Testrunde. In jedem Durchlauf führt die Executable alle konfigurierten Anfragen aus.

Dabei wird die benötigte Zeit für ein Request nicht im Intervall berücksichtigt. So wird sichergestellt, dass jeder Durchlauf nach der exakt gewünschten Zeit anfängt. Dennoch wird jeder Schritt erst einmal abgeschlossen, bevor einen neuen Durchlauf angefangen wird.

Gesamtzeit (OverallTime)

Die Gesamtzeit legt die Gesamtdauer des Tests fest. Dies definiert das Zeitfenster, in dem neue Anfragen gestartet werden. Nach Ablauf dieses Zeitrahmens, mit einem zusätzlichen Puffer von 10 Sekunden, wird der Prozess beendet. Dieser Puffer gibt der letzten Anfrage bis zu 10 Sekunden Zeit, um abgeschlossen zu werden. Falls die letzte Anfrage weniger Zeit benötigt, wird der Prozess sofort nach Erhalt des Ergebnisses gestoppt und der Test ist beendet.

4.3. Zusammenführung der Skript-Elemente

Mit diesen Informationen kann das folgende Skript an die spezifischen Anforderungen angepasst werden.

Zur Lastminimierung erlaubt die Executable maximal 100 Durchläufe mit einem Delay von maximal 10 Minuten. Der Delay darf aus demselben Grund auch nicht kürzer als 2 Sekunden gesetzt werden. Dies ist der Rückfall-Wert für einen nicht explizit angegebenen Delay oder falls dieser kleiner als 2 Sekunden angegeben ist.
Auftragsskript zum Aufruf des Verbindungstests 
import com.crownpeak.firstspirit.ecom.connect.bridge.TestConnectionRequest;
import de.espirit.firstspirit.access.*;
import de.espirit.firstspirit.access.script.Executable;

// Provide Context

parameters = new HashMap();
parameters.put("context", context);

// Define Requests to be performed //

requests = new ArrayList();
parameters.put("test_connection_requests", requests);

// Type Definition: TestConnectionRequest.withParams(String httpMethod, String url)

requests.add(TestConnectionRequest.withParams("HEAD", "/categories/tree"));
requests.add(TestConnectionRequest.withParams("HEAD", "/categories/ids"));
requests.add(TestConnectionRequest.withParams("HEAD", "/content"));

// Specify Interval Properties //

// Delay: The time between each Test Connection Call in seconds.
parameters.put("test_connection_interval_delay", 2);

// OverallTime: After which time the interval should be finished in seconds.
parameters.put("test_connection_interval_overall_time", 10);

// Initialize and Call Executable //

moduleAgent = context.requireSpecialist(ModuleAgent.TYPE);

moduleAgent.getTypeForName("FirstSpirit Connect for Commerce - Test Bridge Connection", Executable.class)
        .newInstance()
        .execute(parameters);

4.4. Protokollausgabe interpretieren

Das Ergebnis einer manuellen Ausführung wird mit einem Klick auf Details angezeigt. Auf vergangene Protokolle kann in der Auftragsverwaltung zugegriffen werden.

Die Protokollausgabe ist ausschließlich in Englisch verfügbar.

Ausführungseigenschaften

Zu Beginn jeder Ausführung wird eine Zusammenfassung der Ausführungseigenschaften protokolliert. Die overallTime wird erfasst, sowie der Zeitpunkt, zu dem die Ausführung abgebrochen wird, falls sie bis dahin nicht abgeschlossen ist. In der Regel erfolgt der Abbruch maximal 10 Sekunden nach Erreichen der overallTime.

Ausgabe der Testeigenschaften 
Running Test Connection
 - for 10 seconds
 - with a delay of 2 seconds between each request
 - stopping after a maximum time of 20 seconds

Antwortzusammenfassung nach jedem Durchlauf

Jeder Durchlauf des Verbindungstests wird im Log zusammengefasst. Im ersten Durchlauf werden detaillierte Informationen über die Anfrage und Antwort angezeigt. In den folgenden Durchläufen wird, falls die Ergebnisse unverändert bleiben, die Nachricht "Same result as before" angezeigt. Ändert sich die Antwort, werden alle neuen Details protokolliert.

Ein erwartetes Ausgabeprotokoll könnte wie folgt aussehen:

Ausgabe der Testergebnisse 
INFO  17.09.2024 14:01:00.407 (com.crownpeak.firstspirit.ecom.connect.executable.TestConnectionExecutable):
    Request No. 1
    1) HEAD http://host.docker.internal:3000/api/categories/tree · OK
    2) HEAD http://host.docker.internal:3000/api/categories/ids · OK
    3) HEAD http://host.docker.internal:3000/api/content · OK
INFO  17.09.2024 14:01:02.411 (com.crownpeak.firstspirit.ecom.connect.executable.TestConnectionExecutable):
    Request No. 2
    1) Same result as before
    2) Same result as before
    3) Same result as before
Exceptions werden oberhalb der Antwortzusammenfassung angezeigt.

5. Referenzen

Nachfolgend finden Sie eine Übersicht aller bisher aufgelisteten Referenzen:

Vorlagenzuweisung:

APIs:

Referenzimplementierungen auf GitHub:

6. Rechtliche Hinweise

FirstSpirit Connect for Commerce ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.
Für die Verwendung des Moduls gilt nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

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