FirstSpirit Connect for Commerce

1. Introduction

Customers' expectations of modern E-Commerce shop systems are becoming increasingly diverse: In addition to the pure display of product catalogs, they must provide customers with unique and personalized shopping experiences. Thereby, customers want to be addressed via all channels and devices used by them. The number of touchpoints used is therefore unlimited.

FirstSpirit Connect for Commerce allows the Digital Experience Platform FirstSpirit to be linked with any E-Commerce shop system. It thus creates a powerful overall system that combines the functional advantages of these systems and enables the delivery of modern and personalized content.

Editors are provided full access to the shop’s product catalog and can combine it with editorial content such as interactive videos. The content is thereby maintained using an intuitive WYSIWYG interface provided by FirstSpirit. They also have the ability to create new content. For this, knowledge of the E-Commerce shop system is not required. The WYSIWYG interface provides all the necessary functionalities.

The content is still delivered by the storefront of the connected shop. However, the storefront no longer obtains this content exclusively from the shop’s backend, but also from the FirstSpirit CaaS (Content as a Service). The CaaS is a central content repository and persists the content maintained in FirstSpirit.
The overall system of FirstSpirit and the connect shop thus has an architecture in which the editorial backend of FirstSpirit is clearly separated from the shop’s frontend.

If the expression "Connect for Commerce" is used in the remainder of this documentation, this refers to FirstSpirit Connect for Commerce in all cases.

Included in the delivery of FirstSpirit Connect for Commerce is the reference project FirstSpirit Connect for Commerce Reference Project. This documentation is consistently based on the reference project and provides an explanation of the functions made available by Connect for Commerce using common use cases.

1.1. Range of functions

FirstSpirit Connect for Commerce allows to:

Access product and category information
Creation of new editorial content
Display shop elements and editorial content in the FirstSpirit preview simultaneously
Delivery of content to any touchpoints

The module provides the necessary functionalities after installation and configuration within the WYSIWYG client.

Familiar FirstSpirit tools are used to maintain the content, meaning that editors who are already familiar with FirstSpirit do not require any additional knowledge - especially not about the E-Commerce shop system. The content is made available to the storefront using the CaaS and is delivered by the storefront in combination with the content from the connected shop.

This means that, within the newly created overall system, there is no difference for the delivery of editorial content. It is still carried out by the storefront. Even if the FirstSpirit server is maintained, this doesn’t affect the frontend.

Figure 1. Data flow

1.2. Architecture

By default, a shop’s architecture consists of the backend and a storefront. While, in this system, the backend provides all shop functionalities and persists all shop content, the storefront delivers this content.

With the FirstSpirit Connect for Commerce solution, FirstSpirit and the CaaS integrate into this architecture and extend the functionalities of the shop. Connect for Commerce thus creates an overall system that combines the functional strengths of the individual systems. Within this overall system, FirstSpirit and the shop represent the backend, while the CaaS and the bridge form the middleware and the storefront is the frontend.

The following graphic shows the high-level architecture of this overall system:

Figure 2. High-level architecture

Within the newly created overall system, the storefront continues to deliver the content, which it by default obtains from the backend. In addition, it queries the content of the respective CaaS instance and links it with those of the shop.

In contrast to the delivery of the content, its creation and maintenance shifts to FirstSpirit. With the ContentCreator, FirstSpirit provides an intuitive WYSIWYG client for this purpose. The so-called Omnichannel Manager (OCM) is integrated into this client, which allows displaying external content in the ContentCreator (see figure Low-level architecture).

By embedding the storefront in the Omnichannel Manager, the editors are provided with a combined preview of the content, which in this case, originates from the Preview CaaS and the shop. This way, the editors get the possibility to edit already existing shop pages in the ContentCreator. For this purpose, a variety of different components are available for them.

Product and category information is provided via reports in the ContentCreator. For this, the bridge determines the necessary information from the backend of the connected shop and transfers it to the FirstSpirit server via a REST interface.

The transfer of the created or modified content to the Online CaaS is done with each release. The CaaS persists the content in JSON format in the form of content fragments and makes them available to the storefront, which integrates them together with the shop content.

The overall system of FirstSpirit, the connected shop and its storefront thus has an architecture in which the editorial backend of FirstSpirit is clearly separated from the storefront.

Figure 3. Low-level architecture

1.3. Concept

Connect for Commerce enables editorial content for the connected shop to be maintained in FirstSpirit and this to be transferred into the CaaS. From there it is retrieved from the storefront and delivered together with the product information from the shop. For this, the processing of content in both systems must be coordinated and be mutually compatible. The subchapters below describe the underlying concept used to achieve this compatibility.

1.3.1. Life Cycle

Within the overall system established with Connect for Commerce, the creation and maintenance of editorial content is shifted to FirstSpirit. Due to the full access to the product catalog of the connected shop, an integration of the shop content is thus also possible.

Once the editorial content is released, it is automatically transferred to the CaaS. This in turn makes it available to the storefront of the connected shop.

The storefront queries the information and links it with that of the shop to deliver it in a combined view. For the preview, FirstSpirit in turn retrieves the displayed page from the storefront and displays it with the maintained content in the ContentCreator.

Figure 4. Life Cycle

1.3.2. Bridge

The Bridge is a microservice that links any shop backend and the FirstSpirit server. It is designed to facilitate communication and data exchange between the two systems.

The Bridge implements the REST interfaces of the Bridge API and transfers the available product, category, and content page information from the shop backend to the FirstSpirit server. It is also responsible for the mapping between FirstSpirit pages and shop pages.

Reference implementations of various bridges are available on Github.

1.3.3. CaaS Connect

The CaaS is a central repository. It persists the FirstSpirit content in the form of content fragments and makes them available to any endpoint in a unified JSON format.
Unlike previous CaaS versions, CaaS Connect omits templating in FirstSpirit and moves it to the frontend. Furthermore, the continuous transfer of content ensures that the data in the CaaS is always up to date.

Further information is available in the CaaS Connect documentation.

1.3.4. Frontend API

The Frontend API extends FirstSpirit Connect for Commerce with the functionality to create product, category, and content pages as Shop Driven Pages, retrieve data from CaaS, and prepare marked slots for content editing.

It consists of two npm packages:

fcecom-frontend-api-client: Provides the API methods for the integration in the storefront.
fcecom-frontend-api-server: Handles communication with CaaS, needs to be integrated in a backend service.

The reference implementation of a backend service is available on Github.

Further information and examples are available in the Frontend API documentation.

To improve the performance of CaaS requests, the Connect for Commerce module creates an index in CaaS. This consists of the keys page.formData.type.value, page.formData.id.value, locale.language and locale.country, which are necessary to identify a Shop Driven Page. The index is created for both the preview and release collection.

1.3.5. Pages

Similar to FirstSpirit, the pages in a shop are based on a structure of various components. To enable editorial content to be exchanged between both systems, these components must be coordinated.

Within the reference project FirstSpirit Connect for Commerce Reference Project included in the delivery, the maintainable areas of a shop page are represented by the content areas of a FirstSpirit page template. Sections can be added to them; each one corresponds to the equivalent component of the shop page (see figure Page Rendering).

FirstSpirit can thus be used to generate components that are displayed within the maintainable areas of a shop page.

Figure 5. Page Rendering

1.3.6. Page types

As described in the previous chapter, the maintenance of editorial content both in FirstSpirit and the shop system is based on a page. Connect for Commerce differentiates between Shop Driven Pages and the FirstSpirit Driven Pages.

FirstSpirit Driven Pages: FirstSpirit Driven Pages exist exclusively in FirstSpirit and do not have an associated page in the shop system. They are used to create content or campaign pages, which are not necessarily included in the standard scope of the store. FirstSpirit Driven Pages can either use the layout of a Shop Driven Page or their own layout, which is defined in the Storefront.
Shop Driven Pages: In contrast to the FirstSpirit Driven Pages, the Shop Driven Pages have a page both in FirstSpirit and in the shop system. For example, they correspond to the homepage or the product and category pages. The contents maintained in FirstSpirit overwrite or extend the existing contents in the predefined slots of these pages.

1.3.7. Preview

The FirstSpirit Connect for Commerce module only allows FirstSpirit to generate and maintain editorial content and to publish it in the form of JSON documents. The storefront, however, continues to determine the framework of a page, whose maintainable areas integrate the generated components.

To present the preview of a page, FirstSpirit determines its current view in the storefront. In this case, the storefront in turn retrieves the editorial content from the Preview CaaS and replaces the corresponding components in the shop page. FirstSpirit then displays the result in the ContentCreator using the Omnichannel Manager.

1.3.8. Identifier

With Connect for Commerce editors are provided full access to the connected shop’s product catalog and can supplement it with editorial content. For this, a bridge is used to determine the necessary information from the shop backend. It transfers the data to the FirstSpirit server, which makes it available via reports in the ContentCreator.

In order to always ensure a correct mapping between the real shop data and the product and category information used in FirstSpirit, a mapping is required. This must be based on unique IDs and can correspond, for example, to the assignment of a SKU to a URL. The mapping is relevant for both, the bridge and the data transfer in the frontend. The following graphic shows the mapping of a Product ID or Category ID to a Resource ID.

The IDs defined in the mapping are in turn stored in the form data of the respective FirstSpirit element and transferred to the CaaS via deployment each time it is released. Such a FirstSpirit element can be a page as well as, for example, a single teaser referencing a specific product. The CaaS persists the content created in FirstSpirit in the form of content fragments and makes them available to the storefront of the connected shop.

The storefront continues to deliver the content, which it by default obtains from the shop’s backend. With Connect for Commerce, it additionally accesses the CaaS and queries the editorial data from it. The query is based on the mapping specified by the bridge, which must also be known in the frontend. This way it is ensured that the CaaS returns the correct data. The storefront links the information with those of the shop and delivers it in a combined view.

Figure 6. Mapping of IDs

1.3.9. Editorial changes

As part of the usual editorial process, the contents of a FirstSpirit project can be changed or deleted at any time. Any of these adjustments require an update of the delivered content. Just as for the initial publication of new content, this also requires a release, which triggers an automatic transfer of the content into the CaaS.

2. Components

Connect for Commerce consists of various components. The functionality of these components is described in the following sections.

FirstSpirit: The FirstSpirit environment corresponds to the FirstSpirit server and the modules installed on it. FirstSpirit enables the creation and maintenance of content and provides the ContentCreator for this purpose. This allows the integration of external content with the help of the Omnichannel Manager. Editors thus receive a combined preview of FirstSpirit and shop content, which they can edit by using different functionalities.
Bridge: Beside the CaaS, the bridge is the central element between FirstSpirit and the connected shop: It determines the product information from the shop backend and transfers it to the FirstSpirit server via a REST interface. The server makes the data available in the form of reports in the ContentCreator and thus enables its integration when creating new content.

Since the interfaces of the connected shop must be taken into account when querying product data, a shop-specific implementation of the bridge is required in each case.
CaaS: The CaaS represents a central repository and is, in addition to the bridge, the second key element of Connect for Commerce. It persists the content created in FirstSpirit in the form of content fragments and makes them available to the connected shop. Its storefront queries the information and combines it with that of the shop.
E-Commerce shop: While the backend of the connected E-Commerce shop provides all shop functionalities, the storefront continues to deliver the content. It obtains this from both the shop’s backend and the CaaS and links them together to then deliver a combined view. Within the overall system created by Connect for Commerce, there is thus no difference for the shop structure.

3. Developer’s tasks

FirstSpirit Connect for Commerce allows FirstSpirit to be linked with any shop system. By default, such a shop’s architecture consists of the shop backend and a storefront. Since the linking - both with the backend and with the storefront - must always be shop-specific, additional implementation effort is required. This consists of the implementation of a so-called bridge and the transfer of the data stored in the CaaS into the storefront.

The Crownpeak Technology GmbH offers support and updates only for the source code it provides. It can explicitly assume neither responsibility nor support for custom implementations.

Bridge implementation

The bridge corresponds to a service whose task is to determine the product information from the shop backend and transfer it to the FirstSpirit server. It links the FirstSpirit Connect for Commerce API with that of the shop and in this way establishes a connection between the two systems.

The delivery already contains a selection of different bridge implementations for various shop systems, each realized as a microservice. These can be extended individually, but can also be used without customization. In this case they only need to be checked for compatibility with the desired use cases. Furthermore, the delivery provides an npm module, that can be used as a basis for the implementation of a bridge. The module implements the basic logic of a bridge and just needs to be extended by adding the shop specific functionalities. Alternatively to these options, the bridge for the connected shop may be completely self-implemented.

Both, in the case of a custom implementation and when using a provided bridge, it must be ensured that the bridge is reachable from the FirstSpirit server in order to receive the data determined from the shop backend. For this, the data exchange must be protected against unauthorized access via Basic-Auth. In addition, the accessibility of the shop must be ensured: If the shop also uses a authentification, the bridge must be allowed to access its backend and query data.

In order to display the data on the FirstSpirit side, it is also necessary to link the bridge endpoints Content, Products and Categories with the corresponding endpoints of the shop API. They are provided by the FirstSpirit Connect for Commerce API and each corresponds to a report in the ContentCreator. If additional endpoints are desired, their linking must be done independently.

The implementation of the Mapping endpoint is required in order to establish a link between FirstSpirit pages and pages on the shop system. It returns an identifier for a given Storefront URL which is used in FirstSpirit to identify the page. Conversely, a storefront URL can be constructed based on given identifier properties in FirstSpirit.

Since the product and category information used in FirstSpirit must always be assignable to the real data in the shop, a mapping must be defined for them. This mapping must be based on unique IDs and is also necessary for data transfer in the frontend. For example, a possible mapping can be the assignment of the SKU to a URL.

Further information on how to implement a bridge is provided in the corresponding use case chapter.

Since the IDs form the basis for mapping the product and category information, subsequent changes are not recommended and should therefore always be avoided. The initial coordination as well as the conception of the overall architecture are in the responsibility of the developers.

The FirstSpirit Connect for Commerce API documentation is provided in two ways:

in ReDoc format
as a local Swagger UI
when using the bridge implementations provided by the Crownpeak Technology GmbH.

Data transfer in the frontend

The transfer of the data stored in the CaaS to the storefront must be done based on a custom implementation.

It must be ensured that data retrieval from the CaaS is only possible with the appropriate authorization. For this, the CaaS requires an API Key, which defines the access rights. This key has the status of a password and must therefore be treated accordingly. Without a protection of the API Key the data stored in the CaaS is freely accessible.

Furthermore, it is important to fetch the correct information. This requires a valid association between the product and category information used in FirstSpirit and the real shop data. Therefore, during the bridge implementation, the definition of a mapping based on unique IDs takes place. The IDs are in turn stored in the form data of a FirstSpirit element and transferred to the CaaS via release. Based on the IDs, it is thus possible to retrieve the FirstSpirit data stored in the CaaS as well as to link it to the shop data.

The JSON content fragments stored in the CaaS are partly very nested and contain information that is irrelevant for the output in the storefront. For this reason, it makes sense to first reduce the data and transform it into a format that is optimal for the storefront. In this process, it is important to ensure a correct resolution of linked information, such as media URLs.

The storefront combines the editorial content received from the CaaS with that from the shop backend and delivers it in a combined view. In doing so, not only the display of the correct content, but also its proper placement is important. Within the reference project included in the delivery, the maintainable areas of a shop page are represented by the content areas of a FirstSpirit page template. Sections can be added to them, each corresponding to the equivalent component of a shop page. This must be taken into account and implemented when outputting editorial content.

Each call to a shop page also generates a CaaS query, since the content displayed in the storefront is dynamically determined. Therefore, a caching strategy that avoids both performance problems and the cost of a high data volume is extremely beneficial.

A more detailed description of how content is displayed in the storefront is contained in the use case chapter of the same name.

4. Quick Start

The Quick Start chapter is aimed at administrators and outlines the installation steps to be performed to connect a E-Commerce shop. It is designed to provide an initial overview and is therefore deliberately kept brief. A detailed explanation of the steps to be performed and additional information is contained in the following installation chapter.

The following list assumes that a shop instance already exists and a FirstSpirit environment is provided by the Crownpeak Technology GmbH including all required modules and an imported project.

In addition to the installation steps, several custom implementations are required, which are not considered here. They cover various use cases, which are described in the chapter of the same name.

Installation steps to be performed

Integration of the Omnichannel Manager

Enable the storefront to be callable in an iFrame by setting frame-ancestors or an X-Frame-Option-Header on the shop side.
Allow Cross-Origin Resource Sharing by configuring a CORS filter.
Include the TPP API in the storefront - either using an npm module or manually.
Using the HTML attribute data-preview-id, mark the editable content areas within the existing shop pages.

Configuration of the project components

Open the ServerManager and select Project Properties Project components.
Specify the required connection data of your CaaS instances in the configuration dialog of the CaaS Connect Project App.
In the dialog of the Navigation Project Configuration, configure the Navigation URL for both the preview and the live status.
Only required when using the Interactive Video: In the YouTube-DAP-Integration configuration dialog, store a Google API Key and optionally a Channel ID.
Enter the bridge’s API URL and the login data of a technical account in the configuration dialog of the FirstSpirit Connect for Commerce - Project Configuration.

Selection of the Element Status Provider for the workflows

Open the ServerManager and select the Project Properties ContentCreator area.
In the corresponding field, select the BasicWorkflows Status Provider.

Permission definition for the workflows

As a project administrator, open the shop to be configured in the SiteArchitect.
In the context menu of the root node of the corresponding store, select the entry Extras Change permissions.
Assign the appropriate permissions in the Workflow permissions tab of the configuration dialog which opens.

Definition of the external preview URL

Open the ServerManager and select Project Properties ContentCreator.
Enter the external preview URL in the field of the same name.

5. Installation

FirstSpirit is used to create and maintain editorial data, which is then transferred to and persisted by the CaaS. To integrate the data into the shop, the storefront requires access to the CaaS. This access is provided by various elements which must be integrated and configured on the shop side.

Furthermore, various components must be installed and configured on the FirstSpirit side in order to use the functions of the FirstSpirit Connect for Commerce module.

The following subchapters explain the steps required on both sides.

5.1. Integration of the Omnichannel Manager

FirstSpirit Connect for Commerce allows FirstSpirit to be linked with any E-Commerce shop system. Editors are provided full access to the shop’s product catalog and can combine it with editorial content. For this purpose, FirstSpirit provides the ContentCreator, which allows the display of external content by including the Omnichannel Manager. By embedding the storefront in the Omnichannel Manager, the editors are provided with a combined preview of the content, which in this case originate from the _Preview CaaS and the shop. This way, the editors get the possibility to edit already existing shop pages in the ContentCreator.

Using the Omnichannel Manager requires the following from the shop used:

Display in iFrame: In order to display the contents of the connected shop in the ContentCreator, its storefront must be callable in an iFrame. This requires frame-ancestors or an X-Frame-Options header, which must be set by default in the configuration of the web server used. However, this may differ depending on the shop system.

Note that frame-ancestors obsoletes the X-Frame-Options header. Therefore frame-ancestors is the recommended option, but as some browsers do not support it yet, x-frame-options might still be required as a fallback.

Allow CORS: In addition to the display in an iFrame, the storefront of the connected shop must be allowed Cross-Origin Resource Sharing (CORS). The CORS filter required for this allows cross-domain requests to be executed and must be configured on a shop-specific basis.
Integration of the TPP API: Editing existing shop pages in the ContentCreator requires that an access to the API of the Omnichannel Manager is available on the shop side. This requires a JavaScript file that can be included in the storefront either using an npm module or manually. It provides the functionalities of the ContentCreator within the storefront and thus enables the maintenance of external content.
Marking editable content areas: Along with the integration of the TPP API, marking editable content areas is required for editing existing shop pages. For this purpose, the HTML attribute data-preview-id must be set. Only this enables the use of the editing functions provided by the ContentCreator and thus the maintenance of the editorial content. Editing the content triggers its transfer to the CaaS, which in turn makes it available for retrieval via a REST interface.

More information about the Omnichannel Manager as well as its API can be found in the Omnichannel Manager documentation and the API description.

5.2. Configuration of the project component

Various project-specific information is required in order to use the FirstSpirit Connect for Commerce module. It is set up using the project component, which is already added to the reference project supplied.

To use the FirstSpirit Connect for Commerce module, the CaaS Connect module and the NavigationService must also be configured. The necessary steps are described in the CaaS Connect Documentation and in the Documentation of the NavigationService.

The use of the Interactive Video additionally requires the configuration of the YouTube-DAP-Integration. This is explained in the associated Readme file.

To perform configuration, open the ServerManager and select Project Properties Project components.

Figure 7. Project Properties - Project components

A list of all existing project components is displayed in the main panel. Select the entry FirstSpirit Connect for Commerce - Project Configuration and open the corresponding configuration dialog via Configure.

5.2.1. General

In the General tab, the following configuration can be made:

The absolute path to the ContentCreator Extension file
Use ContentCreator Extension
Disable Bridge Content Page creation

The ContentCreator Extension is a JavaScript file that must be provided in a location accessible by the client’s browser. The script allows the communication between the ContentCreator and the FirstSpirit Connect for Commerce module. The script is customizable to project specific needs. The implementation of the ContentCreator Extension includes a simple web server and is published on GitHub.

When using the Frontend API the checkbox Use ContentCreator Extension must be unchecked.

By default, the FirstSpirit Connect for Commerce module creates an equivalent of the page in the shop system via the bridge when creating a content page by clicking the plus button in the ContentCreator. The checkbox Do not create content pages via Bridge can be used to disable this behavior.

Figure 8. project component - Configuration dialog - General

5.2.2. Bridge

Configure Bridge

In the Bridge tab, the following configuration can be made:

The bridge’s API URL
The credentials for the login to the bridge

Furthermore the bridge connection can be tested via the button Test Bridge connection.

Figure 9. project component - Configuration dialog - Bridge

Connection test

The project component offers the possibility to test the connection between the Connect for Commerce module and the bridge.

The log window shows the result of the connection test in a detailed way. For this, successful request are as clearly shown as failed ones. In this window, there will be flags added that show if an endpoint is deprecated and removed in the near future.

Figure 10. Example Output: Successful connection test

Figure 11. Example Output: Deactivated feature

Figure 12. Example Output: Failed connection test

5.2.3. Reports

In the Reports tab, the number of category levels can optionally be defined for both the categories and the products report. These limit the display of the category tree within the corresponding report to the number of desired levels, for which the value 3 is specified by default in each case.

Figure 13. project component - Configuration dialog - Reports

5.3. Installation of the web components

For the ContentCreator, a web component is needed, which is already added to the reference project. By default, it is installed globally in the ServerManager in the area Server Properties Web applications. In this case, all installation or configuration steps required for the web component have already been performed by the Crownpeak Technology GmbH.

Figure 14. Web components in the Server Properties

Within the main panel several tabs are visible, each with a list of the existing web components. This list contains the following entries for the ContentCreator:

BasicWorkflows_ContentCreator_Library (only required when using the BasicWorkflows)
FirstSpirit Connect for Commerce - Web Application Component
FirstSpirit ThirdPartyPreview WebApp
YouTube-DAP-Integration (only required when using the Interactive Video)
Interactive Video (only required when using the Interactive Video)

For detailed information about adding web components, see the FirstSpirit Manual for Administrators.

5.4. Workflows

Content is released and deleted by editors within the supplied reference project FirstSpirit Connect for Commerce Reference Project via the BasicWorkflows. They are already added to the project and can be used as an alternative to project-specific workflows.

Installation of the BasicWorkflows module

Before using the workflows, the BasicWorkflows module must first be installed on the FirstSpirit server and the web component must be activated. The necessary steps are the same as for the installation of the other modules and activation of the web component associated with the FirstSpirit Connect for Commerce module. By default, these steps are already performed.

The use of BasicWorkflows in the ContentCreator also requires the selection of the provided BasicWorkflows Status Provider in the Project Properties ContentCreator area within the ServerManager. This setting has also already been made in the reference project FirstSpirit Connect for Commerce Reference Project.

Figure 15. Element Status Provider

Templates

The BasicWorkflows need different templates. These usually have to be imported into the FirstSpirit project via the context menu. However, they are already included in the reference project and an import of the templates is therefore not necessary.

Permission assignment

In the final step, the BasicWorkflows must be allowed in each store to run on FirstSpirit elements. To do this, the permission assignment can be opened in the SiteArchitect on the root nodes of the stores via the context menu entry Extras Change Permissions. This step has already been performed in the reference project and is therefore omitted.

The rights set on the stores' root nodes to execute the workflows refer to the Everyone group. If this is not desired, the rights must be adjusted manually.

More information about the installation, configuration and functionality of the workflows can be found in the BasicWorkflows Documentation.

5.5. Deployment schedules

With CaaS Connect the publication of editorial content as well as updating the Online CaaS takes place with each release. An additional deployment process is not necessary in this case.

However, during the progress of the project, situations may arise that require manual transfer of editorial content into the CaaS. Therefore, the CaaS Connect module provides two schedules that are automatically added to the project. They do not require any project-specific customization.

5.6. Definition of the external preview URL

By using the Omnichannel Manager, the ContentCreator displays external shop content to which the Omnichannel Manager needs access. The preview URL of the storefront must therefore be specified in the ContentCreator properties. Since the specification is always project-specific, there is no default configuration for it within the reference project.

Open the Project Properties ContentCreator settings area within the ServerManager and enter the URL of the storefront in the External Preview URL field.

Figure 16. External Preview URL

6. Reference project

The FirstSpirit Connect for Commerce module provides different ways to access shop content and use it in FirstSpirit. This requires different components both within the FirstSpirit project and in the storefront. The following subchapters describe these components and the dependencies between them using the reference project provided.

6.1. Languages

In order to be able to maintain store content in multiple languages with FirstSpirit, it is necessary to create a clear assignment between store languages and project languages. The languages defined in the FirstSpirit project should therefore be selected so that their abbreviations correspond to the abbreviations of the store languages.

Within the reference project, DE and EN are preconfigured as available languages. However, if the shop requires language abbreviations in the locale format (e.g. en_GB), the two languages DE and EN must be removed and replaced by project languages with appropriate abbreviations. When assigning shop languages to project languages, no distinction is made between upper and lower case letters.

Further information on the selection and configuration of languages in the project can be found in the FirstSpirit Online-Documentation.

6.2. Pages

In contrast to the delivery of content, using Connect for Commerce shifts its creation and maintenance to FirstSpirit. Therefore FirstSpirit provides the ContentCreator. In it, both the pages created with FirstSpirit and the already existing shop pages can be displayed and enriched with editorial content using the Omnichannel Manager.

Editorial content in FirstSpirit is always created and edited on the basis of a page reference. It and the page on which it is based are automatically generated in the background in the provided reference project as soon as a new page is created in the ContentCreator. This is also the case for existing pages that do not yet exist in FirstSpirit.

The reference project provides the following page templates for content, product, and category pages:

Homepage
Contentpage
Categorypage
Productpage
Landingpage

Homepage: The homepage page template is an example of so-called static pages, such as the start page, the login page, or the shopping cart. Static pages have a fixed URL and generally exist only once within a shop. They are predefined by the shop and have their own layout, which distinguishes them from the other pages. For this reason, they each require their own template.
Content pages: The content page templates form the basis for the project’s standard pages and are therefore referenced multiple times. Content pages, unlike category and product pages, contain general information that does not relate to specific products.
Category / Product pages: Both the category and product pages are used to display the products originating from the connected shop. Product pages represent the detailed view of a specific product. In contrast, category pages provide an overview of all products belonging to a category.

The category and product information from the connected shop is integrated, among other things, via two reports provided by the FirstSpirit Connect for Commerce module in the ContentCreator.
Landing pages: Landing pages are temporary pages that are not part of the general website. Instead, they relate to specific events, such as a summer sale or the Black Friday.

6.3. Sections

Within the reference project FirstSpirit Connect for Commerce Reference Project included in the delivery, the maintainable areas of a shop page are represented by the content areas of a FirstSpirit page template. Sections can be added to them; each one corresponds to the equivalent component of the shop page.

For this, the reference project provides the following section templates:

Banner
Carousel
Interactive Video
Interactive Image
Text/Image
Featured Products
Modal
Multi-Slot Container
Teaser Grid

Banner: The banner corresponds to a single image in horizontal format, which is, by default, included in the header of a page.

The section allows the selection of a cropable image, the specification of a headline, a subtitle and a link. The text color as well as the position is specifiable for the headline, the subtitle and the link.
Carousel: The carousel resembles the banner in form and editability. Unlike it, however, it embeds multiple images that rotate continuously.
Interactive Video: The interactive video allows products to be displayed and referenced at specific times in a video.
The section requires the selection of a video in which text/image or product elements can be displayed at any point of time.

Text/Image element
A text/image element consists of an image, a caption, a text, and an internal link.

Product element
A product element contains a product photo, a product name, a product description and optionally an image and a text.

In order to use the Interactive Video the installation and configuration of the modules YouTube-DAP-Integration and Interactive Video is mandatory. Otherwise this section has no functionality.

Interactive Image: The interactive image allows products to be displayed and referenced on an image map.

The section requires the selection of an image in which links to product detailpages can be displayed. In addition, a headline and text can be maintained alongside the image.
Text/Image: The text/image section expects the input of a text. In addition, it allows the specification of a headline and the selection of an image that can be positioned left or right of the text.
Featured Products: The Featured Products is a layout component that, in addition to entering a heading and a text, enables the automatic arrangement of product elements. The arrangement of the elements depends on their number: Up to a number of three elements are displayed next to each other. Additional elements are grouped together, also up to three elements, and displayed in additional lines below.

A product element contains the product photo, the product name and the product description. The information for a product element comes by default from the FirstSpirit Connect for Commerce - Products Data Access Plugin.
Modal: The modal is a layout component that presents information in a pop-up dialog box that overlays the primary content.

It allows the selection of an image as well as the input of a heading, a subheading and a text. Additionally it allows the definition of a reference.

The modal is not a standard section template and can only be selected by editing the page information in the ContentCreator navigation. In the reference project, the modal component is only allowed for the homepage page template.

Multi-Slot Container: The Multi Slot Container is a layout component that enables the automatic arrangement of content, category or product elements in addition to entering a heading. The arrangement of the elements depends on their number: Up to a number of four elements, they are displayed side by side and scaled accordingly. Additional elements are grouped together, also up to four elements, and displayed in additional lines below.

All elements allow the input of a headline, a subtitle and a teaser text as well as the selection of an image for which an alternative text can be specified. Furthermore, the display of each element contains a button whose label is freely definable and which refers to the detailed view of the respective element. This button is only visible if the multi slot container contains only one element.

In addition to the input options mentioned above, the content element allows the definition of a reference. Also in this case all reference types available in the reference project are allowed for this.

In addition to the input components mentioned above, the category element has a component for selecting a category. If no image is selected for a category, the category element displays a default image.

The information for a category and product element comes by default from the FirstSpirit Connect for Commerce - Categories Data Access Plugin and FirstSpirit Connect for Commerce - Products Data Access Plugin. They serve as a fallback and are overwritten by entries in the named components.
Teaser Grid: The teaser grid is a layout component that allows free arrangement and scaling of different elements.

The elements can correspond to an image or a video, for each of which a link as well as a headline, a subtitle and a text can be defined.

6.4. Links

The editorial contents maintained in FirstSpirit can contain the following references, which link them with other contents. They are based on various link templates that are already included in the reference project.

Category and product links: The FirstSpirit Connect for Commerce module provides a report for products and categories in the ContentCreator. They serve to display the category and product information coming from the shop backend, which can be used for links to category or product detail pages.

Therefore, the reference project contains the link templates category_link and product_link, which correspond to a category or product link. They enable category or product detail pages to be referenced.

Content link: The reference project provides the link template content_link. It allows the linking of pages that are maintained within the reference project.
External link: The external_link reference template corresponds to an external reference and works similarly to the content reference. Unlike the latter, however, it refers to external content and therefore expects a URL, rather than a page reference.
CTA reference: A call-to-action reference is provided with the cta_link reference template in the reference project.
The reference text is displayed as either a light or dark CTA button. In addition, a link can be selected from the previous link types.
Interactive product reference: The section template Interactive Image uses only the ìnteractive_product_link reference template.
It functions similarly to the product link with the exception that a caption can also be maintained.
DOM references: The dom_category_link, dom_content_link, dom_external_link, and dom_product_link reference templates included in the reference project function similarly to the equivalent reference templates described previously. These link templates are used in the DOM text editor and provide an additional field for the link text.

7. Use cases

Within the progress of a project, different situations can arise that require certain steps to be taken. The following subchapters describe situations that can typically occur in integration projects, and describe the necessary steps for resolving them by using the reference project supplied as a reference.

7.1. Bridge implementation

In contrast to the delivery of content, which is still done by the storefront, its creation and maintenance shifts to FirstSpirit. Therefore FirstSpirit provides the ContentCreator. In it, both the pages created with FirstSpirit and the already existing shop pages can be displayed and enriched with editorial content. In addition, the reports contained in the ContentCreator enable the provision of product and category information from the shop. However, this requires a bridge that must be specific to the respective shop.

The bridge determines the necessary information from the backend of the connected shop and transfers it to the FirstSpirit server via a REST interface. To do this, it links the FirstSpirit Connect for Commerce API with that of the shop and in this way establishes a connection between the two systems. Just like the CaaS, the bridge thus forms the middleware within the overall system created by Connect for Commerce. Unlike the CaaS, however, the bridge communicates exclusively with the backend of the shop and not with its storefront.

Figure 17. Position of the bridge in the overall system

The Crownpeak Technology GmbH provides bridge implementations in two different forms and thereby enables the following four types of usage:

Available bridge
The delivery already contains a selection of different bridge implementations for specific shops. These are available on GitHub and can be used directly without further customization.
Customized bridge
The bridge implementations available on GitHub are customizable. This way, additional features can be added to the used bridge that are not included in the standard scope.
Bridge commons
In addition to the bridge implementations, the delivery provides an npm module to use as the basis of a bridge implementation. This module offers the basic functionalities of the bridge and just has to be extended by adding the shop specific functionalities. It serves exclusively as a basis for a self-implementation.
Self-implementation
As an alternative to the options mentioned before, the bridge for the connected shop may be completely self-implemented. In this case, the aspects described below must be observed.

The Crownpeak Technology GmbH offers support and updates only for the source code it provides. It explicitly assumes neither responsibility nor support for custom implementations.

As mentioned before, the implementation of a bridge must be adapted to the connected shop. For this reason, detailed instructions are not possible. Basically, however, the following steps are required:

Creation of an HTTP service
Authentication on the FirstSpirit side
Ensuring the accessibility of the shop
Linking the endpoints

Creation of an HTTP service: The bridge corresponds to a service to be developed that implements the FirstSpirit Connect for Commerce API. This can be implemented either as a standalone microservice or as a native service within the shop architecture. In both cases, the service must be accessible via HTTP to allow the FirstSpirit server to determine the shop data.

Authentication on the FirstSpirit side

To protect the data exchange between the FirstSpirit server and the bridge from unauthorized access, Basic-Auth must be implemented in the bridge. Furthermore, the credentials for the login to the bridge as well as its API URL must be entered in the configuration dialog of the project component. In addition to the input fields, the dialog contains a button that enables a test of the connection between the FirstSpirit server and the bridge.

Ensuring the accessibility of the shop

Under certain circumstances, the shop to be connected also requires authentication. In this case, it must be ensured that the bridge can access its backend and query data.

In addition, the bridge must be able to react to a possible downtime of the shop instance and return a corresponding notification to the FirstSpirit server. Such a situation must not have any impact on the creation and maintenance of editorial content on the FirstSpirit side, even if the shop content may be temporarily unavailable.

Linking the endpoints

The FirstSpirit Connect for Commerce API provides the endpoints Content, Products, Categories and Mapping, which can be used optionally. The Content, Products and Categories endpoints correspond to a report in the ContentCreator, which can be disabled if needed.

Content
The Content endpoint provides a report for content pages. This allows both the display of the pages created with FirstSpirit as well as the pages that exist in the shop, such as the homepage or the shopping cart.
Products and Categories
The endpoints Products and Categories allow the provision of product and category information. In both cases, the amount of information returned is limited because its processing is done during the provision in the frontend and no formatting is required. For example, the price of a product is always dynamically queried for display in the frontend. Because of this, it is not available in FirstSpirit’s editorial backend.

By linking product and category information, editors can filter products by category or perform specific searches. Such a product search, depending on the categories, requires a custom implementation that forwards all search queries to the shop and displays the result in FirstSpirit.
Mapping
The Mapping endpoint establishes the link between pages in FirstSpirit and pages in the shop system. It returns an identifier for a given Storefront URL which is used in FirstSpirit to identify the page. It also provides the option to construct a Storefront URL based on given identifier properties in FirstSpirit.

An associated Data Access Plugin (DAP) exists for the Content, `Products and Categories endpoints. This enables the linking of the data provided and its integration into editorial content. In the case of the Products endpoint, for example, it is possible to link products and create product teasers.

To do this, simply add an FS_INDEX input component to the template of the section where content is to be linked to a product:

FS_INDEX input component in section template

<FS_INDEX name="st_product" height="1" useLanguages="no">
    <LANGINFOS>
        <LANGINFO lang="*" label=""/>
    </LANGINFOS>
    <SOURCE name="FirstSpirit Connect for Commerce/FirstSpirit Connect for Commerce - Products Data Access Plugin"/>
</FS_INDEX>

In the same way, content can be linked to categories as well as to other content pages. Only the DAP to be linked must be exchanged accordingly. The following three DAPs are available:

FirstSpirit Connect for Commerce - Products Data Access Plugin.
FirstSpirit Connect for Commerce - Categories Data Access Plugin
FirstSpirit Connect for Commerce - ContentPages Data Access Plugin

The linking of the bridge endpoints with those of the shop is completed as soon as the reports in ContentCreator provide the desired shop data. This simultaneously corresponds to a successful end-to-end test.

The product and category information used in FirstSpirit must always be assignable to the real data in the shop. This is especially important when modifying existing IDs. Since they form the basis for mapping the data, changes to the IDs are not recommended and should therefore always be avoided.

If changes are necessary nevertheless, both the information presented in the reports and the information contained in DAPs will synchronize independently. However, the IDs stored in the input components of product and category pages require updating. In all cases, it is mandatory to ensure that any information stored in FirstSpirit is identical to that from the shop. Otherwise, a manual effort is unavoidable.

7.2. Display of content in the storefront

After the FirstSpirit-side creation or maintenance of editorial content, an automatic transfer to the CaaS takes place with its storage and release. This persists the content in JSON format in the form of content fragments and makes them available via a REST interface. The storefront receives this information and links it with that of the shop to deliver it in a combined view.

The transfer of CaaS content to the storefront is possible on the basis of a custom implementation. This must be adapted to the connected shop, which is why detailed instructions are not possible here.

Regardless of the preferred form of transmission, however, the following points must always be taken into account:

Authentication
Data query
Data transformation
Data output
Caching

Authentication: Querying data from the CaaS requires an API Key, which must be protected against unauthorized accesses. It has the status of a password and must therefore be treated accordingly. Otherwise the contents stored in the CaaS are freely accessible.
Data query: When retrieving editorial content from the CaaS, it is important to retrieve the correct data. For this reason it is important to ensure that the product and category information used in FirstSpirit is always assignable to the real data in the shop. This requires a mapping that is based on unique IDs and must already be specified by the bridge. The IDs are in turn stored in the form data of a FirstSpirit element and transferred to the CaaS via release. Based on the IDs, it is thus possible to retrieve the FirstSpirit data stored in the CaaS as well as to link it to the shop data.

Unlike editorial content, information about the structure is stored in the NavigationService. For the implementation of a navigation, any data queries must therefore be directed against it.

Data transformation: The CaaS persists the data passed to it in JSON format in the form of content fragments. Some of these are very nested and also contain information that is irrelevant for the output in the storefront. For this reason, it makes sense to perform a transformation in the first step of their processing. In this step, it is recommended to reduce the data to the essentials and transfer it to a format that is optimal for the storefront. Furthermore it is important to ensure that linked information, such as media URLs, is resolved correctly.
Data output: The storefront still handles the output of the editorial content. However, it no longer obtains it exclusively from the shop’s backend, but also from the CaaS. The storefront links the data together to deliver it in a combined view.

Just as when retrieving data from the CaaS, it is important to ensure that the output of the product and category information used in FirstSpirit always matches the real shop data. This includes not only the display of the correct content, but also its correct placement. Within the reference project FirstSpirit Connect for Commerce Reference Project included in the delivery, the maintainable areas of a shop page are represented by the content areas of a FirstSpirit page template. Sections can be added to them; each one corresponds to the equivalent component of the shop page. This must be taken into account and implemented when outputting the editorial content.
Caching: The content displayed in the storefront is dynamically determined from the CaaS. Each call to the shop page thus generates a CaaS query. This would lead to extensive data volume, especially during certain events, such as Black Friday. To avoid both performance problems and the costs of high data traffic, a project-specific implementation of a caching strategy is highly recommended.

7.3. Create Reference Page Executable

For the generation of Shop Driven Pages the FirstSpirit Connect for Commerce - Create Reference Page Executable is available. This can be called via the execute method of TPP-SNAP-API.

The following arguments are passed to the executable in the form of a JavaScript object when it is called:

id (required)
fsPageTemplate (required)
type - (required)
displayNames - (optional)

Example Method to call the FirstSpirit Connect for Commerce - Create Reference Page Executable

const createReferencePage = () => {
        payload = {
            id: 'pageId',
            fsPageTemplate: 'product',
            type: 'product',
            displayNames: {
                DE: 'Displayname DE',
                EN: 'Displayname EN'
            }
        };
        TPP_SNAP.execute('class:FirstSpirit Connect for Commerce - Create Reference Page', payload);
};

The FirstSpirit Connect for Commerce module creates a page with the passed values. id corresponds to the identifier of the page in the shop system and is stored in the FormData of the page to be created. type corresponds to the page type (product, category or content) and is also stored in the FormData of the page. This combination makes a page uniquely identifiable and assignable to a page in the shop system. Pages of type product always have an equivalent in the products report, pages of type category have an equivalent in the category report and pages of type content have an equivalent in the content page report. The fsPageTemplate specifies which FirstSpirit page template the page to be created is based on. The optional displayNames object defines the desired display names in the languages available in the FirstSpirit project. It is important that the attribute names correspond to the abbreviation of the language configured in FirstSpirit. If no displayNames are passed, or they are not passed for all project languages, the display name for the missing languages will be set according to the scheme <pageType>_<id>.

8. Error Codes

Errors occuring when using the Frontend API have an error code assigned to allow for easier problem solving. The following table contains these codes and possible fixes for the problems.

Code	Description	Possible solution
0000	Unknown error
1020	Template not mapped	Check template mapping
1030	Field not unique	Try a different value
1040	Mandatory field not filled	Provide a value
2010	Page already exists in FirstSpirit	Check if the page is in the CaaS
2020	Template not mapped	Check template mapping
2030	Invalid page type	Use either "product", "category" or "content"
2040	Invalid display names format	Check the format of the display names when creating a shop driven page
2050	A required parameter is missing	Check if all mandatory parameters are sent correctly when creating a shop driven page
3010	FirstSpirit cannot connect to the bridge	Check configuration
3020	FirstSpirit receives 401 from bridge	Check configuration
3030	FirstSpirit receives 500 from bridge	Check the bridge logs
3040	FirstSpirit receives 408 from bridge	Check the bridge service
3050	FirstSpirit cannot connect to the ContentCreator extension	Check configuration
8010	Frontend API server cannot connect to CaaS	Check configuration
8020	Frontend API server receives 401 from CaaS	Check configured API key
8030	Frontend API server cannot connect to Navigation Service	Check configuration
8040	Frontend API server receives 401 from Navigation Service	Check configured API key
8050	Cannot create section using TPP	Check is page exists in FirstSpirit
8060	Page not found in CaaS after creation	Check CaaS deployment
8070	Missing parameter in request to Frontend API server for findPage	Provide mandatory parameters
8080	Missing parameter in request to Frontend API server for fetchNavigation	Provide mandatory parameters
8090	Cannot create page (unknown reason)
8100	Cannot find new page in CaaS	Check if page exists in CaaS

Code

Description

Possible solution

0000

Unknown error

1020

Template not mapped

Check template mapping

1030

Field not unique

Try a different value

1040

Mandatory field not filled

Provide a value

2010

Page already exists in FirstSpirit

Check if the page is in the CaaS

2020

Template not mapped

Check template mapping

2030

Invalid page type

Use either "product", "category" or "content"

2040

Invalid display names format

Check the format of the display names when creating a shop driven page

2050

A required parameter is missing

Check if all mandatory parameters are sent correctly when creating a shop driven page

3010

FirstSpirit cannot connect to the bridge

Check configuration

3020

FirstSpirit receives 401 from bridge

Check configuration

3030

FirstSpirit receives 500 from bridge

Check the bridge logs

3040

FirstSpirit receives 408 from bridge

Check the bridge service

3050

FirstSpirit cannot connect to the ContentCreator extension

Check configuration

8010

Frontend API server cannot connect to CaaS

Check configuration

8020

Frontend API server receives 401 from CaaS

Check configured API key

8030

Frontend API server cannot connect to Navigation Service

Check configuration

8040

Frontend API server receives 401 from Navigation Service

Check configured API key

8050

Cannot create section using TPP

Check is page exists in FirstSpirit

8060

Page not found in CaaS after creation

Check CaaS deployment

8070

Missing parameter in request to Frontend API server for findPage

Provide mandatory parameters

8080

Missing parameter in request to Frontend API server for fetchNavigation

Provide mandatory parameters

8090

Cannot create page (unknown reason)

8100

Cannot find new page in CaaS

Check if page exists in CaaS

9. Legal notices

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.

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

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