FirstSpirit is used for creating versatile and project-specific content. Thanks to the FirstSpirit Connect for SAP Commerce Cloud module, it is now possible to transfer this content to the SAP Commerce Cloud e-commerce shop system and use it there.
In the remainder of this document, the abbreviated form Commerce Cloud will be used instead of SAP Commerce Cloud. This abbreviated form refers to SAP Commerce Cloud in all cases. Furthermore, the entire document is geared towards connecting to the B2B Accelerator storefront. Mention of the storefront refers to the B2B Accelerator storefront in all cases. |
The module combines the functional strengths of both systems, delivering the key advantages that each offers and creating a highly effective overall system made up of two areas that work in parallel and are largely decoupled from one another:
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 assumed that the reader is confident in the use of FirstSpirit and Commerce Cloud, CaaS and Omnichannel Manager. |
FirstSpirit Connect allows editors to:
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.
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:
The individual components always interact in accordance with the following schema:
Omnichannel Manager JavaScript
, which enables the content in ContentCreator to be edited and highlighted.
CMS WebServices
interface of the Commerce Cloud.
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.
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.
To use the FirstSpirit Connect module, the following technical requirements must be met:
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: |
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.
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. |
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 →
area in the hybris administration console
.
The integration of the content maintained in FirstSpirit into the store requires a connection of the Commerce Cloud to the CaaS. For this, the following information is required after the installation of the add-on for both the productive environment as well as the preview:
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
Further information on using CaaS is provided in the Content as a Service Manual. |
powertoolsContentCatalog
).
fscontentconnect.dev
is optionally definable.
It controls the inclusion of the fs-tpp-api
JavaScript library and is exclusively usable in the configuration file of the add-on.
If the value true
is specified, the cloud-sap-acc-dev
tag is used when loading the fs-tpp-api
library.
If the parameter is missing or set to false
, the cloud-sap-acc
tag is used.
Which versions are behind these two tags can be seen at any time on https://www.npmjs.com/package/fs-tpp-api → Versions.
The |
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.
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.
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>
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.
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/>
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>
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. |
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/>
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:
Hybris Admin Console
under →
)
→ →
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 |
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 |
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 |
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 provide the functions of the FirstSpirit Connect module, the Content as a Service and Omnichannel Manager modules must also be installed on the FirstSpirit server.
The delivery only includes the FirstSpirit Connect module. The Content as a Service and Omnichannel Manager modules can be obtained from Technical Support. |
To install the modules, open the ServerManager
and select →
.
The main panel contains a list of all the modules installed on the FirstSpirit server.
After clicking contentconnect-sap-module-<Versionnumber>.fsm
, caas-<Versionnumber>.fsm
, and fs-tpp-api-<Versionnumber>.fsm
in that order and confirm each selection by clicking .
Following successful installation, the folders FirstSpirit Connect for SAP Commerce Cloud
, Content as a Service
, and FirstSpirit ThirdPartyPreview
are added to the list; each of these folders must be given All permissions
.
The Content as a Service module contains a service used to define a standard configuration. The steps required to do this are described in the Content as a Service Manual. |
After any module installation or update, the FirstSpirit server needs to be restarted. |
Included in the delivery is the FirstSpirit Connect Reference Project, which must be installed on the FirstSpirit server.
To do this, open the import dialog in the ServerManager
via the menu item →
and click the button to select the referenceproject-<VERSIONNUMBER>.tar.gz
file from your local data system.
Then assign a project name and description and confirm the import with .
After successful installation, the project is added to the list in the main panel.
In addition to the standard groups |
A project-specific configuration is required in order to use the FirstSpirit Connect module. It is set up using the project component, which is already added to the reference project supplied.
To perform configuration, open the ServerManager
and select →
.
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 .
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. |
The following fields are used to configure authentication and are available in each tab.
To overwrite the settings defined on the |
The user specified here must belong to the following user groups in the Commerce Cloud:
|
password
or client credentials
.
Override general OAuth settings
option is checked on the other tabs, these settings are also tested.
{code}
can be used as a placeholder for the product code.
The default value is p/{code}
.
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}
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.
{code}
can be used as a placeholder for the category code.
The default value is c/{code}
.
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.