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, category and content page data from the shop. A shop-specific bridge implementation is essential for a successful connection.

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.

Diagram which illustrates the bridges role in context of the Connect for Commerce overall system
Figure 1. 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 as reference implementations 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 the npm module fcecom-bridge-commons. This is the basic framework of a bridge, which only needs to be extended with the shop-specific functions. It serves exclusively as a starting point for an individual implementation of a bridge.

  • 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 only provides support and updates 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 enables both the display of the pages created with FirstSpirit in the shop system as well as the pages that already 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.

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.

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

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