Navigation Service: Module Documentation

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.

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.

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.
Permissions: 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
element	en.espirit.firstspirit.access.store.IDprovider	The FirstSpirit element (page reference, structure folder or root node of the structure store element) for which the navigation should be calculated.
language	en.espirit.firstspirit.access.Language	The FirstSpirit language object for which the navigation should be calculated.
key (optional)	String	The attribute to be returned as a result object. If not set, the entire navigation element is returned.

Name

Type

Description

element

en.espirit.firstspirit.access.store.IDprovider

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

language

en.espirit.firstspirit.access.Language

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

key (optional)

String

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
e	de.espirit.firstspirit.access.store.IDProvider	The current FirstSpirit element (page reference, structure folder or root node of the structure store element).
context	de.espirit.firstspirit.access.BaseContext	Instance of an FirstSpirit-SpecialistBroker.
language	de.espirit.firstspirit.access.Language	The FirstSpirit language object at runtime
customData	Map<String, Object>	Entries in this map are written to the custom data and then provided by the Navigation Service endpoint.

Name

Type

Description

e

de.espirit.firstspirit.access.store.IDProvider

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

context

de.espirit.firstspirit.access.BaseContext

Instance of an FirstSpirit-SpecialistBroker.

language

de.espirit.firstspirit.access.Language

The FirstSpirit language object at runtime

customData

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 amount and type of data that may be written into customData is limited. Check the details in the Navigation Service documentation.

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 Crownpeak Technology 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)

Figure 4. Content projection of a detail page view for products

If such a content projection exists in the project, the associated navigation node contains the attribute seoRouteRegex. The value of the attribute is a regular expression describing the dynamic route of the content projection. For the above example of a detail page view for products the value ^[\/]?products\/[^\s\/]+$ would be generated for the seoRouteRegex attribute.

These are so-called entry pages of FirstSpirit content projections .

The Navigation Service does not contain specific information about individual datasets!

To fetch individual datasets of a content projection an additional step is needed. Usually this is a request to the Content as a Service, filtering for the dataset with a matching route. An example implementation is included in the frontend reference project "Crownpeak PWA Template".

The Navigation Service also supports resolving a dynamic route to the corresponding navigation node. Further information is available in the Navigation Service documentation in the chapter API endpoints.

If required, it is possible to exclude certain page references or entire folders in the site store from the navigation. In the case of folder elements, all sub-elements are also automatically excluded. This can be configured individually for each element using metadata. It must be a CMS_INPUT TOGGLE and must have the name md_navservice_exclude.

Example of the input component in the metadata

<CMS_INPUT_TOGGLE name="md_navservice_exclude" type="radio" hFill="yes">
    <LANGINFOS>
        <LANGINFO lang="*" label="Exclude from Navigation Service"/>
    </LANGINFOS>
    <ON>
        <LANGINFO lang="*" label="On" description="Excludes this element and all subelements from the Navigation Service."/>
    </ON>
</CMS_INPUT_TOGGLE>

The exclude directive of sub-elements is overwritten by the highest-level exclude directive in the parent chain.

The exclude directive in the metadata is also displayed for elements that are not in the site store. However, they are only evaluated there. It therefore makes sense to use a rule to display the metadata entry only in the site store.

Example of a rule to display md_navservice_exclude only in the site store.

<RULE>
        <WITH>
                <EQUAL>
                        <PROPERTY name="STORETYPE" source="#global"/>
                        <TEXT>sitestore</TEXT>
                </EQUAL>
        </WITH>
        <DO>
                <PROPERTY name="VISIBLE" source="md_navservice_exclude"/>
        </DO>
</RULE>

5. Authentication

In the current version of the Navigation Service stack the following aspects have to be considered during project development.

5.1. Authentication for read access

Please note that per default there are no authentication/authorisation procedures for all GET requests against the navigation endpoints. This only applies to reading navigations - all writing operations require authentication/authorisation. As a result, every editorial change to a FirstSpirit project with an activated Navigation Service project component is directly transferred to the preview navigation and is therefore accessible to everyone.

If necessary, GET requests can also be blocked either only for preview navigations or completely. Please contact Crownpeak Technology support for this purpose.

6. Legal information

The Navigation Service module is a product of Crownpeak Technology GmbH.

Only a license agreed upon with Crownpeak Technology GmbH is valid with respect to the user for using the module.

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

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

Navigation Service

Module Documentation

1. Introduction

1.1. Architecture

2. Components

3. Configuration

3.1. Configuration of the Navigation Service project component

4. Usage

4.1. Creation of the navigation

4.1.1. Resilience

4.1.2. Scheduled Tasks

Navigation at generation time

4.2. Custom Data

4.2.1. Setting up a Custom Data Script

4.3. Content projections

4.4. Exclude elements from the navigation

5. Authentication

5.1. Authentication for read access

6. Legal information

7. Help

8. Disclaimer