1. Introduction

This troubleshooting document is designed to help you understand and resolve various error codes that may occur when using :modulname:.

Error codes serve as valuable clues to identify and address underlying issues within software, hardware or systems.
The following table contains error codes along with a brief description and possible solution approaches.

Please note that while this document covers a number of common error codes, it does not include all errors you may encounter.

2. Error Codes

Code Description Possible solutions

0000

Unknown error.

1010

URL already exists.

Use a different URL that has not been used before.

1020

Template is not mapped.

Check the template assignment in the bridge. The FirstSpirit templates used must match the templates of the store system.
See template mapping example.

1030

Field is not unique.

The input value is already used. Store another input value for the corresponding field.

1040

Mandatory field is not filled out.

Specify an input value for the missing mandatory field.

2010

Page already exists in FirstSpirit.

Check if the page already exists in the CaaS.

2020

Template is not mapped.

Check the reference names of the page templates in the SiteArchitect with the template assignment from the bridge configuration. In the reference project, contentpage, content, homepage, landingpage, product, and category are currently allowed as templates.

2030

Invalid page type.

Use product, category, or content as type in the payload when creating a new shop-driven page.

2040

Invalid display names format.

Check the format of displayNames in the payload when creating a shop-driven page. The correct format can be found in the Create Page subsection under Use Cases in the Frontend API documentation.

2050

A required parameter is missing.

Check if the request contains all necessary parameters when creating a shop-driven page. The necessary parameters can be found in the Create Page subsection under Use Cases in the Frontend API documentation.

3010

FirstSpirit cannot connect to the bridge.

Open the Project Components in the ServerManager and check the input value for the Bridge API URL field in the FirstSpirit Connect for Commerce - Project Configuration.

3020

FirstSpirit receives 401 from the bridge.

Open the Project Components in the ServerManager and check the input values for the User Name and Password fields in the FirstSpirit Connect for Commerce - Project Configuration.

3050

FirstSpirit cannot connect to the ContentCreator extension.

Open the Project Components in the ServerManager and check the input value for the ContentCreator Extension field in the FirstSpirit Connect for Commerce - Project Configuration.

8010

Frontend API server cannot connect to the CaaS.

Check the stored CaaS URL of your backend service that includes the frontend-api-server module. In our reference implementation you can find the configuration under config/default.yaml for the caasURL variable.

You can view the correct CaaS URL under Project Components in ServerManager in the CaaS Connect Project App.

Please ensure that your CaaS instance is accessible at the specified URL, for example using Postman. If this is not the case, please contact our Technical Support.

8020

Frontend API server receives 401 from the CaaS.

Check the stored CaaS API key, project UUID and tenant ID of your backend service that includes the frontend-api-server module. In our reference implementation you can find the configuration at config/default.yaml for the apiKey, projectID and tenantID variables.

You can view the correct CaaS API key, project UUID, and tenant ID under Project Components in the ServerManager in the CaaS Connect Project App.

8030

Frontend API server cannot connect to the Navigation Service.

Check the stored navigation service URL of your backend service that includes the frontend-api-server module. In our reference implementation you can find the configuration under config/default.yaml for the navigationServiceURL variable.

You can view the correct navigation service URL under Project Components in the ServerManager in the Navigation Project Configuration.

Please ensure that your Navigation Service instance is accessible at the specified URL, for example using Postman. If this is not the case, please contact our Technical Support.

8040

Frontend API server receives 401 from the Navigation Service.

Check the stored project UUID of your backend service that includes the frontend-api-server module. In our reference implementation you can find the configuration under config/default.yaml for the projectID variable.

You can view the correct project UUID either under Project Components in the ServerManager in the CaaS Connect Project App or Navigation Project Configuration.

8050

Cannot create section using TPP.

Check whether the page already exists in FirstSpirit. If so, the already existing page must be deleted from CaaS.

8060

Page is not found in the CaaS after creation.

Check if the page was created in CaaS and exists. If this is not the case, the CaaS deployment must be checked. Please ensure that your CaaS instance is accessible, for example using Postman and that the CaaS configuration in the backend service is valid.

8070

Missing parameter in request to Frontend API server for findPage.

Provide the required parameters in the payload. These can be viewed under FindPageParams in the Frontend API documentation.

8080

Missing parameter in request to Frontend API server for fetchNavigation.

Provide the required parameters in the payload. These can be viewed under FetchNavigationParams in the Frontend API documentation.

8090

Cannot create page for unknown reasons.

3. Automated Test Connection

The "Test Connection" feature assists in identifying bridge errors in a straightforward manner. The Test Connection dialog in the ServerManager is not designed for automatic execution, making repetitive triggering time-consuming and not always effective.

To quickly identify potential issues with the connection between FirstSpirit and the bridge, and to detect errors that occur sporadically over a longer period, Connect for Commerce provides an Executable. This Executable can be configured for scheduled or repeated execution as described below.

3.1. Configuring a Schedule

The Executable works with multiple parameters, allowing its behavior to be customized according to specific requirements.

Step 1: Creating a Standard Schedule:

  1. Open Schedule Management in the ServerManager.

  2. Click on Add.

  3. Select Default Schedule and proceed.

  4. The schedule should be named appropriately, e.g., "Test Connection".

  5. Based on requirements, manual, one-time, or periodic execution should be configured.

  6. If needed, user permissions can be set.

  7. Proceed to the next step in the Actions tab.

automated bridge testing schedule properties en
Figure 1. Configuration of the schedule

Step 2: Adding a Script as an Action

  1. In the Actions tab, click Add and select Execute Script from the list. Click Apply.

  2. Provide the script with an appropriate name, e.g., "Test Connection".

  3. The script provided below can be entered and customized according to the instructions in the next section.

automated bridge testing schedule actions en
Figure 2. Schedule script

3.2. Script Parameters

The Executable provided by Connect for Commerce for the Test Connection works with multiple parameters. This allows its behavior to be customized according to specific requirements.

  • Requests:
    Array of TestConnectionRequest

  • Delay:
    The time between each Test Connection call, in seconds.

  • OverallTime:
    The total time after which the interval will end, in seconds.

Requests

To configure the tests performed by the Executable, a TestConnectionRequest must be created. An HTTP method and the path to the endpoint being tested are required. The base URL from the bridge configuration is automatically applied – see the example below:

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

In each round, all test cases are executed in parallel. Adding more test cases increases the number of tests conducted per round within the scheduled time window. This allows multiple endpoints to be tested in a single round. Afterward, the configured delay value is waited for, and a new round begins.

Delay

The delay defines the interval between the start of each test round. During this interval, the Executable initiates a new request.

The time required for a request is not factored into the interval, ensuring that each round starts at the precisely desired time. However, each step is fully completed before a new round begins.

Overall Time

Each round of the Test Connection is summarized in the log. In the first round, detailed information about the request and response is displayed. In subsequent rounds, if the results remain unchanged, the message "Same result as before" is shown. If the response changes, all new details are logged.

3.3. Combining the script elements

With this information, the following script can be customized to meet specific requirements.

To minimize load, the Executable allows a maximum of 100 rounds with a delay of up to 10 minutes. For the same reason, the delay cannot be set shorter than 2 seconds. This is the fallback value if no delay is specified or if the delay is set to less than 2 seconds.
Schedule script for calling up the connection test 
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. Interpret the Logging

The result of a manual execution is displayed by clicking on Details. Previous logs can be accessed in the Schedule Management.

The log output is available in English only.

Execution Properties

At the start of each execution, a summary of the execution properties is logged. The overallTime is recorded, along with the time when the execution will be terminated if not completed by then. Termination typically occurs no later than 10 seconds after the overallTime is reached.

Output of test settings 
Running Test Connection
 - for 10 seconds
 - with a delay of 2 seconds between each request
 - stopping after a maximum time of 20 seconds

Response Summary After Each Round

Each Test Connection round generates a custom log message. During the initial execution, detailed information about the request/response is displayed. For subsequent rounds, if the results are unchanged, a simple "Same as before" message is shown. If the response changes, the details are logged again.

The expected output should resemble the following:

Output of test results 
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 will be logged above the response summary.

4. References

Below you will find an overview of all references listed so far:

Template assignment:

APIs:

Reference implementations on GitHub:

FirstSpirit Connect for Commerce is a product of Crownpeak Technology GmbH, Dortmund, Germany.
Only a license agreed upon with Crownpeak Technology GmbH is valid for using the module.

6. Help

The Technical Support of the Crownpeak Technology GmbH provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.

7. Disclaimer

This document is provided for information purposes only. Crownpeak Technology GmbH may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. Crownpeak Technology GmbH specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.