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.

The FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud integration links the Digital Experience Platform FirstSpirit with the e-commerce shop system SAP Commerce Cloud in combination with the Spartacus Storefront. It thus creates a powerful overall system that combines the functional advantages of these systems and enables the delivery of modern and personalized content.

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 (Headless): For SAP Commerce Cloud (Headless) for Commerce Cloud documentation.

If the expression "Commerce Cloud" is used in the remainder of this documentation, this refers to SAP Commerce Cloud in all cases.
This also applies to the short form "FirstSpirit Connect (Headless): For SAP Commerce Cloud", which within this documentation always refers to the FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud integration.

Furthermore, the entire document is geared towards connecting to the Spartacus Storefront. Mention of the Storefront refers to the Spartacus Storefront in all cases.

1.1. Range of functions

FirstSpirit Connect (Headless): For SAP Commerce Cloud allows to:

  • Access to 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 corresponding functions are made available when the module is installed and configured 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 Commerce Cloud.

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 affects neither the Storefront nor the Commerce Cloud.

1.2. Architecture

By default, the SAP shop architecture consists of the Commerce Cloud and the Spartacus Storefront. While, in this system, the Commerce Cloud provides all shop functionalities and persists all shop contents, the Spartacus Storefront delivers these contents.

With the FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud solution, FirstSpirit and the CaaS integrate into this architecture and extend the shop functionalities of the Commerce Cloud. The integration thus creates an overall system that combines the functional strengths of the individual systems. Within this overall system FirstSpirit and the Commerce Cloud represent the backend, while the CaaS forms the middleware and the storefront is the front end.

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

sp architecture simple
Figure 1. High-level architecture

Within the newly created overall system, the Storefront continues to deliver the content, which it by default obtains from the Commerce Cloud. In addition, it queries the contents of the respective CaaS instance and links them with those of the Commerce Cloud. For this purpose it is extended by the fs-spartacus-bridge library.

In contrast to the delivery of the contents, their creation and maintenance shifts from the Commerce Cloud 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 the preview and editing of external content in the ContentCreator (see figure Low-level architecture).

By embedding the Staged Storefront in the Omnichannel Manager, the editors are provided with a combined preview of the contents, which in this case originate from the preview CaaS and the Commerce Cloud. This way, the editors get the possibility to edit already existing shop pages in the ContentCreator. For this purpose, a variety of different components, such as shoppable videos, are available for them.

Product and category information is provided via a report in the ContentCreator. This report accesses the Product Catalog via the Commerce Cloud’s CMS WebServices interface and thus determines the necessary data.

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 into the shop together with the Commerce Cloud contents. In order to display content originating from the reference project, the Storefront must include the fs-spartacus-view-components library in addition to the bridge.

The overall system of FirstSpirit, Spartacus and the Commerce Cloud thus has an architecture in which the editorial backend of FirstSpirit is clearly separated from the Storefront. A maintenance of FirstSpirit affects neither the Storefront nor the Commerce Cloud.

sp architecture
Figure 2. Low-level architecture

2. Installation and Configuration

Various components must be installed and configured in order to use the functions of the FirstSpirit Connect (Headless): For SAP Commerce Cloud module. The following subchapters explain the steps required.

2.1. Installation of the modules

In order to provide the functions of the FirstSpirit Connect (Headless): For SAP Commerce Cloud module, the modules CaaS Connect 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, the CXT ContentCreator Extension and optionally TranslationStudio must also be installed.

The delivery contains only the FirstSpirit Connect (Headless): For SAP Commerce Cloud module. The CaaS Connect and Omnichannel Manager modules as well as the BasicWorkflows, the CXT ContentCreator Extension, and the TranslationStudio module are available from the Technical Support.

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

modules
Figure 3. Server properties - Module installation

The main panel displays 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-connect-<Versionnumber>.fsm

  • fs-tpp-api-<Versionnumber>.fsm

  • cxt-cc-extension-<Versionnumber>.fsm (only required when using the reference project)

  • basicworkflows-fsm-<Versionnumber>.fsm (only required when using the BasicWorkflows)

  • translationstudio-<Versionnumber>.fsm (only required when using TranslationStudio)

After the successful installation, the folders FirstSpirit Connect (Headless): For SAP Commerce Cloud for SAP Commerce Cloud, CaaS Connect, FirstSpirit ThirdPartyPreview and optionally the folders BasicWorkflows, CXT ContentCreator Extension and FirstSpirit TranslationStudio were added to the list. Each of which must have All rights.

The modules FirstSpirit Connect (Headless): For SAP Commerce Cloud, CaaS Connect, and CXT ContentCreator Extension require a configuration. The necessary steps are described in the FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for Commerce Cloud documentation and CaaS Connect Documentation.

After each installation or update of a module, the FirstSpirit server must be restarted.

2.2. Configuration of the FirstSpirit Connect (Headless): For SAP Commerce Cloud 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.

airkey config
Figure 4. 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

A part of the delivery is the reference project 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 spartacus-reference-project-<VERSION>.tar.gz file from your local data system. Then assign a project name and a description and confirm the import with Yes. After the successful installation, the project is added to the list in the main panel.

importedproject
Figure 5. 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 (Headless): For SAP Commerce Cloud 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: WebApp for ContentCreator

  • FirstSpirit Connect (Headless): For SAP Commerce Cloud 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.

sp webcomponents
Figure 6. 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 adding web components, see the FirstSpirit Manual for Administrators.

2.5. Adding language templates

FirstSpirit consistently pursues the concept of multiple languages and allows the output of different language variants. Within the overall system created with the FirstSpirit Connect (Headless): For SAP Commerce Cloud integration, the Storefront handles the delivery of the content and thus determines the language in which it is presented. For this reason, all languages available in the Storefront must be configured in the FirstSpirit project.

If languages available in the storefront are missing in the FirstSpirit project, no editorial content can be created for these languages. Due to this discrepancy, errors may occur.

For languages to be usable in a FirstSpirit project, the appropriate language templates must exist on the FirstSpirit server. To add them, open the Server Properties  Language templates panel in the ServerManager.

The main panel displays a list of all language templates already available. In the edit dialog that opens after clicking Add, enter a name, an abbreviation, a language code, and optionally a display name for the new language template. Confirm the entry with the OK button to complete the creation of the language template. After the successful configuration, the new language template is also visible in the list in the main panel.

Detailed information about the creation of language templates is available in the Online documentation for FirstSpirit.

FirstSpirit Connect (Headless): For SAP Commerce Cloud is a product of Crownpeak Technology GmbH, Dortmund, Germany.
Only a license agreed upon with Crownpeak Technology GmbH is valid for using the module.

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

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