1. Introduction

FirstSpirit provides its own template-based navigation function for statically generated pages. In the modern headless world, a different solution is needed, one that seamlessly integrates a dynamic mapping between a navigation route and the corresponding content behind it.

The Navigation Service module provides a mechanism to transfer the structure of the FirstSpirit site store of a project into a JSON format and make it available via the Navigation Service endpoint. According to the documentation of the Navigation Service endpoint the structure can then be queried via its REST interface.

1.1. Architecture

The functionalities of the Navigation Service are realized by the interaction of different components (see figure Architecture).

These components are as follows:

  • Navigation Service

  • Navigation Service module

Figure 1. Architecture

The interaction of the components always follows the following scheme:

  • The creation and updating of navigation-relevant content takes place at FirstSpirit. Changes are made available to the Navigation Service endpoint (see REST API) in the context of an update. For this purpose, the FirstSpirit server creates a connection to it and transmits all relevant data.

  • The Navigation Service receives this data and updates its internal data model based on the information provided.

  • The customer’s application requests the stored information as needed from Navigation Service endpoint, which provides a REST API for this purpose. The querying of the data is performed according to the pull principle.

The communication between the FirstSpirit server and the Navigation Service is done by HTTPS.

2. Components

Using the Navigation Service in an existing FirstSpirit project infrastructure requires two additional components

When the Navigation Service module has been installed, a FirstSpirit service named Navigation Client Service and a project component named Navigation Project Configuration are provided to the FirstSpirit server.

Navigation Client Service

Upon installation of the Navigation Service module, the Navigation Client Service is added to the FirstSpirit server and is then started. For a transfer to the Navigation Service endpoint the project component must be added to the respective project. The Navigation Client Service then takes care of creating the navigations of the FirstSpirit projects.

Only when the Navigation Client Service is running will changes be transmitted to the Navigation Service .

Navigation Project Configuration

By adding/removing the project component Navigation Project Configuration to a FirstSpirit project, it is regulated whether navigations are created for this project. It has its own configuration, which is described in the chapter Configuration of the Navigation Service project component.

3. Configuration

The setup of the Navigation Service for operation on a server is done by configuring the project component: Navigation Project Configuration.

The following subchapters describe the required configuration steps.

3.1. Configuration of the Navigation Service project component

With the usage of the Navigation Service module the project component Navigation Project Configuration becomes available to the FirstSpirit server.

The addition of the Navigation Project Configuration to a FirstSpirit project triggers an initial creation of its navigation structure.

Removing the Navigation Project Configuration will delete the created navigations in the Navigation Service.

To add the project component, open the ServerManager and select the Project settings  project component area.

A list of all existing project component is displayed in the main panel. After clicking Add, select the {component name} and confirm the selection with OK.

projectcomponents add
Figure 2. Adding the project component: Navigation Project Configuration

This project component will be added to the list in the content area and must be configured afterwards (see figure Adding the project component: Navigation Project Configuration).

Select the entry in the list and open the corresponding configuration dialog via Configure.

Fill in the fields as described below.

projectcomponents config
Figure 3. Navigation Service Configuration
SEO Route Url Factory

In this field the URL Factory which is responsible for the SEO routes can be selected. The default value is "get from CaaS Connect (recommended)" and will set the SEO routes to the same value as is configured in the Content as a Service module project component. Details about how to configure the Content as a Service module project component can be found here.

On request it is possible to configure preview navigations so that new URLs are always created by the UrlFactory. Already existing stored custom URLs will then not be used in preview navigations! This is an experimental feature.

Content Reference Url Factory

Content Reference Url factories can no longer be configured. Instead, the CaaS Connect UrlFactory will always be used for this purpose. Already configured alternative URL factories from previous module versions will continue to be used until such a time as a user opens the navigation project app component and saves the configuration while choosing the "get from CaaS Connect (recommended)" option.

Navigation URL (release and preview state)

These listed navigation URLs indicate the locations to which the navigations created for the project are transmitted. These are endpoints for the front-end developers, provided by Crownpeak Technology.

Available in languages

This is a list of all languages of the current FirstSpirit project, for each of which a navigation is provided.

Ignore errors

This mode is not recommended and per default deactivated in all projects. If it is enabled, errors will be ignored when generating the navigation. Instead, null values will be written to the affected locations. You will therefore lose the certainty that data in the Navigation Service is always correct.


Here you can configure whether permissions information should be part of the navigation. The Input name defines the name of the CMS_INPUT_PERMISSION input component. Permissions will only be written to the navigation if this value is set. The Activity name specifies which set of permissions should be used.

4. Usage

The Navigation Service module makes it possible to query the structure of the FirstSpirit site store of a FirstSpirit project via the Navigation Service endpoint.

The following sections describe how such a navigation is created and how to optionally enrich it with additional information.

4.1. Creation of the navigation

The navigations for the preview and release state are updated each time a page reference, structure folder or root node of the site structure has been changed or released. Additionally, an update of the navigation is triggered by changes to pages, if the page is referenced by at least a single page reference.

When changes are made to the global URL settings of the project, both the preview and the release state are updated.

After resetting stored URLs of an element, new URLs might immediately be stored again due to the update of the navigation in the release state.
Navigations are created for each active language of the project as well as for each release status.

Navigations that correspond to a language that is not part of the project are deleted daily as part of a change-triggered update.

4.1.1. Resilience

Occasionally, an update of the navigation may fail for a variety of reasons. Therefore, the process is reattempted several times over more than a day.

4.1.2. Scheduled Tasks

It is also possible to trigger the generation of the navigation by a FirstSpirit scheduled task. When installing the project app, two jobs are added to the project for this purpose: Navigation Live Generation and Navigation Preview Generation. These consist of two tasks each, which transmit the current navigations in all active languages to the Navigation Service and delete existing navigations for which there is no corresponding language in the project.

Languages are considered active when the option Generate language is enabled in the project language configuration.

The NavigationInspectionExecutable can be used to calculate the navigation tree for a specified element at generation time. It expects the following parameters:

Name Type Description



The FirstSpirit element (page reference, structure folder or root node of the structure store element) for which the navigation should be calculated.



The FirstSpirit language object for which the navigation should be calculated.

key (optional)


The attribute to be returned as a result object. If not set, the entire navigation element is returned.

The return value is a JSON object. The method .toString() provides the serialized JSON of the object. If the key parameter is set and the specified attribute has a primitive type, a String is always returned directly.

4.2. Custom Data

If the navigation data in the generated standard format is not sufficient, it is possible to add further information to the navigation. The Navigation Service Module provides the so-called Custom Data Script for this purpose. It allows users to transfer self-defined content to the Navigation Service endpoint.

One use case for this is, for example, a page description, which is required in addition to the navigation information for the presentation.

The following chapter describes the setup of exactly this particular use case.

4.2.1. Setting up a Custom Data Script

Open the SiteArchitect and add a script to your project with the following reference name: navigation_service_custom_data.

Within the script it is necessary to write the code into the first output channel.

Example implementation of a Custom Data Script
import de.espirit.firstspirit.access.store.pagestore.Page;
import de.espirit.firstspirit.access.store.sitestore.PageRef;

if (e instanceof PageRef) {
    page = e.getPage();
    formData = page.getFormData();
    pageDescription = formData.get(language, "pt_pageDescription").get();
    customData.put("pageDescription", pageDescription);

The CustomData Script is evaluated directly after the creation with each following change at the FirstSpirit project as well the release.

The resulting JSON of an exemplary FirstSpirit page reference
    "id": "815c307c-2ca6-4f02-9653-fa3454988fc2",
    "label": "Products",
    "seoRoute": "/Products/Products.html",
    "seoRouteRegex": null,
    "contentReference": "/examplePrefix/Products/Products.html",
    "customData": {
        "pageDescription": "Our Offers"
    "_links": {
        "self": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/node/815c307c-2ca6-4f02-9653-fa3454988fc2?depth=10&language=de_DE"
        "path": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/node/815c307c-2ca6-4f02-9653-fa3454988fc2/path?depth=10&language=de_DE"
        "seoRoute": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/by-seo-route/Products/Products.html?depth=10&language=de_DE"
    "visible": false,
    "permissions": {
        "allowed": ["customer", "admin"],
        "forbidden": ["anonym"]
    "children": null,
    "hasChildren": false

You can find all information on the use and format of the generated navigation structure in the corresponding Navigation Service endpoint documentation.

In addition to the already mentioned IDProvider, other fields are available to the script within the execution context:

Name Type Description



The current FirstSpirit element (page reference, structure folder or root node of the structure store element).



Instance of an FirstSpirit-SpecialistBroker.



The FirstSpirit language object at runtime


Map<String, Object>

Entries in this map are written to the custom data and then provided by the Navigation Service endpoint.

Please note that the maximum size of the customData map is limited to five entries.

The values must be equivalent to JSON primitives (e.g. String, Number or Boolean).

If you have a use case that cannot be covered by the above-mentioned fields, please contact e-Spirit Support.

4.3. Content projections

In the case of a content projection for detailed views the related navigation nodes contain an attribute that can be used to resolve dynamic routes. A content projection is regarded as a projection for detail views if the following attributes are configured in the Content tab of a page reference:

The *Number of entries per page value is greater than 0 (e.g. 1) The *Maximum number of pages value is not 1 (e.g. 0)