FirstSpirit Connect

For SAP Commerce Cloud

e-Spirit AG

2024-01-12
Table of Contents

1. Introduction

FirstSpirit is used for creating versatile and project-specific content. Thanks to the FirstSpirit Connect for SAP Commerce Cloud module, it is now possible to transfer this content to the SAP Commerce Cloud e-commerce shop system and use it there.

In the remainder of this document, the abbreviated form Commerce Cloud will be used instead of SAP Commerce Cloud. This abbreviated form refers to SAP Commerce Cloud in all cases.

The module combines the functional strengths of both systems, delivering the key advantages that each offers and creating a highly effective overall system made up of two areas that work in parallel and are largely decoupled from one another:

Components on the FirstSpirit side
These components are used for creating and maintaining editorial data. The data is transferred in JSON and media format to the relevant Content as a Service instance, and queried from this instance by the Commerce Cloud.
Components on the Commerce Cloud side
These components are used for integrating editorial content created in FirstSpirit. Commerce Cloud integrates this data into the shop.

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

This document is intended for server administrators and therefore only describes the installation and configuration of the module as well as the import of the reference project on the FirstSpirit server. All steps to be performed in the project and the functionalities provided with the integration are described in the FirstSpirit Connect for SAP Commerce Cloud documentation.

1.1. Range of functions

FirstSpirit Connect allows editors to:

  • Create Commerce Cloud content using FirstSpirit for one or more sites of a Commerce Cloud instance
  • Access to product and category information
  • Display shop elements and editorial content in the FirstSpirit preview simultaneously
  • Transfer of content to Commerce Cloud

The corresponding functions are made available when the module is installed and configured in ContentCreator.

Familiar FirstSpirit tools are used to maintain the content, meaning that editors who are already familiar with FirstSpirit do not require any additional knowledge. The content is made available to Commerce Cloud as part of a deployment so that it can be imported. It integrates the information into the shop.

As far as Commerce Cloud is concerned, this means there is no difference when it comes to delivering editorial content to the live state. Even if the FirstSpirit server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.

1.2. Architecture

FirstSpirit and Commerce Cloud are linked by an architecture made up of a range of components (see figure Architecture).

These components are:

  • The modules installed on the FirstSpirit server:

    • FirstSpirit Connect
    • Omnichannel Manager
    • Content as a Service
  • Commerce Cloud-Instanz
Architecture
Figure 1. Architecture


The individual components always interact in accordance with the following schema:

  1. In FirstSpirit, the editorial content is created and edited in ContentCreator. With the help of the Omnichannel Manager, the staged storefront of the Commerce Cloud is embedded in it.
  2. The Staged Storefront in turn accesses the Preview CaaS and determines the current FirstSpirit contents from it. It also integrates the Omnichannel Manager JavaScript, which enables the content in ContentCreator to be edited and highlighted.
  3. The product and category information is provided via a report. The report accesses the product catalog and obtains the required data via the CMS WebServices interface of the Commerce Cloud.
  4. The module also uses the CMS WebServices interface. It triggers the automatic synchronization of content pages created or modified in FirstSpirit in the content catalog of the staged storefront. The automatic synchronization of the information in the online storefront must always be developed on a project-specific basis, so there is no predefined mechanism for this process.
  5. The released editorial content is transferred via a generation process to the Online CaaS. This process makes the content available to the online storefront, which is then used to integrate it into the shop.

Commerce Cloud thus represents the main component in this architecture. In addition to providing all shop functionality, this system queries content created or maintained in FirstSpirit from Online CaaS and provides it to customers. There is only one loose link between the two systems; they primarily work in parallel with one another. If the FirstSpirit server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.

1.3. Technical requirements

To use the FirstSpirit Connect module, the following technical requirements must be met:

  • The latest versions of the FirstSpirit Connect and Content as a Service modules
  • Omnichannel Manager in version 1.2.27 or higher
  • FirstSpirit 2018-11 (Legacy or Isolated mode)
  • Java 8 or 11
  • SAP Commerce Cloud 18.08 to 20.11

When using the supplied FirstSpirit Connect Reference Project, the latest version of the BasicWorkflows module must also be installed.

The version number of the delivery differs from the version numbers of the individual components of the delivery. It follows a scheme of two-digit year, month number and the number of the release within the respective month (for example: 20.10.0 for the first release in October 2020) In contrast, the module, the reference project, and the add-on receive their own version numbers, which are separated from the version number of the delivery.

2. Installation and Configuration

Various components must be installed and configured on the FirstSpirit side in order to use the functions of the FirstSpirit Connect module. The following subchapters explain the steps required.

2.1. Installing the modules

In order to provide the functions of the FirstSpirit Connect module, the modules Content as a Service and Omnichannel Manager are additionally required, which must also be installed on the FirstSpirit server. Furthermore, when using the supplied FirstSpirit Connect Reference Project, the BasicWorkflows and the CXT ContentCreator Extension must also be installed.

The delivery only includes the FirstSpirit Connect module. The Content as a Service and Omnichannel Manager modules as well as the BasicWorkflows and the CXT ContentCreator Extension can be obtained from Technical Support.

To install the modules, open the ServerManager and select Server properties → Modules.

Server properties - Module installation
Figure 2. Server properties - Module installation


The main panel contains a list of all modules installed on the FirstSpirit server. After clicking Install, select the following files one after the other and confirm your selection with Open:

  • contentconnect-sap-module-<Versionnumber>.fsm
  • caas-<Versionnumber>.fsm
  • fs-tpp-api-<Versionnumber>.fsm
  • cxt-cc-extension-<Versionsnummer>.fsm (only required when using the reference project)
  • basicworkflows-fsm-<Versionsnummer>.fsm (only required when using the BasicWorkflows)

After the successful installation, the folders FirstSpirit Connect for SAP Commerce Cloud, Content as a Service, FirstSpirit ThirdPartyPreview, and optionally the folders BasicWorkflows and CXT ContentCreator Extension were added to the list. Each of which must be given All permissions.

The Content as a Service module contains a service used to define a standard configuration. The steps required to do this are described in the Content as a Service Manual.

After any module installation or update, the FirstSpirit server needs to be restarted.

2.2. Configuration of the FirstSpirit Connect module

When calling the Commerce Cloud API, an application interface key is required, which depends on the application environment used. This must be specified to the module via the configuration of the AIR Key Configuration Service.

Server properties - Module configuration
Figure 3. Server properties - Module configuration


The following two options are available for selection:

  • PRODUCTION: There is a productive use of the Commerce Cloud. This is usually the case in customer scenarios.
  • DEVELOPMENT: The Commerce Cloud is used for development or demo purposes.

After configuring the module, a restart of the FirstSpirit-Server is required.

2.3. Project import

Included in the delivery is the FirstSpirit Connect Reference Project, which must be installed on the FirstSpirit server. To do this, open the import dialog in the ServerManager via the menu item Project → Import and click the Local button to select the referenceproject-<VERSIONNUMBER>.tar.gz file from your local data system. Then assign a project name and description and confirm the import with Yes. After successful installation, the project is added to the list in the main panel.

Imported project in the ServerManager
Figure 4. Imported project in the ServerManager


In addition to the standard groups Everyone, Administrators and Developers, there are three further external user groups in the reference project: Editors, ChiefEditors and ProjectAdmins. The groups have different rights, which are selected according to their tasks and defined for the different stores. Users outside these groups are not allowed to use the reference project by default.

The usage of external groups requires an LDAP connection. Otherwise they are not usable and the rights set for them do not apply.

2.4. Adding the web components

The FirstSpirit Connect integration requires various web components to be added to the project used. Therefore open the Server Properties → Web applications panel in the ServerManager.

Within the main panel several tabs are visible, each with a list of the existing web components. Choose the ContentCreator tab and add the following web components:

  • BasicWorkflows_ContentCreator_Library (only required when using the BasicWorkflows)
  • CXT ContentCreator Extension Extension: WebApp for ContentCreator (only required when using the reference project)
  • FirstSpirit Connect for SAP Commerce Cloud Web App
  • FirstSpirit ThirdPartyPreview WebApp

Select the web components one after the other using the Add button and confirm each selection with OK.

Web components in the Server Properties
Figure 5. Web components in the Server Properties


Finally, select an Active web server in the tab using the selection box of the same name and start the installation by clicking the Install button. After successful installation, a dialog opens, in which the activation of the web server is to be confirmed.

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

4. Help

The Technical Support of the e-Spirit AG 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.