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 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", which within this documentation always refers to the FirstSpirit Connect (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 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 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 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 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 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 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 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 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 library fs-spartacus-view-components 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.

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 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 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 module. The following subchapters explain the steps required.

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 module. It is set up using the project component, which is already added to the reference project supplied.

With the switch to Omnichannel Manager 3.0 it is necessary to additionally configure the project components CXT ContentCreator: Feature Configuration ProjectApp and CXT ContentCreator: Preview Configuration ProjectApp.
The necessary steps are described in the FirstSpirit Online documentation und Omnichannel Manager documentation.

The reference project already includes the project components required for the switch to Omnichannel Manager 3.0 and 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 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: In addition to the Client ID and Client Secret, OAuth authentication requires a Grant Type. Therefore the combo box offers two options: password and client credentials.
Test OAuth settings: By clicking on this button the connection to the Commerce Cloud can be tested. If overriding the OAuth authentication was activated in one of the other tabs, the settings stored in it will be taken into account.

3.1.2. Product DAP

In addition to the tab General, the configuration dialog of the project component has the tabs Product DAP and Category DAP. They are used to configure the reports in the ContentCreator, which require various information.

Figure 7. Project component - Product DAP

Collection

The product report in the ContentCreator lists the products originating from the Commerce Cloud and enables editors to use these products. The products can be queried via a REST endpoint, which must be known by the ContentCreator. It therefore has to be specified in this field.

PDP URL

The relative URL of a product detail page must be entered in this field. As a placeholder for the product code the expression {code} can be used. The default value is p/{code}.

Header/Extract/Icon/Thumbnail

By default, search results in the product report show the product name in the header, the catalogue ID in the extract, and a thumbnail. The fields Header, Extract, Icon, and Thumbnail allow the configuration of this information. For this purpose the following placeholders are available in addition to simple text entries:

${catalogId}
${catalogVersion}
${code}
${description}
${name}
${thumbnailMediaUrl}

The entries in the fields replace the standard information in the search results of the product report. Textual entries are adopted unchanged. If the fields remain empty, the search results display the standard information.

Override general OAuth settings

The fields for OAuth authentication enable the overwriting of the entries in the tab General. The overwriting is done by activating the checkbox Override general OAuth settings. Otherwise, the entries from the General tab will be used for authentication.

3.1.3. Category DAP

The tab Category DAP is equivalent to the tab Product DAP and is used to configure the category report in the ContentCreator.

Figure 8. Project component - Category DAP

Catalog: The category report in the ContentCreator contains the categories from the Commerce Cloud and makes them available to the editors. For this purpose, the corresponding catalog ID must be entered here.
Catalog Version: The categories provided in the ContentCreator originate from a product catalog. Therefore, in addition to the catalog ID, the version of the product catalog from which the categories are obtained must also be specified.
CDP URL: The relative URL of a category detail page must be entered in this field. As a placeholder for the category code the expression {code} can be used. The default value is c/{code}.
Override general OAuth settings: The fields for OAuth authentication enable the overwriting of the entries in the tab General. The overwriting is done by activating the checkbox Override general OAuth settings. Otherwise, the entries from the General tab will be used for authentication.

3.2. Adding the web components

For the ContentCreator, a web component is needed, which is already added to the reference project. By default it is installed globally in the ServerManager in the area Server Properties Web applications. In this case, all installation or configuration steps required for the web component have already been performed by the Crownpeak Technology GmbH.

Alternatively, you may install the web component in the Project properties. Only in this case it still needs to be installed on an active web server. Therefore, open the ServerManager and select Project properties Web components.

Figure 9. Web components in the Project properties

Within the main panel several tabs are visible, each with a list of the existing web components. This list contains the following entries for the ContentCreator:

BasicWorkflows_ContentCreator_Library (only required when using the BasicWorkflows)
CaaS Connect Web App
FirstSpirit Connect for SAP Commerce Cloud Web App

In the tab, select a web server via the selection box 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.

3.3. Definition of the external preview URL

By using the Omnichannel Manager, the ContentCreator displays external content from the Commerce Cloud to which the Omnichannel Manager needs access. The preview URL of the Storefront must therefore be specified in the ContentCreator properties. Since the specification is always project-specific, there is no default configuration for it within the reference project.

Open the Project properties ContentCreator area within the ServerManager and enter the URL of the Storefront in the External preview URL field.

Figure 10. External Preview URL

3.4. Workflows

Content is released and deleted by editors within the supplied reference project FirstSpirit Connect Reference Project via the BasicWorkflows. They are already added to the project and can be used as an alternative to project-specific workflows.

Installation of the BasicWorkflows module

Before using the workflows, the BasicWorkflows module must first be installed on the FirstSpirit server and the web component must be activated. The necessary steps are the same as the installation of the other modules and activation of the corresponding web component. The web component of the BasicWorkflows is also required in the ContentCreator tab.

The use of BasicWorkflows in ContentCreator also requires the selection of the provided BasicWorkflows Status Provider in the Project properties ContentCreator area within the ServerManager. This setting has already been made in the reference project FirstSpirit Connect Reference Project.

Figure 11. Element Status Provider

Templates

The BasicWorkflows need different templates. These usually have to be imported into the FirstSpirit project via the context menu. However, they are already included in the reference project and an import of the templates is therefore not necessary.

Permission assignment

In the final step, the release workflow must be allowed in each store to run on FirstSpirit elements. To do this, you can open the permission assignment on the root nodes of the stores via the context menu entry Extras Change Permissions. This step has already been performed in the reference project and is therefore omitted.

The rights set on the stores' root nodes to execute the workflows refer to the Everyone group. If this is not desired, the rights must be adjusted manually.

More information about the installation, configuration and functionality of the workflows can be found in the BasicWorkflows Documentation.

3.5. TranslationStudio

Translation of editorial content is often done in cooperation with external translation agencies or with the help of translation services. The integration therefore supports TranslationStudio, which allows the export of content to be translated into a target system and to reimport translations into the FirstSpirit project. By default, the TranslationStudio module is installed within the cloud environment of the Crownpeak Technology GmbH, so its functionalities can be activated on demand by performing a few steps.

In addition to the module installation, the use of TranslationStudio requires the installation of the TranslationStudio application as well as the web and project component. Furthermore, various actions within the FirstSpirit project are needed. Both the application setup and all further steps to be performed are described in the TranslationStudio Installation Manual.

The installation of the project component replaces the button of the translation function provided by FirstSpirit in the ContentCreator. This button only has functionality if all other configuration steps have been completed successfully.

3.6. Project settings

The installation on the Commerce Cloud side includes the integration of the library fs-spartacus-bridge. In addition to various CaaS information, this library expects a definition of the Commerce Cloud templates, whose processing is to be enabled in the ContentCreator.

For each Shop Driven Page specified in the bridge configuration, a page must exist within FirstSpirit and within the Commerce Cloud. The mapping between the FirstSpirit page template and the Commerce Cloud template is done via the project settings form.

For each Commerce Cloud template, the project settings contain an input component in which the corresponding page template is referenced. Furthermore, a content folder is selected for content, product, and category pages. These folders define the destination where the pages created based on the page templates are stored. The site store contains folders with the same names in which the corresponding page references are stored.

All reference names of the input components contained in the project settings use the following scheme:

ps_template_<Name of the Commerce Cloud Template> or
ps_folder_<Commerce Cloud Page Type>

When extending the project settings, this schema must be adopted for the reference names of new input components.

Figure 12. Project settings - Mapping for product pages

3.7. Adding the project languages

Within the overall system created with the FirstSpirit Connect integration, the Storefront still 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.

In order for languages to be usable in a FirstSpirit project, the corresponding language templates must exist on the FirstSpirit server. If these are missing, it is not possible to add the project languages. In this case, please contact the Technical Support.

To add the project languages, open the ServerManager and select Project properties Languages. The main panel shows a list of all languages already available in the project. Right-clicking in this main panel opens a context menu that allows the addition, editing and deletion of project languages. Select the desired language in the selection list that opens by clicking on the New menu item and confirm the selection with OK. The language is then visible in the list in the main panel. Repeat the process for all languages that should be available in the project.

Detailed information about the configuration of project languages is available in the Online documentation for FirstSpirit.

3.8. Deployment schedules

With CaaS Connect the publication of editorial content as well as updating the Online CaaS takes place with each release. An additional deployment process is not necessary in this case.

However, during the progress of the project, situations may arise that require a deployment. Therefore, the CaaS Connect module provides two schedules that are automatically added to the project. They do not require any project-specific customization.

4. Reference project

The FirstSpirit Connect module provides different ways to access shop content from Spartacus and use it in FirstSpirit. This requires different components both within the FirstSpirit project and on the Spartacus side. These components and the dependencies between them are described in the following subchapters using the reference project provided.

4.1. Pages

In contrast to the delivery of content, its creation and maintenance shifts from the Commerce Cloud to FirstSpirit. Therefore FirstSpirit provides the ContentCreator. In it, Shop and FirstSpirit Driven Pages can be displayed and enriched with editorial content using the Omnichannel Manager.

Editorial content in FirstSpirit is always created and edited on the basis of a page reference. It and the page on which it is based are automatically generated in the background in the provided reference project as soon as a new page is created in the ContentCreator. The script page_type_mapping determines the corresponding FirstSpirit page template which must be included in the project.

The reference project provides the following page templates for content, product, and category pages that correspond to the Shop Driven Pages:

cartpagetemplate
contentpage1
landingpage2
searchresultslistpage
storefinderpage
product_detail_page
category_page

The page templates for the Shop Driven Pages map the respective Commerce Cloud page templates and differ only in the number of their content areas. Each of these content areas allows the integration of different sections, which are used to create and persist the editorial content. The mapping between the Commerce Cloud templates and the FirstSpirit page templates for the Shop Driven Pages is done in the project settings as described in the installation chapter. Since FirstSpirit Driven Pages have no associated page in the Commerce Cloud, no mapping is required for them.

For the Shop as well as for the FirstSpirit Driven Pages it must be ensured that the content areas of the FirstSpirit templates match the slots configured in the bridge: 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.

In addition, all page templates must have the input components pt_seoUrl and pt_cc_identifier. The language-dependent text input component pt_seoUrl enables the definition of an SEO url and must therefore be editable. In contrast, the language-independent text input component pt_cc_identifier is a hidden component. It is filled automatically and ensures the accessibility of the page in the ContentCreator.

The following code snippet shows the definition of the two input components:

Input components pt_seoUrl und pt_cc_identifier

<CMS_INPUT_TEXT name="pt_seoUrl" hFill="yes" useLanguages="yes">
  <LANGINFOS>
    <LANGINFO lang="*" label="SEO URL"/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

<CMS_INPUT_TEXT name="pt_cc_identifier" hFill="yes" hidden="yes" useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label="Commerce Cloud Identifier"/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

4.2. Sections

Within the reference project FirstSpirit Connect Reference Project included in the delivery, the content areas of a FirstSpirit page template represent the slots of a Commerce Cloud page. Sections can be added to them; each one corresponds to a content module.

For this purpose, the reference project provides the following section templates:

Teaser (teaser)
Carousel (carousel)
Multi Slot Container (multi_slot_container)
Location Overview (location_overview)

Teaser

The teaser corresponds to a single image in horizontal format, which is by default included in the header of a page. On this image another image and a text can be placed.

In addition to the selection of the image and the two overlay options, the section template allows the specification of a link and an alt text. All link types available in the reference project are permitted for linking the image.

Carousel

The carousel is equivalent to the teaser. In contrast to the latter, it embeds several images which, depending on the configuration, rotate continuously or can be clicked through individually.

The individual images of the carousel each correspond to a teaser. For these, the carousel therefore has the same functions. Furthermore, the section template enables the de-/activation of the automatic image scrolling and the definition of the image display duration in seconds.

Multi Slot Container

The Multi Slot Container is a layout component that in addition to entering a headline allows the automatic arrangement of content, category or product elements. The arrangement of the elements depends on their number: Up to a number of four elements, they are displayed side by side and scaled accordingly. Additional elements are combined in groups of also up to four elements and displayed in further lines below.

The templates these elements are stored in the reference project under the reference names msc_content_item, msc_category_item and msc_product_item. All three of them allow entering a headline, a subtitle, and a teaser text as well as selecting an image for which an alternative text can be specified. Furthermore, the display of each element contains a button whose caption can be defined freely and which refers to the detailed view of the respective element. This button is only visible if the Multi Slot Container contains just a single element.

In addition to the input options mentioned above the content element allows the definition of a link. For this, also in this case, all link types available in the reference project are permitted.

Along with the mentioned input components the category element contains a component for selecting a category. If no image is selected for a category the category element displays a default image.

In contrast to the category element the information for the product element comes from the Commerce Cloud by default. They serve as a fallback and are overwritten by the content in the mentioned components.

Location Overview

This section template allows the input of a user-defined headline and the selection of any number of locations, each of which contains various address data. Each of these locations corresponds to a dataset stored in the datasource locations. The selected datasets are displayed as two-lined adresses in the form of an overview below the specified headline.

Each of these section templates available in the reference project includes the input component st_languageFallbackEnabled and its related rule. The input component corresponds to a checkbox which, when checked, causes the usage of the fallback language configured in the bridge. In this case, the content of the section is replaced by the content of the fallback language. Further information is available in the chapter on using the fallback language.

The usage of a fallback language requires its definition in the bridge configuration.

4.3. Links

The editorial contents maintained in FirstSpirit can contain the following references, which link them with other contents. They are based on various link templates that are already included in the reference project.

Category and product links: The FirstSpirit Connect module provides a report for products and categories in the ContentCreator. They serve to display the category and product information coming from Spartacus, which can be used for links to category or product detail pages.

Therefore, the reference project contains the link templates category_link and product_link, which correspond to a category or product link. They enable category or product detail pages to be referenced and are equivalent to each other.
Search link: The reference project contains the link template search_link. It enables the linking of a search result page to a defined search term.
Content link: The reference project provides the link template content_link. It allows the linking of pages that are maintained within the reference project.

The front-end processing of the links is done using the SemanticPathService. It generates the required URLs based on the CaaS data passed to it.

5. Use cases

Within the progress of a project, different situations can arise that require certain steps to be taken. The following subchapters describe situations that can typically occur in integration projects, and describe the necessary steps for resolving them by using the reference project supplied as a reference.

5.1. Development of a new content module

Within the overall system created with the FirstSpirit Connect integration, the Spartacus Storefront delivers the editorial content. However, the creation and maintenance of this content shifts from the Commerce Cloud to FirstSpirit. For this reason, the provided reference project FirstSpirit Connect Reference Project contains the following section templates:

teaser
carousel
multi_slot_container
location_overview

Each of these section templates requires an Angular UI component on the Spartacus side. The UI components receive the contents to be displayed and define their output in the shop.

In addition to the creation of a further section template in the FirstSpirit project, the development of a new content module therefore always includes the implementation of an associated Angular UI component in the frontend. In detail, the following steps are required, which will be explained in more detail in the course of the chapter:

Creation of a section template including maintenance of contents
Import and configuration of the DataVisualizer
Creation of a converter
Implementation of the Angular UI component
Extension of the Storefront

Creation of a section template

The development of a new content module first requires the creation of a new section template within the SiteArchitect. The template must then be integrated into a page and filled with content in all available languages. By saving these contents, they are automatically transferred to the Preview CaaS and are thus available in the preview.

In the steps below, the reference name of the new section template has to be specified at various positions. These positions are all marked by the placeholder <SECTION_REF_NAME>. The placeholder must be replaced by the reference name in all cases.

The same applies to an input component contained in the section, which is named st_input_component in the following steps.

Import and configuration of the DataVisualizer

The fs-spartacus-view-components library contains, among other things, the DataVisualizer, which enables an unprocessed output of the JSON structure stored in the CaaS in the ContentCreator. Therefore the DataVisualizer requires an import into the main module of the Spartacus application (app.module.ts) as well as the configuration as a display component for the previously created section template. In addition, the import of the ConfigModule is necessary to provide all features.

Import of the ConfigModul

import { ConfigModule } from '@spartacus/core';

The following code snippet shows the necessary adjustments in the main module. The placeholder <SECTION_REF_NAME> must be replaced by the reference name of the section template created in the first step.

Import and configuration of the DataVisualizer

import { ConfigModule } from '@spartacus/core';
import { DataVisualizerComponent } from 'fs-spartacus-view-components';

[...]

@NgModule({
   imports: [
      ConfigModule.withConfig({
         cmsComponents: {<SECTION_REF_NAME>: {component: DataVisualizerComponent}}
      })
   ]
})
export class AppModule { }

After the integration of the DataVisualizer, the page containing the new section shows its associated CaaS information in the preview of the ContentCreator. With the button COPY TO CLIPBOARD the displayed data can also be copied to the clipboard. They are required for the subsequent creation of the converter.

The parameters uid and typeCode contained in the displayed data are assumed by the Storefront. They must therefore be included in the return value of the converter to be created subsequently.

Figure 13. Data Visualizer

Example
In the case of a section, for example, which only contains a CMS_INPUT_TEXT input component for a headline (st_headline), the output of the DataVisualizer corresponds to the following code snippet:

Output of the DataVisualizer

{  "uid": "headline",
   "typeCode": "headline",
   "otherProperties": {
      "formData": {
         "st_headline": {
            "fsType": "CMS_INPUT_TEXT",
            "name": "st_headline",
            "value": "Only this week: 20% discount"
         }
      },
      "previewId": "b547b345-6077-4574-97b1-308ebcc2e58d.en_GB"
   }
}

Creation of a converter

The data stored in the CaaS for the new section is very complex and also contains information that is not needed for the output in the shop. For this reason, it is recommended to add an additional transformation step before transferring the data to the Angular UI component. The transformation of the information into a format that is optimal for the component is performed by a converter. This must contain the following code and is to be be saved under the name <SECTION_REF_NAME>.component.converter.ts at any position in the Spartacus project. Thereby the placeholder <SECTION_REF_NAME> corresponds to the reference name of the previously created section template.

Converter

import { Injectable, InjectionToken } from '@angular/core';
import { Converter, CmsComponent } from '@spartacus/core';

@Injectable({ providedIn: 'root' }) (1)
export class NewSectionComponentConverter implements Converter<CmsComponent, CmsComponent> { (2)
   public convert(source: CmsComponent): CmsComponent { (3)
      return {
         uid: source.uid,
         typeCode: source.typeCode,
         previewId: source.otherProperties.previewId,
         value: source.otherProperties.formData.st_input_component.value (4)
      } as CmsComponent;
   }
}

export const NewSectionConverterToken = new InjectionToken<Converter<CmsComponent,CmsComponent>>('NewSectionConverter'); (5)

1	The Injectable annotation creates a new Angular service. This allows the later injection of the new converter into the bridge.
2	The new class `NewSectionComponentConverter` implements the converter interface provided by Spartacus, which expects the method `convert`. Each time the section for which the converter is registered is processed, this method is called automatically.
3	Using the `source` parameter, the `convert` method gets all the information available for the section from the CaaS. The return value of the method allows the filtering of this data and defines which parameters are transferred to the Angular UI component. The parameters `uid` and `typeCode` are assumed by the Storefront and are therefore mandatory.
4	The structure of the associated values is derived from the CaaS document and must be adjusted accordingly, especially for the form data to be passed. The displayed line refers to a simple `CMS_INPUT_TEXT` input component.
5	The `NewSectionConverterToken` created here enables the later registration of the `NewSectionComponentConverter` in the main module of the Spartacus application (`app.module.ts`).

Implementation of the Angular UI component

The data format defined with the help of the converter enables the implementation of the Angular UI component, which must be saved under the name <SECTION_REF_NAME>.component.ts at any position in the Spartacus project.

The following code snippet shows an example of the content of the component:

Angular UI component

import { CmsComponent } from '@spartacus/core';
import { CmsComponentData } from '@spartacus/storefront';
import { Component } from '@angular/core';

@Component({ (1)
   template: (2)
      `<ng-container *ngIf="(componentData?.data$) | async as convertedData">
         <h1 [attr.data-preview-id]="convertedData.previewId">{{convertedData.value}}</h1> (3)
      </ng-container>`,
})

export class NewSectionComponent { (4)
   constructor(public componentData: CmsComponentData<CmsComponent>) { }
}

1	The new Angular UI component is created using the Component annotation. The annotation enables the later injection of the component into the bridge.
2	The `template` property defines the HTML output of the transferred data within the shop, which has to be adapted to the component to be created on a project-specific basis. The output is done via a container element (`ng-container`), which is only displayed in the case of existing data. If data exists, it is transferred asynchronously to the content module using the variable `convertedData`.
3	In this example, the component only outputs a headline. Therefore it uses the `value` parameter defined in the converter, which contains the corresponding form data of the initially created section. It also includes the attribute `data-preview-id`, which contains the `previewId` passed by the converter as a value and allows editing of the headline in the ContentCreator.
4	At this point, the new Angular UI component is created. It receives the data returned by the converter as constructor parameters.

Extension of the Storefront

The output of the section created in the first step assumes the integration of the implemented Angular UI component and the registration of the new converter in the Storefront. This requires the following extension of the main module of the Spartacus application (app.module.ts):

Extension of the main module

import { NewSectionComponent } from './<SECTION_REF_NAME>.component';
import { NewSectionConverterToken, NewSectionComponentConverter } from './<SECTION_REF_NAME>.component.converter';
import { FsComponentConverter } from 'fs-spartacus-common';

@NgModule({
   declarations: [NewSectionComponent], (1)
   imports: [
      ConfigModule.withConfig({
         cmsComponents: {<SECTION_REF_NAME>: { component: NewSectionComponent }} (2)
      })
   ],
   providers: [
      {  provide: NewSectionConverterToken, (3)
         useClass: NewSectionComponentConverter,
         multi: true
      },
      {  provide: FsComponentConverter, (4)
         useValue: {
            <SECTION_REF_NAME>: NewSectionConverterToken
         },
         multi: true (5)
      }
   ],
   entryComponents: [NewSectionComponent] (6)
})
export class AppModule { }

1	Within the main module a declaration of the new component is first made to include it in the Spartacus project.
2	The imports' attribute links the section template created in the first step to the component, instructing Spartacus to always use this link when processing the section. The placeholder `<SECTION_REF_NAME> must be replaced with the reference name of the new section template.
3	The converter is registered in two steps using the `providers` attribute: The first `provide` entry declares the converter as an Angular service in the Storefront. It causes the Storefront to automatically create an instance of the converter at runtime each time the `NewSectionConverterToken` is used. For a registration of further converters belonging to other sections, this entry has to be duplicated and adjusted accordingly.
4	The second `provide` entry introduces the converter to the bridge by using the `useValue` parameter to create a link between the newly created section and the token of the converter. The bridge therefore accesses the token each time the section is processed, which in turn triggers the creation of a new instance of the converter. Also in this case, the placeholder `<SECTION_REF_NAME>` must be replaced by the reference name of the new section template. The values of the `useValue` parameter are unlimited in their number and correspond to a key/value pair in each case. If further converters belonging to other sections should be introduced to the bridge, the corresponding key/value pairs can be added separated by commas: Example: `useValue: { headline: HeadlineConverterToken, carousel: CarouselConverterToken }`
5	In both cases, the `multi` parameter prevents previous declarations from being overwritten at runtime.
6	The entry `entryComponents` informs the Offline Template Compiler (OTC) of Angular that the component can be generated at runtime.

5.2. Dataset usage

On the Spartacus side, the output of the content maintained in FirstSpirit is done via Angular UI components. These receive the content to be displayed and define the HTML view in the shop.

The content maintenance is based on section templates, which can include datasets in addition to pure content. The use of datasets requires an FS_INDEX input component, which in turn references the associated data source.

The provided reference project FirstSpirit Connect Reference Project contains the section template location_overview as an example. This allows the input of a headline and the selection of any number of dataset, each of which is an address. For this purpose it has the FS_INDEX input component st_locations, which in turn references the data source locations.

FS_INDEX input component

<FS_INDEX name="st_locations" height="1" useLanguages="no">
   <LANGINFOS>
      <LANGINFO lang="*" label="Locations"/>
      <LANGINFO lang="DE" label="Standorte"/>
   </LANGINFOS>
   <SOURCE name="DatasetDataAccessPlugin">
      <TEMPLATE uid="locations.locations"/>
   </SOURCE>
</FS_INDEX>

In the CaaS, the selected datasets are stored only as a reference at the section. Therefore, when querying the data, the bridge automatically checks all documents for such references and determines the datasets by their ID. The converter associated with the section takes the data on the Spartacus side and converts it to a format that is optimal for the Angular UI component. Each of these components is associated with a FirstSpirit section template and defines the HTML output of the transferred data within the shop.

For the location_overview section template, the integration provides the location-overview component. It displays the datasets selected in the FirstSpirit project in the form of an overview below the specified headline.

5.3. Creation of a FirstSpirit Driven Page

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

In contrast to the Shop Driven Pages, the 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. In both cases, the styling of the FirstSpirit Driven Pages is done in Angular, for example, in the styles.scss file of the Storefront.

To create a new FirstSpirit Driven Page, some steps have to be performed on the SAP and Spartacus side as well as in FirstSpirit. These steps are described below.

Configuration in SAP and Spartacus

In turn, the bridge expects a definition of the pages, whose processing is to be enabled in the ContentCreator. For FirstSpirit Driven Pages, the configuration must consider whether the page uses the layout of a Shop Driven Page or its own layout.

In the first case, a dummy page must exist in the Commerce Cloud, which is empty except for the desired layout. This means, for example, that it only includes 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.

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. For this reason the layoutConfig configuration must be extended accordingly.

Configuration in FirstSpirit

In contrast to the delivery of content, its creation and maintenance is done in the FirstSpirit ContentCreator. In it, Shop and FirstSpirit Driven Pages can be displayed and enriched with editorial content using the Omnichannel Manager.

The creation and editing of editorial content requires a page template in FirstSpirit, which must be created if necessary. It must be ensured that the content areas match the slots configured in the bridge: 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.

In addition, all page templates must have the text input components pt_seoUrl and pt_cc_identifier. The input component pt_seoUrl enables the definition of an SEO url and the input component pt_cc_identifier ensures the accessibility of the page in the ContentCreator.

5.4. Selection of a product or a category

The module provides a product and a category report in ContentCreator. These reports present the products and categories originating from Commerce Cloud. The lists can be filtered via the search field in the report.

The CMS WebServices interface of the Commerce Cloud does not allow a search in another language. A search for categories or products in the corresponding reports must therefore use search terms in the default language of Commerce Cloud.

5.5. Editing page attributes

The maintenance of specific page attributes, such as a SEO URL, requires a corresponding FirstSpirit page template for all page types. This has a form consisting of various input components that are used to store the attributes and are editable in the ContentCreator via the edit dialog of the currently displayed page. The editing dialog can be called up via the Open page settings entry in the page information display area, which opens when the cursor hovers over the page status.

Figure 14. Editing page attributes

5.6. Translation of editorial content

FirstSpirit consistently pursues the concept of multiple languages and allows the output of different language variants. Translation of editorial content into these languages is often done in cooperation with external translation agencies or with the help of translation services. The integration therefore supports TranslationStudio, which allows the export of content to be translated into a target system and to reimport translations into the FirstSpirit project.

If TranslationStudio is configured in the project, the ContentCreator provides various workflows. These are executable via the Actions menu and are used to perform the following tasks:

Translation of the current page or specific sections on this page
Translation of all pages within a specific folder
Translation of multiple pages
Translation of the datasets of a data source

Each of these workflows opens a dialog where different settings for the translation have to be defined. These differ depending on the elements to be translated and are described in detail in the TranslationStudio Editor Manual. A click on the Request Translation button triggers the export of the content to be translated into the predefined target system. Once the translation is complete, a preselected workflow automatically imports the content into the FirstSpirit project and embeds it in the correct places.

Alternatively, an EasyEdit button is provided for translating single pages or sections. The button also first displays the configuration dialog and then opens the so-called TranslationHelper dialog. This displays both the source text and its translation side by side and enables immediate editing if required.

5.7. Use of the fallback language

As described in the previous chapter, 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 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.

In a multilingual project, however, in some cases content may not be available for all languages. For these cases, the FirstSpirit Connect integration optionally allows the definition of a fallback language for non-translated content. Content can thus be presented quickly and easily without being fully translated. Furthermore, the fallback language enables overriding of already existing content.

In order to use the fallback language, first its definition in the bridge configuration is required. Furthermore, the section template used must contain the st_languageFallbackEnabled input component described below and its related rule. The input component corresponds to a checkbox with which the use of fallback language can be controlled. By activating it in a section’s form, its content and the content of all of its subordinate sections are replaced by the content of the fallback language. As a result, in the case of nested sections, the input component is available only in the outermost section. In the subordinate sections it is hidden by the rule.

The following code snippet shows the input component st_languageFallbackEnabled. Its activation enables the usage of fallback language for the corresponding section.

Input component st_languageFallbackEnabled

<CMS_INPUT_TOGGLE name="st_languageFallbackEnabled" hFill="yes" preset="copy" singleLine="no" useLanguages="yes">
   <LANGINFOS>
      <LANGINFO lang="*" label="Enable language fallback"/>
      <LANGINFO lang="DE" label="Ersetzung für nicht gepflegte Sprache einschalten"/>
   </LANGINFOS>
</CMS_INPUT_TOGGLE>

The rule displayed in the following code snippet controls the visibility of the st_languageFallbackEnabled input component. Since in the case of nested sections it can be used only in the outer section, the rule hides it in subordinate sections.

Corresponding rule

<RULE>
   <WITH>
      <NOT>
         <EQUAL>
            <PROPERTYname="CONTAINERTYPE"source="#global"/>
            <TEXT>FS_CATALOG</TEXT>
         </EQUAL>
      </NOT>
   </WITH>
   <DO>
      <PROPERTY name="VISIBLE" source="st_languageFallbackEnabled"/>
   </DO>
</RULE>

5.8. Page deletion

Within the progress of a project, some pages are only required for a certain time. After that, they are no longer needed and can be removed from the project. For this purpose the reference project provides the delete workflow of the BasicWorkflows.

This workflow allows the removal of pages as well as media from the FirstSpirit project. The deletion can be performed either directly or based on the principle of dual control. After deleting the corresponding element, the workflow releases the parent structure. The changes are thus directly transferred to the Preview and the Online CaaS.

The execution of the delete workflow requires both delete and release rights. If the executing person is missing one of these rights, the workflow is not available.

5.9. Server-side rendering

Search engines control the relevance of individual websites by means of a ranking. This is an indicator of a page’s usability and accessibility and depends on various factors. Among others, these factors include the loading time and transmission time. In the context of search engine optimization (SEO), it can therefore be beneficial to generate the page on the server before delivery. This minimizes the load for the client, speeds up the initial page loading and enables optimization of the caching strategy.

The pre-generation of a page requires the activation of server-side rendering (SSR) on the server. In the case of a Spartacus project, several steps have to be performed for this, which SAP has summarized in a guide. In addition, SAP has defined various SSR coding guidelines, which have to be considered for the operation of a server in SSR mode.

In the FirstSpirit context, it is important to note that the TPP-SNAP API provided by the ContentCreator is not usable in SSR mode. This leads to the fact that, when it is activated, each page request in the preview triggers a pre-generation of the entire web presence on the server. To avoid this, it is recommended to exclude the preview and thus the ContentCreator from the SSR mode.

The exclusion of the ContentCreator is possible by checking the referer header: If the header contains a ContentCreator URL, the requested page is to be generated on the client side. Otherwise, pre-generation takes place on the server.

Checking the referer header requires an adjustment to the server.ts file, which is shown in the following code snippet:

Adjustment to the server.ts file

// All regular routes use the Universal engine
server.get('*', (req, res) => {
   // return CSR when opened on a preview URL
   if(req.header('referer')?.includes('<CONTENT_CREATOR_BASE_URL>')) {
      res.sendFile(distFolder + '/index.html');
   } else {
      res.render(indexHtml, {
         req,
         providers: [{ provide: APP_BASE_HREF, useValue: req.baseUrl }],
      });
   }
});

6. Legal notices

FirstSpirit Connect is a product of Crownpeak Technology GmbH, Dortmund, Germany.
Only a license agreed upon with Crownpeak Technology GmbH is valid for using the module.

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

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

Documentation

for version 24.12.1
Updated: 06.12.2024

Company

Contact

Crownpeak Technology GmbH
Stockholmer Allee 24
44269 Dortmund, DE
+49 231 477 77 0
Contact us