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:

ng architecture simple
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.

ng architecture
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:

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

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

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.

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