FirstSpirit Connect (Headless): For SAP Commerce Cloud

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.

Editors are provided full access to the SAP Commerce Cloud product catalog and can supplement it with editorial content such as shoppable videos. The content is thereby maintained using an intuitive WYSIWYG interface provided by FirstSpirit. They also have the ability to create new content. The content can be integrated in pages of various types - on the homepage as well as on landing pages or product and category pages. 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 Spartacus Storefront. However, the Storefront no longer obtains this content exclusively from SAP Commerce Cloud, 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, Spartacus and the SAP Commerce Cloud thus has an architecture in which the editorial backend of FirstSpirit is clearly separated from the Spartacus Storefront.

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 and the B2C demo shop. Mention of the Storefront refers to the Spartacus Storefront in all cases.

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

1.1. Range of functions

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

Figure 1. Data flow

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 content, the Spartacus Storefront delivers this content.

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:

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 Commerce Cloud. In addition, it queries the content of the respective CaaS instance and links it 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 content, its 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 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 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 content. 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.

Figure 3. Low-level architecture

1.3. Concept

The FirstSpirit Connect (Headless): For SAP Commerce Cloud integration enables editorial content for the Storefront 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 Commerce Cloud. For this, the processing of content in both systems must be coordinated and be mutually compatible. The sub-chapters below describe the underlying concept used to achieve this compatibility.

1.3.1. Pages

Similar to FirstSpirit, the pages in Commerce Cloud 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 Reference Project included in the delivery, the slots are represented by the content areas of a page template. Sections can be added to them; each one corresponds to a component (see figure Page Rendering).

FirstSpirit can thus be used to generate components that are displayed in a page via slots.

Figure 4. Page Rendering

1.3.2. Page types

As described in the previous chapter, the maintenance of editorial content both in FirstSpirit and in the Commerce Cloud is based on a page. The integration differentiates between Shop Driven Pages and the FirstSpirit Driven Pages.

Shop Driven Pages: In contrast to the FirstSpirit Driven Pages, the Shop Driven Pages have a page both in FirstSpirit and in the Commerce Cloud. 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.
FirstSpirit Driven Pages: FirstSpirit Driven Pages exist exclusively in FirstSpirit and do not have an associated page in the Commerce Cloud. 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.

The storage of the contents is identical for both page types: They are transferred to the CaaS and persisted in it. At the time a page is queried, the Storefront checks whether a page exists for a given ID in both the CaaS and the Commerce Cloud. If this is the case, it is a Shop Driven Page. Otherwise, if only the CaaS contains a page for the corresponding ID, it is a FirstSpirit Driven Page. If neither system returns a page, the Storefront displays an error page.

1.3.3. Preview

The integration effected by the FirstSpirit Connect (Headless): For SAP Commerce Cloud 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 slots integrate the generated components.

To present the preview of a page, FirstSpirit therefore determines its current view in the Spartacus Storefront. This in turn retrieves the editorial content from the Preview CaaS and replaces the corresponding components. FirstSpirit then displays the result in the ContentCreator using the Omnichannel Manager.

2. Commerce Cloud - Installation and configuration

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 libraries which must be integrated and configured on the Spartacus side.

The following chapters explain all necessary steps for installing and configuring the libraries and the required Commerce Cloud expansions.

The FirstSpirit Connect (Headless): For SAP Commerce Cloud integration requires the Commerce Cloud (in version 19.05 or higher) and the Spartacus Storefront in version 4.x.

2.1. OAuth configuration

The FirstSpirit Connect (Headless): For SAP Commerce Cloud module requires OAuth authentication to query information from Commerce Cloud. For this purpose, an OAuth client must be configured within Commerce Cloud.

There are two options for creating this type of OAuth client:

Manually, in the back office under System OAuth OAuth Clients
Automatically, by importing the following ImpEx
(in the Hybris Admin Console under Console ImpEx Import)

ImpEx

INSERT_UPDATE OAuthClientDetails;clientId[unique=true] ;resourceIds;scope ;authorizedGrantTypes ;authorities ;clientSecret;registeredRedirectUri
;firstspirit ;hybris ;extended,previewwebservices;authorization_code,refresh_token,password,client_credentials;ROLE_TRUSTED_CLIENT ;secret; ;

2.2. Integration and configuration of the libraries

In the system realized by the FirstSpirit Connect (Headless): For SAP Commerce Cloud integration the Storefront takes over the delivery of the content. It queries the content from both the Commerce Cloud and the respective CaaS instance and links them together. For this purpose it must be extended by the fs-spartacus-bridge library. In order to display and edit the content originating from the reference project, the integration of the libraries fs-spartacus-view-components and fs-tpp-api is also required. Furthermore, the fs-spartacus-common library is required. It contains classes that are used by both the bridge and the Angular UI components.

The libraries are provided in the form of npm packages, which can be installed using the following commands. Note that no command is given for the fs-tpp-api library, since its installation is done automatically.

Installation commands

npm install fs-spartacus-bridge
npm install fs-spartacus-view-components
npm install fs-spartacus-common

Additional CSS is required for displaying the editing functionality in the ContentCreator. This is included in the bridge and must be imported into the styles.scss file of the Storefront afterwards.

Integration of the CSS file

@import '~fs-spartacus-bridge/styles/index';

Furthermore, in the last step of the installation the Angular UI components and the bridge must be included in the imports array of the @NgModules in the main module of the Spartacus application (app.module.ts). In contrast to the UI components, the bridge thereby requires different information for each BaseSite. In addition to an optional fallback language and various CaaS information, it expects a definition of the Shop and FirstSpirit Driven Pages, whose processing is to be enabled in the ContentCreator.

Specifying a fallback language provides the ability to access content in another language if no content exists for the displayed language. This allows content to be presented quickly and easily without being fully translated. In order to use this feature, the specification of a fallback language in the CaaS locale format is required (for example en_GB).

To use the fallback language specified in the bridge configuration, the FirstSpirit section template used must contain the input component st_languageFallbackEnabled and its associated rule. Otherwise, the fallback language cannot be enabled.

Among others, the CaaS information includes the tenant ID and the project ID: The tenant ID is a unique identifier set by the Crownpeak Technology GmbH, and defined in the configuration dialog of the CaaS service. The project ID corresponds to the UUID of the FirstSpirit project used. It is a part of the CaaS URL and in this follows the tenant ID. In turn, the CaaS URL is visible in the configuration dialog of the CaaS project component. More information about the scheme of the CaaS URL can be found in the CaaS Connect module documentation.

The CaaS information required for the configuration is provided with the integration by the Crownpeak Technology GmbH. In case of questions the Technical Support offers expert support.

For the defined pages, the editable slots and optionally a merge strategy must also be configured. The merge strategy defines how the contents that are maintained for a slot on both the Commerce Cloud and the FirstSpirit side are merged. By default, the FirstSpirit content replaces the existing Commerce Cloud content in a slot.

The following code block shows the configuration required for the reference project. It defines various Shop and FirstSpirit Driven Pages for whose processing the configuration is mandatory.

Extension of the import array

import { APPEND, FsSpartacusBridgeModule } from 'fs-spartacus-bridge';
import { FsSpartacusViewComponentsModule } from 'fs-spartacus-view-components';
import { FirstSpiritManagedPage, fromSlotList } from 'fs-spartacus-common';
import { NgModule } from '@angular/core';

@NgModule({
   imports: [
      FsSpartacusViewComponentsModule,
      FsSpartacusBridgeModule.withConfig({
         bridge: {
            [BaseSite uid]: {
               fallbackLanguage: 'en_GB',
               caas: {
                  baseUrl: 'CAAS BASE URL',
                  project: 'PROJECT ID',
                  apiKey: 'CAAS API KEY',
                  apiKeyPreview: 'PREVIEW CAAS API KEY',
                  tenantId: 'TENANT ID'
               },
               firstSpiritManagedPages: [
                  FirstSpiritManagedPage.enhanceSapPages('CartPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.enhanceSapPages('ProductDetailsPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.enhanceSapPages('CategoryPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.enhanceSapPages('ProductListPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot'))
                  FirstSpiritManagedPage.enhanceSapPages('ProductListPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.integrateFsDrivenPagesIntoSapSkeleton(
                     'DummyCampaignPageWithHeader',
                     PageType.CONTENT_PAGE,
                     'campaign_page_with_header',
                     fromSlotList(
                        'BottomHeaderSlot',
                        'Section1', 'Section2C', 'Section3',
                        'PreFooterSlot'
                     )
                  ),
                  FirstSpiritManagedPage.integrateFsDrivenPages(
                     'campaign_page_without_header',
                     fromSlotList(
                        'BottomHeaderSlot',
                        'NarrowContentSection', 'WideContentSection', 'BottomNarrowSection',
                        'PreFooterSlot'
                     )
                  )
               ]
            }
         }
      })
   ]
})
export class AppModule { }

2.2.1. Connection of various BaseSites

For the implementation of different country or store pages Spartacus offers the so-called Multi-Site Configuration. It is used to connect different BaseSites, each corresponding to such a page.

The FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud integration allows the connection of any number of BaseSites. For this, only the different BaseSite UIDs have to be added to the bridge configuration. For each BaseSite, the bridge also expects an optional fallback language, various CaaS information, and the definition of the Shop and FirstSpirit Driven Pages, whose processing is to be enabled in the ContentCreator.

The following code example shows such a configuration in an abbreviated form:

Configuration of various BaseSites

import { APPEND, FsSpartacusBridgeModule } from 'fs-spartacus-bridge';
import { FsSpartacusViewComponentsModule } from 'fs-spartacus-view-components';
import { FirstSpiritManagedPage, fromSlotList } from 'fs-spartacus-common';
import { NgModule } from '@angular/core';

@NgModule({
   imports: [
      FsSpartacusViewComponentsModule,
      FsSpartacusBridgeModule.withConfig({
         bridge: {
            [BaseSite uid]: {
               fallbackLanguage: 'en_GB',
               caas: {
                  baseUrl: 'CAAS BASE URL',
                  project: 'PROJECT ID',
                  apiKey: 'CAAS API KEY',
                  apiKeyPreview: 'PREVIEW CAAS API KEY',
                  tenantId: 'TENANT ID'
               },
               firstSpiritManagedPages: [
                  FirstSpiritManagedPage.enhanceSapPages('CartPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  ...
               ]
            },
            [BaseSite uid]: {
               fallbackLanguage: 'en_US',
               caas: {
                  ...
               },
               firstSpiritManagedPages: [
                  ...
               ]
            },
                        [BaseSite uid]: {
               fallbackLanguage: 'de_DE',
               caas: {
                  ...
               },
               firstSpiritManagedPages: [
                  ...
               ]
            }
         }
      })
   ]
})
export class AppModule { }

2.2.2. Definition of the Shop and FirstSpirit Driven Pages

For the maintenance of editorial content, the integration distinguishes between Shop and FirstSpirit Driven Pages. They differ in the fact that the Shop Driven Pages have a page both in FirstSpirit and in the Commerce Cloud. In contrast, the FirstSpirit Driven Pages exist exclusively in FirstSpirit.

In order to enable the processing of these pages in the ContentCreator, they must be configured in the Bridge. The configuration differs depending on the page type.

Shop Driven Pages

In the case of Shop Driven Pages, the name of the Commerce Cloud template and the editable slots as well as optionally a merge strategy must be specified in the configuration. The mapping between the defined Commerce Cloud template and the FirstSpirit template is done in the project settings.

Example configuration - Shop Driven Page

firstSpiritManagedPages: [
   FirstSpiritManagedPage.enhanceSapPages('StoreFinderPageTemplate', [
      { name: 'BottomHeaderSlot' },
      { name: 'MiddleContent', mergeStrategy: APPEND }
   ])
]

FirstSpirit Driven Pages

FirstSpirit Driven Pages exist exclusively in FirstSpirit and do not have an associated page in the Commerce Cloud. They can either use the layout of a Shop Driven Page or their own layout, which is defined in the Storefront. This distinction must also be considered in the configuration: In the first case, the UID of the Commerce Cloud page to be used, its PageType as well as the FirstSpirit template and the editable slots must be specified. In the second case, only the FirstSpirit template and the slots need to be specified. In both cases, the styling of the FirstSpirit Driven Pages is done in Angular, for example, in the styles.scss file of the Storefront.

Example configuration - FirstSpirit Driven Pages

firstSpiritManagedPages: [

   // Case 1: The FirstSpirit Driven Page uses the layout of a Shop Driven Page.
   FirstSpiritManagedPage.integrateFsDrivenPagesIntoSapSkeleton(
      'DummyCampaignPageWithHeader',
      PageType.CONTENT_PAGE,
      'campaign_page_with_header',
      fromSlotList('BottomHeaderSlot', 'Section1', 'Section2C', 'Section3', 'PreFooterSlot')),

   // Case 2: The FirstSpirit Driven Page uses a layout defined in the Storefront.
   FirstSpiritManagedPage.integrateFsDrivenPages(
      'campaign_page_without_header',
      fromSlotList('BottomHeaderSlot', 'NarrowContentSection', 'WideContentSection',
         'BottomNarrowSection', 'PreFooterSlot')
   )
]

The Commerce Cloud page specified in the first case must correspond to a dummy page, which is empty except for the desired layout. This means that it defines the layout and has, for example, a general header and footer, but does not contain any other content. Such a page is required for every layout that should be usable by FirstSpirit Driven Pages. The SAP Blog describes the creation of new pages in Spartacus.

In the second case, the FirstSpirit Driven Page does not have a mapping to a Commerce Cloud page and therefore no layout of such a page is assigned to it. Thus the Storefront does not know which slots exist and in which order they should be output. To make this information available to the Storefront, the layoutConfig configuration must be extended as follows. The shown code snippet represents the configuration for the reference project.

On the Spartacus side, there exist several general slots, which are output without additional configuration. Their specification is therefore only required in the bridge`s configuration, but not in the layoutConfig configuration. An example for this kind of slots is the BottomHeaderSlot from the previous code snippet.

Extension of the layoutConfig configuration

import {layoutConfig, LayoutConfig} from '@spartacus/storefront';

const config: LayoutConfig = JSON.parse(JSON.stringify(layoutConfig));
config.layoutSlots.footer['slots'].unshift('PreFooterSlot');

config.layoutSlots.campaign_page_without_header = {
  slots: ['NarrowContentSection', 'WideContentSection', 'BottomNarrowSection']
 };

export const customLayoutConfig = config;

Requirements on the FirstSpirit side

Both the Shop and the FirstSpirit Driven Pages require corresponding page templates in the FirstSpirit project in which the input components pt_seoUrl and pt_cc_identifier must be configured. The input component pt_seoUrl enables the definition of an SEO url and must therefore be editable. In contrast, the input component pt_cc_identifier is a hidden component. It is filled automatically and ensures the accessibility of the page in the ContentCreator.

In addition, it must be ensured that the content areas of the FirstSpirit templates match the configured slots: For each defined slot, the page template must have a content area with the same name. Otherwise, the editorial content will be ignored by the Storefront and not be output in the live state.

The mapping between the configured slots and the content areas of the FirstSpirit page templates is not case-sensitive. The names Section1 and section1 are therefore considered identical and are successfully mapped to each other.

2.2.3. Merge strategies

With the FirstSpirit Connect (Headless): For SAP Commerce Cloud integration, the Storefront queries content from both the Commerce Cloud and the respective CaaS instance and links them together before delivery. Therefore it must be extended by the fs-spartacus-bridge library, which needs to be integrated and configured as described in the previous chapter. During configuration, a merge strategy can optionally be defined. This determines how the content that is maintained for a slot on both the Commerce Cloud and the FirstSpirit side is merged.

The following options are available:

REPLACE: The merge strategy REPLACE is the default setting of the bridge and therefore does not need to be specified explicitly. It causes the content maintained in FirstSpirit to overwrite the Commerce Cloud content contained in a slot. As a result, only the FirstSpirit content is visible on the corresponding page.
APPEND: If a page should show both the Commerce Cloud and FirstSpirit content for a slot, it is possible to choose between the merge strategies APPEND and PREPEND. With the merge strategy APPEND the corresponding page displays the content maintained in FirstSpirit below the Commerce Cloud content existing for a slot.
PREPEND: The PREPEND merge strategy is equivalent to the APPEND option mentioned above. However, in this case, the page displays the FirstSpirit content for a slot above the content coming from the Commerce Cloud.

2.3. Creation of a dummy page

For the maintenance of editorial content, the integration distinguishes between Shop and FirstSpirit Driven Pages. FirstSpirit Driven Pages can either use their own layout defined in the Storefront or the layout of a Shop Driven Page.

In the second case, a dummy page must exist in the Commerce Cloud, which is empty except for the desired layout. This means that it has, for example, a general header and footer, but does not contain any other content.

A dummy page can be created using an ImpEx script. The script shown in the following code block generates the dummy page for the FirstSpirit Driven Pages included in the reference project. It is based on the LandingPage2Template and contains only a header and a footer. The existence of the dummy page is mandatory for using the FirstSpirit Driven Pages.

Further information on how to create new pages in Spartacus is included in the SAP blog.

ImpEx-Skript

$contentCatalog=electronics-spaContentCatalog
$contentCVOnline=catalogVersion(CatalogVersion.catalog(Catalog.id[default=$contentCatalog]),\
CatalogVersion.version[default=Online])[default=$contentCatalog:Online]

$siteResource=jar:de.hybris.platform.spartacussampledataaddon.constants.\
   SpartacussampledataaddonConstants&/spartacussampledataaddon/import/\
   contentCatalogs/electronicsContentCatalog

# create dummy page in online catalog
INSERT_UPDATE ContentPage;$contentCVOnline[unique=true];uid[unique=true];name;\
   masterTemplate(uid,$contentCVOnline);label;defaultPage[default='true'];\
   approvalStatus(code)[default='approved'];homepage[default='false']
;;DummyCampaignPageWithHeader;Dummy Campaign Page With Header;LandingPage2Template;/dummycampaignpagewithheader

# create empty slots for page
INSERT_UPDATE ContentSlot;$contentCVOnline[unique=true];uid[unique=true];name;active
;;Section1-DummyCampaignPageWithHeader;Section1 Slot for DummyCampaignPageWithHeader;true
;;Section2A-DummyCampaignPageWithHeader;Section2A Slot for DummyCampaignPageWithHeader;true
;;Section2B-DummyCampaignPageWithHeader;Section2B Slot for DummyCampaignPageWithHeader;true
;;Section2C-DummyCampaignPageWithHeader;Section2C Slot for DummyCampaignPageWithHeader;true
;;Section3-DummyCampaignPageWithHeader;Section3 Slot for DummyCampaignPageWithHeader;true
;;Section4-DummyCampaignPageWithHeader;Section4 Slot for DummyCampaignPageWithHeader;true
;;Section5-DummyCampaignPageWithHeader;Section5 Slot for DummyCampaignPageWithHeader;true
;;BottomHeaderSlot-DummyCampaignPageWithHeader;Bottom Header Slot for DummyCampaignPageWithHeader;true

# configure content slots for page
INSERT_UPDATE ContentSlotForPage;$contentCVOnline[unique=true];uid[unique=true];\
   position[unique=true];page(uid,$contentCVOnline)[unique=true];contentSlot(uid,$contentCVOnline)[unique=true]
;;Section1-DummyCampaignPageWithHeader;Section1;DummyCampaignPageWithHeader;Section1-DummyCampaignPageWithHeader
;;Section2A-DummyCampaignPageWithHeader;Section2A;DummyCampaignPageWithHeader;Section2A-DummyCampaignPageWithHeader
;;Section2B-DummyCampaignPageWithHeader;Section2B;DummyCampaignPageWithHeader;Section2B-DummyCampaignPageWithHeader
;;Section2C-DummyCampaignPageWithHeader;Section2C;DummyCampaignPageWithHeader;Section2C-DummyCampaignPageWithHeader
;;Section3-DummyCampaignPageWithHeader;Section3;DummyCampaignPageWithHeader;Section3-DummyCampaignPageWithHeader
;;Section4-DummyCampaignPageWithHeader;Section4;DummyCampaignPageWithHeader;Section4-DummyCampaignPageWithHeader
;;Section5-DummyCampaignPageWithHeader;Section5;DummyCampaignPageWithHeader;Section5-DummyCampaignPageWithHeader
;;BottomHeaderSlot-DummyCampaignPageWithHeader;BottomHeaderSlot;DummyCampaignPageWithHeader;BottomHeaderSlot-DummyCampaignPageWithHeader

# language settings
$language=en
INSERT_UPDATE ContentPage;$contentCVOnline[unique=true];uid[unique=true];title[lang=$language]
;;DummyCampaignPageWithHeader;Dummy Campaign Page With Header

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

To use the FirstSpirit Connect (Headless): For SAP Commerce Cloud module, the CaaS Connect module must also be configured. The steps required to do this are described in the CaaS Connect Documentation.

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. These groups possess different rights, which are selected depending on their tasks and defined for the different stores. Users outside these groups are not authorized to use the reference project by default.

If there is a need for additional accounts or groups, their creation must be requested by contacting the Technical Support. For new accounts, the following information is required:

first and last name
e-mail address
groups to be assigned

3.1. Configuration of the project component

A project-specific configuration is required in order to use the FirstSpirit Connect (Headless): For SAP Commerce Cloud module. It is set up using the project component, which is already added to the reference project supplied.

To use the FirstSpirit Connect (Headless): For SAP Commerce Cloud module, the CaaS Connect module must also be configured. The necessary steps are described in the CaaS Connect Documentation.

The reference project also includes the project component of the CXT ContentCreator Extension. This contains a predefined configuration, the modification of which can lead to a change in the behavior of the ContentCreator. An adjustment of the configuration is therefore only to be made after prior consultation with the Technical Support.

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

Figure 5. Project properties - Project components

A list of all existing project components is displayed in the main panel. Select the entry FirstSpirit Connect (Headless): For SAP Commerce Cloud for SAP Commerce Cloud Project Configuration and open the corresponding configuration dialog via Configure.

The dialog is organized in five tabs, of which currently only the fields of the tabs General, Product DAP and Category DAP are to be considered. The following subchapters explain them in detail. The tabs Preview and Content currently do not have any functionality.

3.1.1. General

The configuration dialog of the project component first contains the tab General. The information to be defined in it must be known to the FirstSpirit-Server for a connection to the Commerce Cloud.

Figure 6. Project component - General

URI: Within the tab General the URI of the Commerce Cloud instance has to be entered first. It enables the FirstSpirit-Server to establish a connection to the Commerce Cloud.
Connection timeout/Connection retries: Using the two fields Connection timeout and Connection retries the time span (in seconds) and the number of attempts can be defined, which the FirstSpirit-Server uses to establish a connection to the Commerce Cloud.

The FirstSpirit-Server requires OAuth authentication to retrieve information from the Commerce Cloud. The required authentication data must be entered in the following fields of the General tab. The other tabs enable the overwriting of this information and therefore have the same fields. The overwriting is done by activating the checkbox Override general OAuth settings in one of the other tabs.

Auth Server URI: To connect to the Commerce Cloud, the FirstSpirit-Server requires the specification of the default endpoint for OAuth authentication. The URI of this endpoint must be entered relatively to the URI of the Commerce Cloud instance.
Username/Password: The access data with which the authentication is carried out must be entered in the fields Username and Password. Usually this is the data of a technical Commerce Cloud account.
OAuth Client ID: This field is used to enter the default client ID used for authentication. It is created during the configuration of the OAuth Client and defines the access rights of the technical account.
OAuth Client Secret: In addition to the Client ID, the specification of the associated Client Secret is expected at this point.
OAuth Grant Type