ContentConnect

For SAP Commerce Cloud

e-Spirit AG

2020-03-13
Table of Contents

1. Introduction

FirstSpirit is used for creating versatile and project-specific content. Thanks to the ContentConnect 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 ContentConnect For SAP Commerce Cloud module is the reference project ContentConnect 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

ContentConnect allows editors to:

  • Create native Commerce Cloud content using FirstSpirit
  • 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:

    • ContentConnect
    • Omnichannel Manager
    • Content as a Service
  • Commerce Cloud instance
Architecture
Figure 1. Architecture


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

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

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

1.3. Technical requirements

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

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

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

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

2.1.2. Configuring the add-on

After installation, the Commerce Cloud add-on expects the following parameters to be defined:

  • caas-online.apikey / caas-staged.apikey
  • caas-online.database / caas-staged.database
  • caas-online.host / caas-staged.host
  • caas-online.port / caas-staged.port
  • caas-online.scheme / caas-staged.scheme

These are required in order to use CaaS and must be entered in the Commerce Cloud as configuration parameters. Configuration is required for live operation as well as for using CaaS for previewing.

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

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.

2.1.3. 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 relevant configuration applied: In this file, the firstSpiritPreviewFilter bean, which is added to the FilterChainList, is configured.

Activating the FirstSpiritPreviewFilter. 

<!-- register filter bean from fscontentconnect addon-->
<bean
 id="firstSpiritPreviewFilter"
 class="com.espirit.moddev.contentconnect.sap.filters.FirstSpiritPreviewFilter" >

   <property name="sessionService" ref="sessionService"/>
   <property name="configurationService" ref="configurationService" />
   <property name="cmsPreviewService" ref="cmsPreviewService" />

</bean>

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

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

</util:list>

2.1.4. 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.5. Integrating Omnichannel Manager into the storefront

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.

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 ContentConnect 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 ConsoleImpEx Import)
  • Manually, in the back office under SystemOAuthOAuth 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 SystemPersonalization. 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 ContentConnect module. The following sub-chapters describe the steps required to do this.

3.1. Installing the modules

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

The delivery only includes the ContentConnect 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 propertiesModules.

Server properties - Module installation
Figure 2. 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 ContentConnect, 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 ContentConnect Reference Project, which must be installed on the FirstSpirit server. To do this, open the import dialog in the ServerManager via the menu item ProjectImport and click the Local button to select the ContentConnectReferenceProject.tar.gz file from your local data system. Then assign a project name and description and confirm the import with Yes. After successful installation, the project is added to the list in the main panel.

Imported project in the ServerManager
Figure 3. 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 ContentConnect 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 propertiesProject components.

Server properties - Project components
Figure 4. Server properties - Project components


A list of all existing project components is displayed in the main panel. Select the entry ContentConnect Project Configuration and open the corresponding configuration dialog via Configure

To use the ContentConnect 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.

Project component - General
Figure 5. 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.
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.
Project component - Product DAP
Figure 6. 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}.

All of the authentication settings in this tab are used if the parameter Override general OAuth settings is selected. Otherwise, the product DAP uses the settings from the General tab for authentication.

Project component - Category DAP
Figure 7. Project component - Category DAP


Catalog Id
The catalog defined here is used as the source of the categories for the category DAP.
Catalog 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}.

All of the authentication settings in this tab are used if the parameter Override general OAuth settings is selected. Otherwise, the category DAP uses the settings from the General tab for authentication.

Project component - Preview
Figure 8. Project component - Preview


Language
The language abbreviation entered in this field sets the language of the generated preview ticket.
Resource Path
This field defines the resource URL of the generated preview ticket.
Page Id
This field indicates the ID of the page of the generated preview ticket.
Catalog Versions
This field is used to enter the catalog versions of the generated preview ticket.

The previously mentioned settings on the Preview tab correspond to the parameters of a preview ticket in the Preview API of Commerce Cloud. This ticket is requested by FirstSpirit to allow a protected storefront to be previewed in ContentCreator. The delivery includes the file fs-preview-session-initializer.js, which is used as necessary by the caas:includeOcmScripts tag and triggers the generation of a preview ticket by calling up an executable. If necessary, additional parameters can be transferred during this call to overwrite the settings on the Preview tab shown here. The structure of the parameter object must match the structure of one of the Preview tickets in the Preview API.

All of the authentication settings in this tab are used if the parameter Override general OAuth settings is selected. Otherwise, the preview uses the settings from the General tab for authentication.

Project component - Contents
Figure 9. Project component - Contents


Site Id
The ID of the Commerce Cloud site (e.g. powertools) must be entered in this field.
Content Catalog Id
As with the Site Id, this field is used to enter the ID of the content catalog (e.g. powertoolsContentCatalog).
Content Catalog Version
In this field, the version of the content catalog to be used must be selected (Staged or Online).
Template Mappings
This field is used to define the mapping between the Commerce Cloud template item IDs and the FirstSpirit page template Uids.
Content Page Attribute Mapping

The data entered here corresponds to the mapping of the FirstSpirit content page attributes to the Commerce Cloud content page attributes.

Example

Example configuration of attribute mapping. 

[{
   "templateUid": "landinglayout2",
   "uidType": "TEMPLATESTORE",
   "attributeMappings": [
      { "source": "pt_title",
        "target": "title",
        "languageDependent": true
      },
      { "source": "pt_label",
        "target": "label",
        "languageDependent": false
      }
   ]
},
{
   "templateUid": "news.news_article",
   "uidType": "TEMPLATESTORE_SCHEMA",
   "attributeMappings": [
      { "source": "tt_title",
        "target": "title",
        "languageDependent": true
      },
      { "source": "tt_label",
        "target": "label",
        "languageDependent": false
      }
   ]
}]

Content Pages Sitestore Folder UID
In this field, the UID of the structure folder in which the content pages managed in FirstSpirit are stored must be entered.
Contentpage URL
The URL of a content page must be entered in this field. Both absolute and relative URLs are permitted. {pageUid} can be used as a placeholder for the UID of the content page. The default value is preview-content?uid={pageUid}.

All of the authentication settings in this tab are used if the parameter Override general OAuth settings is selected. Otherwise, the content creation uses all settings from the General tab for authentication.

3.4. Adding web components

The ContentCreator requires a web component that has already been added to the reference project supplied. Nevertheless, this component still needs to be installed on an active web server. To do this, open the ServerManager and select Project propertiesWeb components.

Inside the main panel, various tab pages are visible. Each tab page contains a list of the existing web components. This list contains the following entries for ContentCreator (see fig. Web components in the project properties):

  • ContentConnect For SAP Commerce Cloud Web App
  • FirstSpirit ThirdPartyPreview WebApp

Select a Web server on the tab page 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 must be confirmed.

To use the FirstSpirit ThirdPartyPreview WebApp web component, a configuration is required that is described in the Omnichannel Manager Manual.

Detailed information on how to add web components is available in the FirstSpirit Manual for Administrators.

Web components in the project properties
Figure 10. Web components in the project properties


3.5. Presentation channel

An additional XML channel is required in addition to the presentation channels that already exist for the project. For empty projects, this channel must be created manually; however, it is already contained within the supplied ContentConnect Reference Project.

The presentation channel was created in the ServerManager under Project propertiesTemplate sets and is configured as follows:

Presentation channel
Figure 11. Presentation channel


In the selection box of the same name, the conversion rule to be created for CaaS must be selected. The steps required to do this are described in the Content as a Service Manual.

The presentation channel is activated and is therefore available in the project. It is used to define the content to be transferred, which is summarized in messages during the generation operation and transferred to CaaS.

3.6. Release workflow

Within the supplied ContentConnect Reference Project, content is released by editors via the release workflow of the BasicWorkflows. This can be used as an alternative to project-specific workflows.

Installing the BasicWorkflows module

Before using the release workflow, you must install the BasicWorkflows module on the FirstSpirit Server and activate the web component. The steps required to do this are the same as those required for the installation of the other modules and the activation of the associated web components. The web component BasicWorkflows is also required in the ContentCreator tab.

In addition, to use BasicWorkflows in the ContentCreator, the provided BasicWorkflows Status Providers must be selected in the Project propertiesContentCreator area within the ServerManager. This setting has already been applied in the ContentConnect Reference Project.

Element status provider
Figure 12. Element status provider


Templates

The BasicWorkflows require various templates. Usually, these templates need to be imported via the context menu in the FirstSpirit project used. However, they are already contained within the reference project and importing the templates is therefore not necessary.

Permission assignment

In the final step, the release workflow must be authorized in the individual stores so that they can be executed on FirstSpirit elements. To do this, select ExtrasChange permissions from the context menu of the stores' root nodes to call up the permission assignment. This step has also already been carried out in the reference project and is therefore omitted.

The permissions for executing the workflow set on the stores' root nodes relate to the Everyone group. This can only be changed by modifying the permissions manually.

More detailed information on the installation, configuration, and functionality of the workflow can be found in the BasicWorkflows Manual.

3.7. Project settings

There is some essential project-specific information that needs to be entered for the connection between FirstSpirit and Commerce Cloud. It is entered using the project settings form and must be specified within the project being used.

Within the supplied reference project, the project settings page with the required configuration already exists. In this case, there is no need to create the template or the required components.

Changes to the project settings do not take effect straight away, as they are saved in the session of the user. They require the client to be restarted.

Project settings
Figure 13. Project settings


CONTENT PAGE | LANDINGPAGE2 TEMPLATE
For the maintenance of existing Commerce Cloud content pages in FirstSpirit each Commerce Cloud page template must be assigned to a FirstSpirit template. The FirstSpirit template selected in this field is used to maintain Commerce Cloud content pages based on the Commerce Cloud template LandingPage2Template. To support different or further Commerce Cloud templates the project settings form must be extended by similar fields. This information enables the scripts page_type_mapping and get_page_type to correctly map Commerce Cloud and FirstSpirit content pages. Therefore changes in the project settings page have to be reflected in these two scripts.
CONTENT PAGE FOLDER
Within the FirstSpirit project, all content pages are created in the same content folder, which is defined in this field. The script page_type_mapping requires the details of the folder for the maintenance of existing Commerce Cloud content pages.

3.8. Deployment schedule

By default, the release of content does not involve any update to Online CaaS or any transfer for data to the Commerce Cloud. Instead, it only involves the FirstSpirit release process, which can be mapped, for example, using the Release workflow of the BasicWorkflows. The Online CaaS update and data transfer to the Commerce Cloud only takes place when the content is deployed.

The deployment of released editorial content is executed via a CaaS schedule. This executes a CaaS generation and transfers the data to Online CaaS, which then makes it available to Commerce Cloud. The schedule can also be used to synchronize the online content catalog in Commerce Cloud.

The update of the online content catalog may involve various dependencies. For this reason, a decision as to whether the approval and synchronization processes form part of the import process or not must be made on a project-specific basis.

The supplied reference project contains a schedule that incorporates the following actions:

Generation schedule actions
Figure 14. Generation schedule actions


The actions Initialize CaaSGeneration, CaaS Generate, CaaS CleanUp, and Finalize CaaS Generation make up the CaaS schedule. The actions described in the following sub-chapters are added to the schedule. As the Bulk Update requires access to the Approval or Sync Definition, these actions are described in reverse order.

The Content as a Service Manual contains further information on the CaaS schedule.

3.8.1. SAPCC - Bulk Update

Product detail pages maintained in FirstSpirit are generally based on pages that already exist in Commerce Cloud. When these pages are edited, only the content is changed; the page creation process is separate. Their publication therefore only requires an update of the data stored in the Online CaaS. There is no need to synchronize the online content catalog in Commerce Cloud.

Unlike product detail pages, content pages can be created in FirstSpirit. For this type of page, it is not sufficient to just update Online CaaS to trigger deployment. Deployment also involves importing the content pages into Commerce Cloud. This import process must be added to the deployment schedule as the last action in the form of the script SAPCC - Bulk Update.

To update the online storefront, the bulk update accesses the approval and sync definition. These match the action described in the following chapter.

However, the update of the online content catalog may involve various dependencies. For this reason, the action is optional and a decision as to whether or not it is included in the import process must be made on a project-specific basis. If the action is not included, the bulk update script only updates the staged storefront.

SAPCC - Bulk Update. 

#! executable-class
com.espirit.moddev.contentconnect.sap.module.synchronization.CommerceCloudBulkUpdate

To create and update content pages in Commerce Cloud, the import process must know the mapping of the FirstSpirit and Commerce Cloud content pages. For this purpose, a mapping must be configured in the project component under Content.

The reference name of the structure folder in which the content pages within the FirstSpirit project are stored must be entered at the same position. The structure folder allows the import process to identify the pages to be transferred. For this reason, the folder must only contain content pages that are managed by FirstSpirit. During deployment, the import process updates or creates all pages contained in this folder in the Commerce Cloud.

3.8.2. Content Page Approval & Sync Definition

By default, Bulk Update only updates the staged content catalog in Commerce Cloud. To initiate an update of the online catalog content as well, the relevant pages must be approved and synchronized.

The update of the online content catalog may involve various dependencies. For this reason, a decision as to whether the approval and synchronization processes form part of the import process or not must be made on a project-specific basis.

In such cases, the import process permits the execution of an additional update logic, which is applied to each content page that is to updated or created. This logic can be added to the deployment schedule in the form of the Content Page Approval & Sync Definition script. As the previously described Bulk Update uses the update logic, the logic must be executed before the update.

Approval and synchronization take place via the API of the ContentConnect module. The associated manual and the JavaDoc-JAR is included in the delivery.

Content in the staged content catalog may contain references to products in the staged product catalog. To avoid inconsistencies in the online catalogs, it is a good idea to synchronize the product catalog before synchronizing the content catalog.

A standard process for synchronizing various catalogs always involves complex and project-specific requirements. For this reason, it is not possible to define this kind of process here.

The code extract below shows an example definition of the approval process for an imported content page and its synchronization with the online content catalog.

Update logic for the approval and synchronization of a content page. 

import com.espirit.moddev.contentconnect.sap.module.ServiceFactory;
import com.espirit.moddev.contentconnect.sap.module.synchronization.ContentPageAdditionalUpdate;
import com.espirit.moddev.contentconnect.sap.module.catalogs.cmsitem.CMSItemService;
import com.espirit.moddev.contentconnect.sap.module.catalogs.cmsitem.CMSItem;

contentPageAdditionalUpdate = new ContentPageAdditionalUpdate() {
   updateCMSContentPage(cmsContentPage, pageRef) {
      cmsItemService = ServiceFactory.getCMSItemService(context);

      context.logInfo("Approving content page " + cmsContentPage.getUid() + "..");

      // Approving CMSContentPage
      cmsContentPage.setApprovalStatus("APPROVED");
      updatedCMSContentPageOpt = cmsItemService.updateCMSContentPage(cmsContentPage);

      if(updatedCMSContentPageOpt.isPresent()) {
         // Synchronizing CMSContentPage to online catalog
         context.logInfo("Synchronizing content page " + cmsContentPage.getUid() + "..");
         cmsItemService.synchronizeItem(cmsContentPage, "Online");
      } else {
         context.logWarning("Approving content page " + cmsContentPage.getUid() + " failed!");
      }
   }
};

context.setProperty("sapcc_additional_contentpage_update", contentPageAdditionalUpdate);

3.8.3. Expansion of the standard process

The previously described standard process for the release and deployment of content can be modified and expanded as required on a project-specific basis. This chapter describes possible use cases and contains information on how to use them.

Preview of changes to Commerce Cloud-specific page attributes

Editorial changes to content or product detail pages are automatically transferred to Preview CaaS, which renders them available for display in the preview. However, changes to Commerce Cloud-specific page attributes of content pages are processed in a different way: These changes are not stored in CaaS, but are transferred to the staged content catalog during deployment.

If these changes need to be reflected in the preview, it must be possible to manually transfer them to the staged content catalog. To do so, the system requires a schedule which, like the deployment schedule, is comprised of a generation operation and the subsequent import process. In such cases, instead of a CaaS full generation, a CaaS partial generation must be selected. The update logic for the import process must also contain an unapproval of the content page and must not trigger synchronization.

Approval of a content page during page release
Using the release workflow, the user can execute an automatic approval of the corresponding Commerce Cloud page in the staged content catalog in parallel to the FirstSpirit release process. To achieve this, the workflow must be modified to call up the relevant deployment schedule. In order to update only the single released page, the CaaS full generation must be replaced with a CaaS partial generation. As is the case with the preview of changes to Commerce Cloud-specific page attributes, the update logic must not trigger synchronization.
Hot deployment
A hot deployment - the publication of a single page - works in the same way as a standard released page deployment. However, instead of a delta or full generation, only a partial generation of the page to be deployed should be carried out.

4. Use cases

The ContentConnect module provides various options for accessing Commerce Cloud content and for using this in FirstSpirit. These options are described below using use cases based on the supplied ContentConnect Reference Project.

4.1. Maintenance of existing Commerce Cloud content pages

The ContentConnect module enables editors to maintain content pages that already exist in Commerce Cloud in FirstSpirit. For this purpose, the content pages are displayed in ContentCreator via Omnichannel Manager, enabling them to be seamlessly integrated into the familiar FirstSpirit editorial process.

As well as integrating Omnichannel Manager, which is an installation step, the presentation channel of the page and section templates must be completed in order to maintain content pages in FirstSpirit. In addition, the relevant page template must also be modified in Commerce Cloud.

4.1.1. Page template

Generally, content pages in a FirstSpirit project are edited based on a FirstSpirit page reference. This reference and the page on which it is based must be created for content pages that already exist in Commerce Cloud. In the ContentConnect Reference Project, the creation of this page reference and the associated page takes place in the background, in a process that is invisible to the editor. The script page_type_mapping uses the page template of the Commerce Cloud page to determine the corresponding FirstSpirit page template, which is referenced in the project settings.

The following code extract shows a shortened form of the presentation channel for the page template in the reference project:

Presentation channel for the page template. 

$CMS_TRIM(level:1)$
   $CMS_SET(json, {:})$
   $CMS_SET(previewId, previewId(element:#global.node))$
   $CMS_SET(void, json.put("previewId", "" + previewId))$
   $CMS_SET(void, json.put("pageRevisionId", #global.page.revision.id))$

   $CMS_SET(slotList, {:})$

   $CMS_IF(#global.page.body("stage_body").children.toList().size > 0)$
      $CMS_SET(dynamicContent, {:})$
      $CMS_SET(content)$
         $CMS_TRIM(level:4)$$CMS_VALUE(#global.page.body("stage_body"))$$CMS_END_TRIM$
      $CMS_END_SET$
      $CMS_SET(stage_body, {:})$
      $CMS_SET(void, stage_body.put("content", content.toString))$
      $CMS_SET(void, stage_body.put("dynamic",
         if(dynamicContent.get("active") != null, dynamicContent.get("active"), false)))$
      $CMS_SET(void, slotList.put("stage_body", stage_body))$
   $CMS_END_IF$

   [...]

   $CMS_SET(void, json.put("slots", slotList))$
   $CMS_VALUE(json.toJSON)$
$CMS_END_TRIM$

The page has three content areas - the stage_body, tiles_body, and main_body - and represents a landingLayout2Page.jsp page. While the first two content areas are used to edit existing content from Commerce Cloud, the third allows further sections to be added. In the reference project, the section templates banner_section, category_teaser_section, and text_picture_section are available for this purpose. The content of these templates is added to the JSON object slots generated in the template.

For this purpose, two instructions are required for each content area to enable the system to distinguish between static and dynamic content. Dynamic content can only be incorporated into combined text-image sections, as this is the only type of section that can include dynamic product data. The section uses the link template a_product_price_link, with the value of the active parameter in the presentation channel configured as true for the dynamicContent variable.

In addition to the editorial content, the previewId and pageRevisionId of the page reference are also transferred to the JSON object created in the template: The previewId is stored in the PAGE_PREVIEW_DATA object in the template in Commerce Cloud, and is used to identify the page reference. Identification takes places via the JavaScript of Omnichannel Manager. The pageRevisionId is a technical dependency field and ensures that dynamic content is always displayed correctly in ContentCreator.

The JSON object is part of the CaaS item to be generated and can be read out within the Commerce Cloud template.

4.1.2. Section template

The slots contained within a Commerce Cloud page are represented in FirstSpirit by the sections banner_section, category_teaser_section, and text_picture_section. If a corresponding content page is to be created in the FirstSpirit project for an existing Commerce Cloud page, the relevant sections are created automatically and populated with the existing content.

The following code extract shows the presentation channel for the text-image section from the reference project:

Presentation channel for the text-image section. 

<div data-preview-id="$CMS_VALUE(previewId())$">
   [...]
   <div class="yCmsComponent" style="margin: 20px;">
      $CMS_IF(!st_headline.isEmpty())$
         <h1 style="text-align:center;">$CMS_VALUE(st_headline.convert2)$</h1>
      $CMS_END_IF$

      $CMS_IF(!st_picture.isEmpty())$
         <img
            data-preview-id="$CMS_VALUE(previewId(element:st_picture))$"
            class="js-responsive-image"
            style="margin: 20px;float:$CMS_VALUE(st_picturePosition, default:"left")$"
            $CMS_IF(!st_pictureDescription.isEmpty())$
               title="$CMS_VALUE(st_pictureDescription.convert2)$"
               alt="$CMS_VALUE(st_pictureDescription.convert2)$"
            $CMS_END_IF$
            data-media="{}"
            src="$CMS_REF(st_picture,resolution:"CATEGORY_TEASER_ITEM",abs:1)$">
      $CMS_END_IF$
      $CMS_IF(!st_text.isEmpty())$
         $CMS_VALUE(st_text)$
      $CMS_END_IF$
   </div>
   [...]
</div>

This section has various input components for entering a heading and text and adding an image with a definable position and image description. The heading, text and image are displayed within a DIV, with a data-preview-id attribute configured to the value $CMS_VALUE(previewId())$. This attribute serves to decorate and identify the section; again, this process is executed by the JavaScript of Omnichannel Manager. To enable media-specific actions, such as release or image cropping, the same attribute is also provided for the img tag.

The Omnichannel Manager Manual contains additional information on the use of the preview ID.

4.1.3. Commerce Cloud Page Template

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. This also applies to the online storefront and the Online CaaS.

This link requires modifications to the page template of the Commerce Cloud content page; these modifications are explained in this chapter. The modifications are contained in the landingLayout2Page.jsp page, which is part of the delivery, and can be reproduced in this page.

The following code extract shows the querying of a CaaS item that is saved in the variable caasItem. The first step of this process is to determine the CaaS collection in which the data is stored: The FirstSpirit content pages from the reference project are always stored in the contentpages collection, while other content is stored in the standard collection content.

Example - Querying of the CaaS item. 

<%@ taglib prefix="caas" uri="/WEB-INF/tld/addons/fscontentconnect/caas.tld" %>

<c:choose>
   <c:when test="${cmsPage.typeCode == 'ContentPage'}">
      <c:set var="caasCollection" value="contentpages"/>
   </c:when>
   <c:otherwise>
      <c:set var="caasCollection" value="content"/>
   </c:otherwise>
</c:choose>

<caas:request itemId="${cmsPage.uid}" collection="${caasCollection}" var="caasItem" />

To edit editorial content, ContentCreator displays the familiar EasyEdit buttons, which appear together with a frame while hovering. Via Omnichannel Manager, ContentCreator can display external content. However, Omnichannel Manager requires information from Commerce Cloud to highlight this content. This information is read from a data object, which is populated via the corresponding page template in Commerce Cloud.

The following code extract shows an example of how this type of data object may be populated; the page type, preview ID, and page ID are transferred to this object. The preview ID matches the ID of the previously determined CaaS item. If it was not possible to query a CaaS item, the preview ID in the data object remains empty.

Example - Population of a data object. 

[... Determine the CaaS item (see above) ...]

<c:set var="pagePreviewId" value="${not empty caasItem and not empty caasItem['previewId'] ? caasItem['previewId'] : ''}"/>

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

For product detail pages, the product code must be defined as the page ID instead of the UID:

Example - Defining the product code. 

const PAGE_PREVIEW_DATA = {
   [...]
   pageId: '${productCode}',
   [...]
};

In addition to determining the CaaS item and populating the data object, the output must also be defined. As part of this process, a check is needed whether the previously determined CaaS item includes content for the relevant content area. If this is not the case, fallback content can be defined.

The following code extract shows the definition of the output for the content area stage_body:

Example - Definition of output. 

<%@ taglib prefix="caas" uri="/WEB-INF/tld/addons/fscontentconnect/caas.tld" %>

[... Determine the CaaS item and set the PAGE_PREVIEW_DATA object (see above) ...]

<c:choose>
   <c:when test="${not empty caasItem and not empty caasItem['slots']['stage_body']}">
      <div data-slot-name="stage_body">
         ${caasItem['slots']['stage_body']}
      </div>
   </c:when>
   <c:otherwise>
      <div data-slot-name="stage_body" data-fs-content-editing>
         <cms:pageSlot position="Section1" var="feature">
            <cms:component component="${feature}"/>
         </cms:pageSlot>
      </div>
   </c:otherwise>
</c:choose>

Whether the outcome is positive or the fallback is applied, a Dom element must be defined to mark the FirstSpirit content area. This element allows external content to be visually highlighted and maintained in ContentCreator. The name of the content area must be transferred to the Dom element via the data-slot-name attribute. In the event of a fallback, the Dom element also requires the attribute data-fs-content-editing. This attribute controls the display of a plus button in ContentCreator, which shows the label override content or add content when hovering.

override content

If the fallback is applied and existing content from Commerce Cloud is displayed, the button is displayed with the override content label while hovering. This means that there is not yet any content in FirstSpirit for the content area. For this reason, the existing content can only be overwritten and not edited. The previously described code extract shows this option.