FirstSpirit Connect

For SAP Commerce Cloud

e-Spirit AG

2021-07-08

Table of Contents

1. Introduction
2. Commerce Cloud - Installation and configuration
3. FirstSpirit - Installation and configuration
4. Use cases
5. Legal notices
6. Help

1. Introduction

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

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

Furthermore, the entire document is geared towards connecting to the B2B Accelerator storefront. Mention of the storefront refers to the B2B Accelerator storefront in all cases.

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

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

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

This document is aimed both at SAP developers and at FirstSpirit developers, who should be able to perform integration using this document as a guide.

It is not intended as a handbook for FirstSpirit editors.

It is assumed that the reader is confident in the use of FirstSpirit and Commerce Cloud, CaaS and Omnichannel Manager.

1.1. Range of functions

FirstSpirit Connect allows editors to:

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

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

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

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

1.2. Architecture

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

These components are:

The modules installed on the FirstSpirit server:
- FirstSpirit Connect
- Omnichannel Manager
- Content as a Service
Commerce Cloud-Instanz

Figure 1. Architecture

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

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

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

1.3. Technical requirements

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

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

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

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

2. Commerce Cloud - Installation and configuration

FirstSpirit is used to create and maintain editorial data, which is then transferred to and persisted by CaaS. To integrate the data into the shop, Commerce Cloud requires access to CaaS. This access is provided by an add-on included in the delivery package which must be installed and configured on the Commerce Cloud side. The delivery also includes storefront modifications that already incorporate the add-on.

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

2.1. Add-on

The CaaS content is queried by the Commerce Cloud using an add-on. This add-on is included in the delivery in the form of a fscontentconnect-<Versionsnumber>.zip file requiring installation and configuration in Commerce Cloud. The FirstSpiritPreviewFilter included in the add-on must also be activated in Commerce Cloud.

The following chapters describe how to execute the required steps.

The Commerce Cloud server must be stopped before the steps described below are carried out. Otherwise this can lead to malfunctions.

2.1.1. Installing the add-on

The zip file that must first be unzipped in order to install the add-on contains the directory fscontentconnect, which must be copied to the $HYBRISHOME/hybris/bin/custom directory on the Commerce Cloud server. The add-on must also be introduced to the Commerce Cloud server. This is achieved by entering the add-on in the localextensions.xml file in the $HYBRISHOME/hybris/config directory.

Entering the add-on in the localextensions.xml file.

<hybrisconfig>
   <extensions>
      [...]
      <extension name='fscontentconnect' />
   </extensions>
</hybrisconfig>

In the next installation step, the add-on must be built. This can be achieved using the following command sequence, which must be executed in the $HYBRISHOME/hybris/bin/platform directory of the previously stopped Commerce Cloud server.

// 1.
. ./setantenv.sh

// 2.
ant addoninstall -Daddonnames="fscontentconnect"
-DaddonStorefront.yb2bacceleratorstorefront="yb2bacceleratorstorefront"

// 3.
ant clean all

The first command sets environment variables, the second command adds the add-on to the Commerce Cloud, and the final command triggers the compilation.

To complete the installation of the add-on, the last step is to update the Commerce Cloud server. The update can be executed via the Platform → Update area in the hybris administration console.

2.1.2. Configuring the add-on

The integration of the content maintained in FirstSpirit into the store requires a connection of the Commerce Cloud to the CaaS. For this, the following information is required after the installation of the add-on for both the productive environment as well as the preview:

CaaS API Key
CaaS Database
CaaS Host
CaaS Port
CaaS Scheme
Content Catalog ID

They are to be specified either for each site used or in the project.properties file in the fscontentconnect directory of the add-on. In contrast to the specifications at the respective site, the parameters in the configuration file always refer to all sites. Therefore they serve as fallback parameters.

The following code block shows an example for the content of the project.properties file:

Example configuration.

caas-online.apikey=abcdefghijklmn1234567890
caas-online.database=MyProject
caas-online.host=caas.mydomain.com
caas-online.port=80
caas-online.scheme=http

caas-staged.apikey=abcdefghijklmn1234567890
caas-staged.database=MyProject
caas-staged.host=caas-preview.mydomain.com
caas-staged.port=80
caas-staged.scheme=http

content-catalog-id=powertoolsContentCatalog

fscontentconnect.dev=true

apikey: A valid API key is required to access the data stored in CaaS. This key requires read permissions for the project in question. It can be generated in the CaaS Admin Interface and must be entered in this line.
database: The value of this parameter corresponds to the name of the project stored in CaaS. It can be determined via the CaaS Admin Interface.
host: This parameter requires the host name to be entered under which CaaS can be reached.
port: This parameter requires the port to be entered under which CaaS can be reached.
scheme: This parameter indicates whether communication with CaaS is to take place via http or https.

Further information on using CaaS is provided in the Content as a Service Manual.

content-catalog-id: The value of this parameter corresponds to the ID of the content catalog used (for example, powertoolsContentCatalog).
fscontentconnect.dev: In addition to the other parameters, the configuration parameter fscontentconnect.dev is optionally definable. It controls the inclusion of the fs-tpp-api JavaScript library and is exclusively usable in the configuration file of the add-on. If the value true is specified, the cloud-sap-acc-dev tag is used when loading the fs-tpp-api library. If the parameter is missing or set to false, the cloud-sap-acc tag is used. Which versions are behind these two tags can be seen at any time on https://www.npmjs.com/package/fs-tpp-api → Versions.

The cloud-sap-acc-dev tag is upgraded by e-Spirit on every DEV/QA patchday to the latest compatible version of the fs-tpp-api library. The cloud-sap-acc tag on every PROD patchday.

2.1.3. Connection of multiple sites

The FirstSpirit Connect module allows editors to create Commerce Cloud content using FirstSpirit and to integrate it into the shop. This requires the Commerce Cloud to be connected to the CaaS. The parameters needed for the connection are definable either in the configuration file of the previously installed add-on or for each site. The FirstSpirit Connect module thus allows multiple sites to be connected to FirstSpirit.

The configuration of the sites is done in the Commerce Cloud backoffice. Under the item Administration each site has the fields visible in the following figure.

Figure 2. configuration parameters of a site

The information defined in the fields always refers to the corresponding site only. If no entry exists for a field, the parameter specified in the configuration file of the add-on represents a fallback value. Since the data stored in the configuration file applies to all sites, mixed operation can be implemented in this way. For example, it is possible to store the API Key, the protocol as well as the URL and the port of the CaaS centrally in the configuration file, while the name of the database to be used is specified separately for each site. The site-specific parameters always overwrite the data persisted in the configuration file.

2.1.4. Activating the FirstSpiritPreviewFilter

The previously installed and configured add-on FSContentConnect contains the FirstSpiritPreviewFilter. This filter sets the session variables that are required for the integration to work. It requires activation in Commerce Cloud and must be added to the PlatformFilterChain for this purpose.

The delivery includes a B2B accelerator storefront, which contains a spring-filter-config.xml file with the firstSpiritPreviewFilter bean already added to the FilterChainList.

Activating the FirstSpiritPreviewFilter.

<alias
 name="defaultStorefrontTenantDefaultFilterChainList"
 alias="storefrontTenantDefaultFilterChainList" />
<util:list id="defaultStorefrontTenantDefaultFilterChainList">

   [...]
   <!-- filter to handle requests from FirstSpirit -->
   <ref bean="firstSpiritPreviewFilter"/>

</util:list>

2.1.5. JSP tags

The add-on FSContentConnect, which is included in the delivery and was previously installed and configured, provides the following JSP tags:

caas:includeOcmScripts
caas:request
caas:whenFirstSpiritPreview

These tags are used to query the CaaS content and can be used in the required Commerce Cloud page templates.

caas:includeOcmScripts

Omnichannel Manager requires various JavaScript files; in the preview, the tag creates the script tags required for the integration of these files. It determines the preview using the session attributes, which are set by the FirstSpiritPreviewFilter contained within the add-on. It is only necessary to integrate the tag for this purpose.

Integration - JSP tag caas:includeOcmScripts.

<caas:includeOcmScripts/>

caas:request

The tag enables data to be requested from CaaS. In order to do this, the element to be determined and the collection containing the element must be specified. This information can be assigned to the tag using the attributes itemId and collection. The result of the query is stored in a variable, the name of which is defined via the var variable. Once the indicated CaaS item has been successfully queried, the variable is stored in the page scope.

Example - caas:request JSP tag.

<caas:request itemId="homepage" collection="contentpages" var="homepageItem" />

<!-- Display the revision of the current content -->
${homepageItem['fs_revision_id']}

If no content exists in CaaS for a defined request, this can be dealt with using standard JSP techniques:

Specification of fallback content.

<c:choose>
   <c:when test = "${homepageItem != null}">
      <!-- do this if we have a response -->
      <%-- ${homepageItem['slots']['section1']} --%>
   </c:when>
   <c:otherwise>
      <!-- do this when nothing else is true, i.e. output the fallback content. -->
   </c:otherwise>
</c:choose>

caas:whenFirstSpiritPreview

The tag enables code to be executed exclusively in the FirstSpirit preview. For this purpose, it evaluates a session attribute set by the FirstSpiritPreviewFilter. This is contained within the previously installed add-on.

Example - JSP tag whenFirstSpiritPreview.

<caas:whenFirstSpiritPreview>
   <script type="text/javascript">
      const PAGE_PREVIEW_DATA = {
         pageType: '${cmsPage.typeCode}',
         pagePreviewId: '${pagePreviewId}',
         pageId: '${cmsPage.uid}',
         pageTemplate: '${cmsPage.masterTemplate.uid}'
      };
   </script>
</caas:whenFirstSpiritPreview>

Further information on the use of CaaS and the Omnichannel Manager is provided in the Content as a Service Manual and in the Omnichannel Manager Manual.

2.1.6. Integrating Omnichannel Manager into the storefront

In FirstSpirit, the editorial content is created and edited in the ContentCreator. With the help of the Omnichannel Manager, the staged storefront of the Commerce Cloud is embedded in it. The Staged Storefront in turn accesses the Preview CaaS and determines the current FirstSpirit contents from it.

To enable the content from the storefront to be edited in ContentCreator, the Omnichannel Manager JavaScript must be integrated into Commerce Cloud. For this purpose, the Taglib and the tag caas:includeOcmScripts must be integrated into the javaScript.tag file. The delivery includes storefront modifications with Omnichannel Manager already integrated, which renders this step unnecessary.

Integration of the Taglib and the tag caas:includeOcmScripts.

<%@ taglib prefix="caas" tagdir="/WEB-INF/tags/addons/fscontentconnect/responsive/caas"%>

<caas:includeOcmScripts/>

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

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

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

The validity scope of the OAuth client used for the Preview must be set to previewwebservices.

2.3. FlexibleSearch Restrictions

The product report in ContentCreator shows all of the products in a product catalog. It therefore requires access to all of the detail pages for all displayed products. If search restrictions exist that prevent the product detail pages for specific products in a product catalog from being called up, these restrictions must be expanded with the condition described below. Within the condition, the placeholder must be replaced with the ID of the product catalog.

Additional condition within the filter query of a search restriction for products.

-- existing conditions such as approval status check
OR
   ({{ SELECT {PK} FROM {CatalogVersion} WHERE {Catalog} IN
      ({{ SELECT {PK} FROM {Catalog as c} WHERE {c.id} = '<Catalog Id of product catalog>'}})
      AND {version} = 'Staged' AND {PK} IN (?session.catalogversions)
   }}) IS NOT NULL

This additional condition prevents the relevant search restriction from being used in the context of the Staged version of the product catalog.

Search restrictions are configured in the back office under System → Personalization. For example, in the B2B accelerator, the search restriction Frontend_ProductApprovalStatus must be modified as described.

Search restrictions, that affect content pages, also need to be extended. Again, the placeholder within the condition needs to be replaced with the ID of the content catalog.

Additional condition within the filter query of a search restriction for pages.

-- existing conditions such as approval status check
OR
   ({{ SELECT {PK} FROM {CatalogVersion} WHERE {Catalog} IN
      ({{ SELECT {PK} FROM {Catalog as c} WHERE {c.id} = '<Catalog Id of content catalog>'}})
      AND {version} = 'Staged' AND {PK} IN (?session.catalogversions)
   }}) IS NOT NULL

For example, in the B2B accelerator, the search restriction Frontend_PageApprovalStatus must be modified as described.

3. FirstSpirit - Installation and configuration

Various components must be installed and configured in FirstSpirit in order to use the functions of the FirstSpirit Connect module. The following sub-chapters describe the steps required to do this.

3.1. Installing the modules

To provide the functions of the FirstSpirit Connect module, the Content as a Service and Omnichannel Manager modules must also be installed on the FirstSpirit server.

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

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

Figure 3. Server properties - Module installation

The main panel contains a list of all the modules installed on the FirstSpirit server. After clicking Install, select contentconnect-sap-module-<Versionnumber>.fsm, caas-<Versionnumber>.fsm, and fs-tpp-api-<Versionnumber>.fsm in that order and confirm each selection by clicking Open. Following successful installation, the folders FirstSpirit Connect for SAP Commerce Cloud, Content as a Service, and FirstSpirit ThirdPartyPreview are added to the list; each of these folders must be given All permissions.

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

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

3.2. Project import

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

Figure 4. Imported project in the ServerManager

In addition to the standard groups Everyone and Administrators, the reference project includes four further user groups: Editors, ChiefEditors, Developers, and ProjectAdmins. These groups possess different rights, which are selected depending on their roles and defined for different Stores. Users who are not included in these groups are not authorized to use the reference project by default.

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

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

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

To use the FirstSpirit Connect module, the Content as a Service and the Omnichannel Manager modules must also be configured. The steps required to do this are described in the Content as a Service Manual and in the Omnichannel Manager Manual.

Figure 6. Project component - General

URI: The indicated URI is the server URI to the Commerce Cloud instance.
Connection timeout (sec): This parameter defines the time that elapses (in seconds) before the process of establishing a connection for communication with Commerce Cloud times out.
Connection retries: This parameter defines the number of attempts the system will make to establish a connection for communication with Commerce Cloud.

The following fields are used to configure authentication and are available in each tab. To overwrite the settings defined on the General tab, the other tabs provide an option to Override general OAuth settings.

Auth Server URI: This parameter defines the standard end point for OAuth authentication (relative to the URI of the Commerce Cloud instance).
Username: This field is used to enter the standard user for OAuth authentication.

The user specified here must belong to the following user groups in the Commerce Cloud:

previewmanagergroup to generate a preview ticket
basecmsmanagergroup to load product and category information in the reports
cmsmanagergroup to create and update pages in the Commerce Cloud

Password: This field is used to enter the password associated with the user provided in the previous field.
OAuth Client ID: This field is used to indicate the standard client ID used for OAuth authentication. It has an impact on the rights of the users.
OAuth Client Secret: A secret is used for OAuth authentication; this secret must match the indicated client ID.
OAuth Grant Type: OAuth authentication requires a standard grant type. This can either be set to password or client credentials.
Test OAuth Settings: This button is used to test the established connection based on the authentication settings entered. If the Override general OAuth settings option is checked on the other tabs, these settings are also tested.

Figure 7. Project component - Product DAP

Collection: This field is used to define the end point for product data queries.

PDP URL

The URL of a product detail page must be entered in this field. Both absolute and relative URLs are permitted. {code} can be used as a placeholder for the product code. 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 contained in this tab 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.

Figure 8. Project component - Category DAP

Katalog Id: The catalog defined here is used as the source of the categories for the category DAP.
Katalog Version: For configuration purposes, this field is used to specify the version of the product catalog from which the categories for the category DAP were taken.

CDP URL: The URL of a category detail page must be entered in this field. Both absolute and relative URLs are permitted. {code} can be used as a placeholder for the category code. The default value is c/{code}.
Override general OAuth settings: The fields for OAuth authentication contained in this tab 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.