FirstSpirit Connect for Commerce: Anleitung zur Fehlerbehebung

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

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.

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

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

Öffnen Sie die Auftragsverwaltung im ServerManager.
Klicken Sie auf Hinzufügen.
Wählen Sie Standard-Auftrag und fahren Sie fort.
Der Auftrag sollte einen passenden Namen erhalten, z. B. "Verbindungstest".
Basierend auf den Anforderungen sollten manuelle, einmalige oder regelmäßige Ausführungen konfiguriert werden.
Falls erforderlich, können Benutzerberechtigungen gesetzt werden.
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

Klicken Sie im Tab Aktionen auf Hinzufügen und wählen Sie Skript ausführen aus der Liste. Klicken Sie auf Übernehmen.
Geben Sie dem Skript einen passenden Namen, z. B. "Verbindungstest".
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

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

3.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);

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

4. Referenzen

Nachfolgend finden Sie eine Übersicht aller bisher aufgelisteten Referenzen:

Vorlagenzuweisung:

Beispiel (SAP)

APIs:

Frontend API

Referenzimplementierungen auf GitHub:

Connect for Commerce Referenzimplementierungen

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

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