FirstSpirit Connect: For SAP Commerce Cloud

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.
This also applies to the short form "FirstSpirit Connect", which within this documentation always refers to the FirstSpirit Connect for SAP Commerce Cloud integration.

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 2024.5
Java 17
SAP Commerce Cloud 18.08 to 20.11

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 shop 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
fscontentconnect.storefrontContextRoot=yb2bacceleratorstorefront

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 the corresponding npm page in the tab Versions.

The cloud-sap-acc-dev tag is upgraded by Crownpeak Technology GmbH 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.

fscontentconnect.storefrontContextRoot: The FirstSpiritPreviewFilter of the add-on reads the variable storefrontContextRoot of the Commerce Cloud by default and stores its value for further use in the session. Among other things, it is used to generate the preview URLs of content pages. If the value of the storefrontContextRoot variable and the value actually used by the shop differ from each other, because the latter is stored in a different variable, for example, you can configure the add-on to use a different value using this parameter. If this parameter is set, the add-on uses this value as storefrontContextRoot. If the parameter is empty or not present, the add-on reads the storefrontContextRoot variable of the Commerce Cloud as before.

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.

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.

In addition to the standard groups Everyone, Administrators and Developers, there are three further external user groups in the reference project: Editors, ChiefEditors and ProjectAdmins. The groups have different rights, which are selected according to their tasks and defined for the different stores. Users outside these groups are not allowed to use the reference project by default.

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

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

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

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

Figure 4. 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 5. 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 6. 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.

Figure 7. 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.
Preview Servlet: This field contains the name of the Commerce Cloud preview servlet endpoint. When connecting to version 20.11 of the Commerce Cloud, the value cx-preview must be entered. For older versions of the Commerce Cloud, the default value previewServlet must be retained.
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.

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

To maintain existing Commerce Cloud pages in FirstSpirit, a FirstSpirit template must be assigned to each Commerce Cloud template. For this purpose, a mapping between the Commerce Cloud Template Item IDs and the corresponding FirstSpirit Page Template UIDs must be defined at this point.

Since the content pages based on the templates can have different URLs, the Commerce Cloud URL Pattern column enables the creation of a specific preview URL in each case. The URL can be entered either relative to the storefront or the host (see example below). Furthermore, it is also possible to use the placeholder pageUid. If the column remains empty, the URL defined in the Contentpage URL field is used instead for the preview of the corresponding page.

Example
The configuration visible in the figure would have the following meaning:

Table 1. Commerce Cloud URL Pattern - Example
FirstSpirit template	Entry	resulting URL	Explanation
content_page	/magazin/outdoor	http(s)://<host>/magazin/outdoor	If the entry starts with a slash, only the server URL is extended.
content_page_1	---	http(s)://<host>/<storefront-context-root>/preview-content?uid={pageUid}	Since no specific URL is defined in this case, the general `Contentpage URL` is used instead.
content_page_2	assortment/{pageUid}	http(s)://<host>/<storefront-context-root>/assortment/{pageUid}	This entry has no leading slash. It therefore represents a URL relative to the storefront. Furthermore, it contains the placeholder `pageUid`.
content_page_3	indoor	http(s)://<host>/<storefront-context-root>/indoor	This entry also does not contain a leading slash and therefore also leads to an extension of the storefront URL.

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.

The following FirstSpirit input components are supported for entering the FirstSpirit content page attributes: CMS_INPUT_TEXT, CMS_INPUT_TOGGLE, CMS_INPUT_RADIOBUTTON, CMS_INPUT_CHECKBOX, CMS_INPUT_COMBOBOX, CMS_INPUT_LIST, CMS_INPUT_DATE, CMS_INPUT_NUMBER, CMS_INPUT_TEXTAREA.

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: Content pages can have specific URLs that are optionally specified during the definition of the Template Mapping which have to be configured beforehand. If a content page does not have a specific URL, the general Contentpage URL entered in this field is used instead for displaying the content page in the preview. Both absolute and relative URLs as well as the use of the placeholder {pageUid} are permitted in this field. The default value is preview-content?uid={pageUid}.
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.

3.2. Adding web components

The ContentCreator requires a web component that has already been added to the reference project supplied. 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. To do this, open the ServerManager and select Project properties Web components.

Figure 9. Web components in the project properties

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:

BasicWorkflows_ContentCreator_Library (only required when using the BasicWorkflows)
CXT ContentCreator Extension Extension: WebApp for ContentCreator (only required when using the reference project)
FirstSpirit Connect for SAP Commerce Cloud Web App
FirstSpirit ThirdPartyPreview WebApp

Select an Active web server on the tab page via the selection box of the same name and start the installation by clicking the Install button. After successful installation, a dialog opens, in which the activation of the Web server must be confirmed.

Detailed information on how to configure web components is available in 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 storefront of the Commerce Cloud to which the Omnichannel Manager needs access. The preview URL of the storefront must therefore be specified in the ContentCreator properties. This must be extended by the parameter firstSpiritPreview=1, which is required for initializing the preview. Since the specification of the URL is always project-specific, there is no default configuration for it within the reference project.

Example: https://sap-storefront.e-spirit.com?site=e-spirit&firstSpiritPreview=1

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. 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 FirstSpirit Connect Reference Project.

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

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

Within the supplied FirstSpirit Connect 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 component. By default, these steps are already performed.

In addition, to use BasicWorkflows in the ContentCreator, the provided BasicWorkflows Status Providers must be selected in the Project properties ContentCreator area within the ServerManagers. This setting has already been applied in the FirstSpirit Connect Reference Project.

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 Extras Change 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.6. 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.

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

It is also possible to simply carry out an approval and a direct publication in the online content catalogue. In this case, the synchronization of the data must be ensured on a project-specific basis.

The supplied reference project contains a schedule that incorporates the following 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.7.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.7.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.

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

Direct publication in the online content catalogue

The described deployment schedule updates both the Staged and the Online Content Catalog. Therefore it triggers an approval and synchronization of the affected content pages. Alternatively, it is also possible to trigger only an approval and a direct publication into the online content catalog. In this case, automatic synchronization is not necessary.

The following steps are required to implement direct publication:

In the first step the sync definition must be removed within the schedule action Content Page Approval & Sync Definition. For this purpose, the update logic must be adapted as shown in the code snippet.

Due to the direct publication and the adaptation of the update logic, the automatic synchronization of both content catalogs will be omitted. For this reason, it must be ensured on a project-specific basis that the contents of both catalogs remain identical. Otherwise, divergences are unavoidable.

Update logic for the approval 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()) {
         context.logWarning("Approving content page " + cmsContentPage.getUid() + " failed!");
      }
   }
};

context.setProperty("sapcc_additional_contentpage_update", contentPageAdditionalUpdate);

An identical, second schedule is created by a subsequent duplication of the existing schedule. Without any further configuration, both schedules would write into the Content Catalog that is selected as the Content Catalog Version in the Content tab of the project component. In the reference project, this is the Staged Content Catalog.

In order for the second schedule to write into the online content catalog, the parameter catalogVersion must be added to the properties of the schedule action SAPCC - Bulk Update and configured with the value Online. If the value is missing or the configuration is incorrect, the bulk update terminates and an exception occurs. Otherwise, the log contains the information about which content catalog is used for deployment.

Figure 15. Parameter catalogVersion

If, as described in this section, writing to the Online Content Catalog is done by a separate schedule, the CaaS generation must be adjusted in the schedule that writes to the Staged Content Catalog. This must fill the Preview CaaS equivalent to writing to the Staged Content Catalog. Information on the necessary adaptation of the CaaS generation is contained in the Initialize CaaSGeneration section of the Content as a Service Manual.

4. Use cases

The FirstSpirit Connect 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 FirstSpirit Connect Reference Project.

4.1. Maintenance of existing Commerce Cloud content pages

The FirstSpirit Connect 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 FirstSpirit Connect 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.

When a content page is created, the ID of the associated Commerce Cloud page is stored in its form. This ID is required to display the page in the preview. The page template therefore contains the hidden input component pt_cc_identifier. If additional page templates are added to the project, their form must also contain this input component.

Input component pt_cc_identifier

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

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

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.

Figure 16. override content button

add content

If the fallback is applied and the Dom element does not contain any content, the button is displayed with the add content label while hovering. This situation can arise when there is no content on an empty page for the area in Commerce Cloud, or if no content has been defined for the Dom element. Within the landingLayout2Page.jsp page, which is included in the delivery, this option is used for the output of the main_body content area:

Example - Fallback for output of main_body content area

<c:choose>
   <c:when test="${not empty caasItem and not empty caasItem['slots']['main_body']}">
      [... show Content ...]
   </c:when>
   <c:otherwise>
      <div data-slot-name="main_body" data-fs-content-editing></div>
   </c:otherwise>
</c:choose>

Figure 17. add content button

4.2. Maintaining content on new Commerce Cloud content pages

The maintenance of content on new Commerce Cloud content pages is subject to the same requirements as the maintenance of existing Commerce Cloud content pages.

However, the creation of new pages must be configured in the project component. Once this configuration is complete, the familiar ContentCreator functions can be used to create new pages.

The label attribute of new Commerce Cloud content pages is set by the FirstSpirit Connect module and by default starts with a slash (/).

4.3. Dynamic content

The FirstSpirit Connect module allows the maintenance of dynamic content. This content is code that is defined in the presentation channel of the FirstSpirit template and stored in the generated CaaS item. This content is evaluated when the content area is output in the Commerce Cloud page template.

Modifications in FirstSpirit

In the supplied reference project, the dynamic content is integrated via the link template a_product_price_link. This can be used in text-image sections and uses the template language Apache Velocity to integrate the name and price of a product. To do so, it accesses the context objects productOptions and productFacade, which provides the add-on in the storefront during the evaluation process:

The productOptions context object is a list of all values of the ProductOption enum.
The productFacade context object is a reference to the ProductFacade.

The following code extract shows the presentation channel of the link template a_product_price_link in the reference project:

Presentation channel for the link template

$CMS_SET(productCode,lt_productRef.values.iterator.next.getValueMap().get("code"))$
$CMS_SET(void,dynamicContent.put("active",true))$
<span data-dynamic-content="true">
   #set( $product = $productFacade.getProductForCodeAndOptions("$CMS_VALUE(productCode)$", $productOptions))
   #if( $product )
      <a href="$CMS_RENDER(template:"product_link_render", prodRef:lt_productRef)$">
         $product.getName()
         #set( $priceData = $product.getPrice())
         #if ( $priceData )
            ($priceData.getFormattedValue())
         #end
      </a>
   #end
</span>

Within the template, the first action is to determine the product code of the referenced product and to transfer it to the getProductForCodeAndOptions method together with the productOptions context object. This step ensures that all product information is available within the product variable. The dynamicContent variable is needed to determine the product information to be used in the generation of the CaaS item. This variable is evaluated in the FirstSpirit page template and the active parameter must be set to true.

Unlike static content, dynamic content is pulled from the staged storefront for display in ContentCreator, so it must be identifiable. For this purpose, this content must be enclosed in a Dom element with the attribute data-dynamic-content set to true. Furthermore, the page template must also indicate the pageRevisionId. This ID is used to ensure that the revision of the CaaS item always corresponds to the pages displayed in ContentCreator and allows the content to be updated if necessary. The dynamic content must be queried from the staged storefront as the initial evaluation of this content takes place in this location. If the content were to be determined directly from FirstSpirit, like static content, ContentCreator would only show the code defined for it in the presentation channel.

Modifications in Commerce Cloud

The code for dynamic content is evaluated in the Commerce Cloud page template. This evaluation is executed during access to the relevant content area within the result object of the caas:request tag; the process returns a string. The output is therefore the same as that for static content and is defined as such.

The following code extract shows a shortened form of the definition of the output for the content area stage_body on the landingLayout2Page.jsp page, which is included in the delivery:

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>
      [...]
   </c:otherwise>
</c:choose>

4.4. Maintaining content on product detail pages

To maintain content on product detail pages, in addition to the relevant storefront expansions, the modifications to the presentation channel of the templates - as described in chapter Maintenance of existing Commerce Cloud content pages - must also have been implemented.

Once these requirements are met, product detail pages can be maintained in the same way as content pages.

Product detail and content pages must be stored in different structure and content folders in FirstSpirit and in different collections in CaaS.

4.5. Deleting content pages managed in FirstSpirit

When maintaining content on CCommerce Cloud content pages, FirstSpirit is the leading system used to manage and delete pages. The FirstSpirit executable CMSItemRemoval can be used to delete these pages from Commerce Cloud. This executable can be called up by entering an itemUid parameter that contains the UID of the page reference to be deleted. Alternatively, the executable can be used within a workflow. In such cases, ensure that a trigger_finish_full transition exists, as the executable will move on to this transition once deletion has been completed successfully. This allows the deletion of pages from Commerce Cloud to be integrated into a deletion workflow. The following code extract shows the call-up of the executable within a script.

Call-up of the CMSItemRemoval executable

#!executable-class
com.espirit.moddev.contentconnect.sap.module.catalogs.cmsitem.CMSItemRemoval

After deleting a page, the editor is redirected to the start page.

4.6. Product referencing

Product referencing requires modifications to the form and presentation channel of a template.

4.6.1. Form

To reference products in a template, this template must first include the appropriate form. The form requires an FS_INDEX component to store the product ID as a minimum.

Form

<CMS_MODULE>
   <FS_INDEX name="st_products">
      <LANGINFOS>
         <LANGINFO lang="*" label="Products"/>
      </LANGINFOS>
      <SOURCE name="ContentConnectSAPCommerceCloud/ContentConnectSAPCommerceCloud_ProductDataAccessPlugin"/>
   </FS_INDEX>
</CMS_MODULE>

4.6.2. Presentation channel

The presentation channel permits access to the FS_INDEX component and the referenced products it contains. Each element of the FS_INDEX component provides methods for querying information on the relevant product and, for example, to output this information.

Use of a product in the presentation channel

$CMS_FOR(for_product, st_products.values())$
   $CMS_VALUE(for_product.getValueMap().get("name_de"))$
$CMS_END_FOR$

Table 2. Methods
Name	Parameter	Return value	Description
get	name: String	String	Returns the value of the stated attribute or `null` if the attribute does not exist.
getValueMap		Map<String, String>	Returns a map of all attributes of the product.

The description of the ProductWsDTOs in the Cmswebservices API provides an overview of the available attributes and their identifiers.

Some attributes, such as name, contain language-dependent values. For this reason, their identifier must be expanded for the purposes of the query: name_de.

The code extract Use of the product code within a product link template shows an example of how the product code can be used to link a product. It uses various input components from the project settings, which are defined as follows:

Table 3. Input components in the project settings
Name	Value (example)	Description
ps_hybrisAcceleratorName	yb2bacceleratorstorefront	Name of the Commerce Cloud storefront
ps_hybrisSiteName	powertools	Name of the Commerce Cloud site

Use of the product code within a product link template

$CMS_IF(!lt_ref.isEmpty && !lt_ref.values.isEmpty)$
   $CMS_VALUE(ps_hybrisAcceleratorName.replace("/", ""))$/$CMS_VALUE(ps_hybrisSiteName.replace("/", ""))$/$CMS_VALUE(#global.language.abbreviation.toLowerCase())$/p/$CMS_VALUE(lt_ref.values.iterator.next.getValueMap().get("code"))$
$CMS_END_IF$

4.7. Category referencing

Category referencing requires modifications to the form and presentation channel of a template.

4.7.1. Form

To reference categories in a template, this template must first include the appropriate form. The form requires an FS_INDEX component to store the category ID as a minimum.

Form

<CMS_MODULE>
   <FS_INDEX name="st_categories" useLanguages="no">
      <LANGINFOS>
         <LANGINFO lang="*" label="Categories"/>
      </LANGINFOS>
      <SOURCE name="ContentConnectSAPCommerceCloud/ContentConnectSAPCommerceCloud_CategoryDataAccessPlugin"/>
   </FS_INDEX>
</CMS_MODULE>

4.7.2. Presentation channel

The presentation channel permits access to the FS_INDEX component and the referenced categories it contains. Each element of the FS_INDEX component is an object of type com.espirit.moddev.contentconnect.sap.module.catalogs.productcatalogs.Category, which is described in the JavaDoc of the API included in delivery.

The following code extract shows an example use of a category in the presentation channel:

Use of a category in the presentation channel

$CMS_FOR(for_category, st_categories.values())$
   $CMS_VALUE(for_category.getName(#global.language))$
$CMS_END_FOR$

The FirstSpirit Connect module allows the navigation structure to be generated in FirstSpirit. The generation process produces a JSON document in CaaS.

To use this function, a navigation function that generates the JSON document is required. The following code extract shows an example of this kind of function, taking into account all of the elements in the structure folder contentpages.

Navigation function

<CMS_HEADER>
   <CMS_FUNCTION name="Navigation" resultname="nav">
      <CMS_PARAM name="root" value="pagefolder:contentpages" />
      <CMS_PARAM name="expansionVisibility" value="all"/>
      <CMS_PARAM name="siteMap" value="0" />
      <CMS_ARRAY_PARAM name="beginHTML">
         <CMS_ARRAY_ELEMENT index="0..4">{</CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
      <CMS_ARRAY_PARAM name="delimiter">
         <CMS_ARRAY_ELEMENT index="0..4">,</CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
      <CMS_ARRAY_PARAM name="selectedDelimiter">
         <CMS_ARRAY_ELEMENT index="0..4">,</CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
      <CMS_ARRAY_PARAM name="innerBeginHTML">
         <CMS_ARRAY_ELEMENT index="0..3">,"children":[</CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
      <CMS_ARRAY_PARAM name="unselectedHTML">
         <CMS_ARRAY_ELEMENT index="0..4">
            "label":"$CMS_VALUE(#nav.label)$",
            "id":"$CMS_VALUE(#nav.id)$",
            "pageRef":"$CMS_VALUE(#nav.ref.getUid())$"
         </CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
      <CMS_ARRAY_PARAM name="selectedHTML">
         <CMS_ARRAY_ELEMENT index="0..4">
            "label":"$CMS_VALUE(#nav.label)$",
            "id":"$CMS_VALUE(#nav.id)$",
            "pageRef":"$CMS_VALUE(#nav.ref.getUid())$"
         </CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
      <CMS_ARRAY_PARAM name="innerEndHTML">
         <CMS_ARRAY_ELEMENT index="0..3">]</CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
      <CMS_ARRAY_PARAM name="endHTML">
         <CMS_ARRAY_ELEMENT index="0..4">}</CMS_ARRAY_ELEMENT>
      </CMS_ARRAY_PARAM>
   </CMS_FUNCTION>
</CMS_HEADER>{"navigation":[$CMS_IF(!nav.isEmpty)$$CMS_VALUE(nav)$$CMS_END_IF$]}

The execution of this function requires a page and a page reference based on this page, which must also be created.

The page reference must contain the reference name main_navigation.

The navigation function shown only incorporates the start page of a menu level. If you wish to incorporate all page references, the function must be modified accordingly.

Each time an element is created, modified, moved, or deleted in the structure area, the FirstSpirit Connect module starts generating the page reference main_navigation. As a result, the document in CaaS always reflects the most up-to-date navigation structure in FirstSpirit. The CaaS configuration for the higher level structure folder determines which collection the document will be stored in. The name of the document saved in CaaS is main_navigation_<LANGUAGE>.

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

Figure 18. Products and categories 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.

4.10. Inclusion of a product or category

A product or category can be dragged from the report and dropped into an FS_INDEX input component in the editing dialog. Alternatively, the component has an Add button which opens a selection dialog. This dialog lists all the available products and categories.

The selection is saved using the button of the same name.

4.11. Calling up a content page or product/category detail page

Content pages as well as product and category detail pages can be accessed via the shop navigation and via the product, category or search report. In the report, these pages are called up by clicking on one of them. Thereby detail pages that are not yet available in the shops main navigation can also be called up.

To determine the URL of product and category detail pages, the reports use the URLs from the fields PDP URL and CDP URL that must be specified during the configuration of the project component.
Content pages can have specific URLs that are optionally specified during the definition of the Template Mappings. If a content page does not have a specific URL, the general Contentpage URL is used for it instead. If one of these fields contains a relative URL, this is converted into an absolute URL based on the URL of the current shop page.

The product report shows all of the products in the configured product catalog. This means that the detail pages of all products in the catalog must be accessible. To ensure that this is the case, the configuration of the FlexibleSearch Restrictions must be checked.

4.12. Editing page attributes

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, both new and existing Commerce Cloud pages can be displayed and edited.

The maintenance of specific page attributes, such as a SEO URL, requires a corresponding FirstSpirit page template for all Commerce Cloud content pages. 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 19. Editing page attributes

5. Legal notices

FirstSpirit Connect for SAP Commerce Cloud is a product of Crownpeak Technology GmbH, Dortmund, Germany.
Only a license agreed upon with Crownpeak Technology GmbH is valid with respect to the user for using the module.

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

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.

FirstSpirit Connect

For SAP Commerce Cloud