FirstSpirit Connect: For SAP Commerce Cloud

1. Einleitung

FirstSpirit dient der Erstellung vielseitiger und projektspezifischer Inhalte. Mit dem Modul FirstSpirit Connect for SAP Commerce Cloud wurde die Möglichkeit geschaffen, diese Inhalte in das E-Commerce-Shopsystem SAP Commerce Cloud zu übertragen und dort zu nutzen.

Im restlichen Dokument wird anstelle von "SAP Commerce Cloud" die Kurzform "Commerce Cloud" benutzt. Damit ist immer ausschließlich die SAP Commerce Cloud gemeint.
Dies gilt auch für die Kurzform "FirstSpirit Connect", mit der innerhalb dieser Dokumentation grundsätzlich die FirstSpirit Connect for SAP Commerce Cloud-Integration gemeint ist.

Des Weiteren ist die gesamte Dokumentation auf die Anbindung der B2B Accelerator Storefront ausgerichtet. Die Erwähnung der Storefront bezieht sich somit ausschließlich auf die B2B Accelerator Storefront.

Das Modul kombiniert die funktionalen Stärken beider Systeme, um so die besten Vorteile zu erzielen und ein erfolgreiches Gesamtsystem zu schaffen. Dieses Gesamtsystem besteht aus zwei Bereichen, die parallel und größtenteils entkoppelt voneinander arbeiten:

FirstSpirit-seitige Komponenten: Diese Komponenten dienen der Erstellung und Pflege der redaktionellen Daten. Sie werden im JSON-Format und in Form von Medien an die jeweilige Content as a Service-Instanz übermittelt und aus dieser von der Commerce Cloud abgefragt.
Commerce Cloud-seitige Komponenten: Diese Komponenten dienen der Einbindung der in FirstSpirit erstellten redaktionellen Inhalte. Die Commerce Cloud integriert diese Daten in den Shop.

Ein Bestandteil der Auslieferung des FirstSpirit Connect for SAP Commerce Cloud-Moduls ist das Referenzprojekt FirstSpirit Connect Reference Project. Die vorliegende Dokumentation orientiert sich durchgängig an dem Referenzprojekt und erläutert die mit dem Modul bereitgestellten Funktionalitäten anhand gängiger Anwendungsfälle.

Das vorliegende Dokument richtet sich sowohl an SAP- als auch an FirstSpirit-Entwickler, die mithilfe der Dokumentation die Integration durchführen können sollen.
Es ist kein Handbuch für FirstSpirit-Redakteure.

Es wird vorausgesetzt, dass der Leser sicher in der Verwendung FirstSpirits und der Commerce Cloud sowie des CaaS und des Omnichannel Managers ist.

1.1. Funktionsumfang

FirstSpirit Connect stellt Redakteuren die folgenden Möglichkeiten zur Verfügung:

Erstellung von Commerce Cloud-Inhalten mit FirstSpirit für eine oder mehrere Sites einer Commerce Cloud-Instanz
Zugriff auf Produkt- und Kategorieinformationen
gleichzeitige Darstellung von Shop-Elementen und redaktionellen Inhalten in der FirstSpirit-Vorschau
Übertragung von Inhalten in die Commerce Cloud

Die entsprechenden Funktionalitäten werden mit der Installation und Konfiguration des Moduls im ContentCreator bereitgestellt.

Die Pflege der Inhalte findet über die gewohnten FirstSpirit-Mittel statt. Mit FirstSpirit vertraute Redakteure benötigen daher keine darüber hinausgehenden Kenntnisse. Die Inhalte werden der Commerce Cloud im Rahmen eines Deployments zum Import bereitgestellt. Diese integriert die Informationen in den Shop.

Für die Commerce Cloud ergibt sich somit bei der Auslieferung redaktioneller Inhalte in den Live-Stand keinerlei Unterschied. Auch wenn der FirstSpirit-Server beispielsweise aufgrund von Wartungsarbeiten heruntergefahren wird, beeinflusst dies die Commerce Cloud nicht.

1.2. Architektur

Die Verbindung von FirstSpirit und der Commerce Cloud wird über eine Architektur aus verschiedenen Komponenten realisiert (vgl. Abbildung Architektur).

Diese Komponenten sind:

die auf dem FirstSpirit-Server installierten Module:
- FirstSpirit Connect
- Omnichannel Manager
- Content as a Service
Commerce Cloud-Instanz

Abbildung 1. Architektur

Das Zusammenspiel der einzelnen Komponenten erfolgt immer nach dem folgenden Schema:

Die Erstellung und Bearbeitung redaktioneller Inhalte findet FirstSpirit-seitig im ContentCreator statt. In diesem ist mithilfe des Omnichannel Managers die Staged Storefront der Commerce Cloud eingebettet.
Die Staged Storefront greift ihrerseits auf den Preview CaaS zu und ermittelt aus diesem die aktuellen FirstSpirit-Inhalte. Gleichzeitig bindet er das Omnichannel Manager JavaScript ein, das die Bearbeitung und das Highlighting der Inhalte im ContentCreator ermöglicht.
Die Bereitstellung von Produkt- und Kategorieinformationen erfolgt über einen Report. Dieser greift dafür über die CMS WebServices-Schnittstelle der Commerce Cloud auf deren Product Catalog zu und fragt so die notwendigen Daten ab.
Neben dem Report nutzt außerdem das Modul die CMS WebServices-Schnittstelle. Es veranlasst die automatische Synchronisation FirstSpirit-seitig erstellter bzw. veränderter Inhaltsseiten im Content Catalog der Staged Storefront. Eine automatische Synchronisation der Informationen in die Online Storefront ist stets projektspezifisch zu entwickeln und existiert daher nicht.
Die Übertragung der freigegebenen redaktionellen Inhalte in den Online CaaS erfolgt mithilfe einer Generierung. Dieser macht die Inhalte für die Online Storefront verfügbar, über den sie in den Shop integriert werden.

Die Commerce Cloud stellt somit die Hauptkomponente dieser Architektur dar. Neben der Bereitstellung sämtlicher Shop-Funktionalitäten fragt sie die in FirstSpirit erstellten bzw. gepflegten Inhalte aus dem Online CaaS ab und liefert sie an die Kunden aus. Zwischen beiden Systemen existiert lediglich eine lose Kopplung. Sie arbeiten hauptsächlich parallel zueinander. Wird der FirstSpirit-Server beispielsweise aufgrund von Wartungsarbeiten heruntergefahren, beeinflusst dies die Commerce Cloud nicht.

1.3. Technische Voraussetzungen

Für den Einsatz des FirstSpirit Connect-Moduls müssen die folgenden technischen Voraussetzungen erfüllt sein:

die Module FirstSpirit Connect und Content as a Service in der jeweils aktuellen Version
Omnichannel Manager in der Version 1.2.27 oder höher
FirstSpirit 2024.5
Java 17
SAP Commerce Cloud 18.08 bis 20.11

Bei der Verwendung des mitgelieferten Referenzprojekts FirstSpirit Connect Reference Project ist außerdem das BasicWorkflows-Modul in der jeweils aktuellen Version erforderlich.

Die Versionsnummer der Auslieferung unterscheidet sich von den Versionsnummern der einzelnen Bestandteile der Auslieferung. Sie folgt einem Schema aus zweistelliger Jahreszahl, Monatszahl und der Nummer des Releases innerhalb des jeweiligen Monats (zum Beispiel: 20.10.0 für das erste Release im Oktober 2020). Im Gegensatz dazu erhalten das Modul, das Referenzprojekt und das Add-on eigene Versionsnummern, die von der Versionsnummer der Auslieferung losgelöst sind.

2. Commerce Cloud - Installation und Konfiguration

FirstSpirit dient der Erstellung und Pflege redaktioneller Daten, die in den CaaS übertragen und von diesem persistiert werden. Um die Daten in den Shop zu integrieren, benötigt die Commerce Cloud eine Zugriffsmöglichkeit auf den CaaS. Diese wird durch ein Add-on bereitgestellt, das in der Auslieferung enthalten ist und eine Commerce Cloud-seitige Installation und Konfiguration erfordert. Die Auslieferung enthält außerdem Storefront-Anpassungen, in denen das Add-on bereits eingebunden ist.

Die nachfolgenden Kapitel beschreiben alle notwendigen Schritte für die Installation und die Konfiguration des Add-ons sowie für die erforderlichen Commerce Cloud-seitigen Erweiterungen.

2.1. Add-on

Die Abfrage der CaaS-Inhalte durch die Commerce Cloud erfolgt mithilfe eines Add-ons. Dieses ist in Form der fscontentconnect-<Versionsnummer>.zip-Datei ein Bestandteil der Auslieferung und erfordert eine Commerce Cloud-seitige Installation und Konfiguration. Des Weiteren ist der in dem Add-on enthaltene FirstSpiritPreviewFilter Commerce Cloud-seitig zu aktivieren.

Die nachfolgenden Kapitel beschreiben die Durchführung der notwendigen Schritte.

Vor der Ausführung der nachfolgenden Schritte ist der Commerce Cloud-Server zu stoppen. Andernfalls kann es zu Fehlfunktionen kommen.

2.1.1. Installation des Add-ons

Die für die Installation des Add-ons zunächst zu entpackende zip-Datei enthält das Verzeichnis fscontentconnect, das in das Verzeichnis $HYBRISHOME/hybris/bin/custom des Commerce Cloud-Servers zu kopieren ist. Anschließend ist das Add-on dem Commerce Cloud-Server bekanntzumachen. Dies erfolgt über einen Eintrag in der localextensions.xml-Datei im Verzeichnis $HYBRISHOME/hybris/config.

Eintragung des Add-ons in der localextensions.xml-Datei

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

Die Installation erfordert im nächsten Schritt das Bauen des Add-ons. Dies lässt sich über die folgende Befehlsfolge realisieren. Sie ist im Verzeichnis $HYBRISHOME/hybris/bin/platform des zuvor gestoppten Commerce Cloud-Servers auszuführen.

// 1.
. ./setantenv.sh

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

// 3.
ant clean all

Während der erste Befehl Umgebungsvariablen setzt, fügt der zweite Befehl das Add-on der Commerce Cloud hinzu, bevor der letzte Befehl die Kompilierung auslöst.

Um die Installation des Add-ons abzuschließen, ist im letzten Schritt ein Update des Commerce Cloud-Servers notwendig. Das Update ist über den Bereich Platform Update in der hybris administration console ausführbar.

2.1.2. Konfiguration des Add-ons

Die Integration der in FirstSpirit gepflegten Inhalte in den Shop setzt eine Anbindung der Commerce Cloud an den CaaS voraus. Dafür sind nach der Installation des Add-ons sowohl für den Produktivbetrieb als auch für die Vorschau die folgenden Informationen erforderlich:

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

Sie sind entweder pro verwendeter Site oder in der project.properties-Datei im Verzeichnis fscontentconnect des Add-ons anzugeben. Im Gegensatz zu den Angaben an der jeweiligen Site, beziehen sich die Parameter in der Konfigurationsdatei immer auf alle Sites. Sie dienen daher als Fallback-Parameter.

Der nachfolgende Code-Block zeigt ein Beispiel für den Inhalt der project.properties-Datei:

Konfigurationsbeispiel

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: Der Zugriff auf die im CaaS gespeicherten Daten setzt einen gültigen API Key voraus, der Leserechte auf das entsprechende Projekt benötigt. Er kann im CaaS Admin Interface generiert werden und ist an dieser Stelle anzugeben.
database: Der Wert dieses Parameters entspricht dem Namen des im CaaS gespeicherten Projekts. Dieser lässt sich über das CaaS Admin Interface ermitteln.
host: Dieser Parameter erfordert die Angabe des Hostnames, unter dem der CaaS erreichbar ist.
port: Dieser Parameter erfordert die Angabe des Ports, unter dem der CaaS erreichbar ist.
scheme: Mit diesem Parameter ist anzugeben, ob die Kommunikation mit dem CaaS via http oder https erfolgen soll.

Weitere Informationen zur Verwendung des CaaS sind in der Content as a Service-Dokumentation enthalten.

content-catalog-id: Der Wert dieses Parameters entspricht der Id des eingesetzten Content-Katalogs (z. B. powertoolsContentCatalog).
fscontentconnect.dev: Zusätzlich zu den anderen Parametern ist optional der Konfigurationsparameter fscontentconnect.dev definierbar. Er steuert die Einbindung der fs-tpp-api-JavaScript-Bibliothek und ist ausschließlich in der Konfigurationsdatei des Add-ons benutzbar. Bei Angabe des Werts true wird das Tag cloud-sap-acc-dev beim Laden der fs-tpp-api-Bibliothek verwendet. Fehlt der Parameter oder wird er auf false gesetzt, so wird das Tag cloud-sap-acc verwendet. Welche Versionen hinter diesen beiden Tags liegen, kann jederzeit auf der zugehörigen npm-Seite im Tab Versions eingesehen werden.

Das Tag cloud-sap-acc-dev wird durch Crownpeak Technology GmbH an jedem DEV/QA-Patchday auf die aktuellste kompatible Version der fs-tpp-api-Bibliothek gehoben. Das Tag cloud-sap-acc respektive an jedem PROD-Patchday.

fscontentconnect.storefrontContextRoot: Der FirstSpiritPreviewFilter des Add-ons liest standardmäßig die Variable storefrontContextRoot der Commerce Cloud aus und speichert deren Wert zur weiteren Nutzung in der Session. Er dient unter anderem zur Generierung der Vorschau-URLs von Inhaltsseiten. Weichen der Wert der Variablen storefrontContextRoot und der tatsächlich durch den Shop genutzte Wert voneinander ab, weil dieser beispielsweise in einer anderen Variablen gespeichert ist, so kann dem Add-on über diesen Parameter konfigurativ ein anderer Wert übergeben werden. Ist dieser Parameter gesetzt, so verwendet das Add-on diesen Wert als storefrontContextRoot. Ist der Parameter leer oder nicht vorhanden, so liest das Add-on wie bisher die Variable storefrontContextRoot der Commerce Cloud aus.

2.1.3. Anbindung mehrerer Sites

Das FirstSpirit Connect-Modul stellt Redakteuren die Möglichkeit zur Verfügung, Commerce Cloud-Inhalte in FirstSpirit zu pflegen und sie in den Shop zu intergrieren. Dafür ist eine Anbindung der Commerce Cloud an den CaaS notwendig. Die für die Anbindung erforderlichen Parameter sind entweder in der Konfigurationsdatei des zuvor installierten Add-ons oder pro Site definierbar. Das FirstSpirit Connect-Modul ermöglicht somit die Anbindung mehrerer Sites an FirstSpirit.

Die Konfiguration der Sites erfolgt im Commerce Cloud Backoffice. Unter dem Punkt Verwaltung besitzt jede Site die auf der folgenden Abbildung sichtbaren Felder.

Abbildung 2. Konfigurationsparameter einer Site

Die in den Feldern definierten Informationen beziehen sich immer nur auf die entsprechende Site. Existiert für ein Feld keine Eingabe, dient der in der Konfigurationsdatei des Add-ons angegebene Parameter als Fallback-Wert. Da die in der Konfigurationsdatei gespeicherten Angaben für alle Sites gelten, ist auf diesem Weg ein Mischbetrieb umsetzbar. So ist es beispielsweise möglich, den API Key, das Protokoll sowie die URL und den Port des CaaS zentral in der Konfigurationsdatei zu hinterlegen, während der Name der zu verwendenden Datenbank jeweils pro Site angegeben ist. Die Site-spezifischen Parameter überschreiben dabei grundsätzlich die in der Konfigurationsdatei persistierten Daten.

2.1.4. Aktivierung des FirstSpiritPreviewFilters

Das zuvor installierte und konfigurierte Add-on FSContentConnect enthält den FirstSpiritPreviewFilter. Dieser setzt Sessionvariablen, die für die Funktionalität der Integration notwendig sind. Er erfordert eine Commerce Cloud-seitige Aktivierung und muss dafür der PlatformFilterChain hinzugefügt werden.

Die Auslieferung enthält eine B2B Accelerator Storefront, in dessen spring-filter-config.xml-Datei die firstSpiritPreviewFilter-Bean der FilterChainList bereits hinzugefügt ist.

Aktivierung des FirstSpiritPreviewFilters

<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

Das in der Auslieferung enthaltene und zuvor installierte sowie konfigurierte Add-on FSContentConnect stellt die folgenden JSP-Tags bereit:

caas:includeOcmScripts
caas:request
caas:whenFirstSpiritPreview

Sie dienen der Abfrage der CaaS-Inhalte und können innerhalb der gewünschten Commerce Cloud Page Templates benutzt werden.

caas:includeOcmScripts

Die Verwendung des Omnichannel Managers setzt verschiedene JavaScript-Dateien voraus, für deren Einbindung das Tag im Vorschaufall die notwendigen script-Tags erzeugt. Den Vorschaufall ermittelt es dabei über Session-Attribute, die der im Add-on enthaltene FirstSpiritPreviewFilter setzt. Das Tag muss lediglich eingebunden werden.

Einbindung - JSP-Tag caas:includeOcmScripts

<caas:includeOcmScripts/>

caas:request

Das Tag ermöglicht die Abfrage von Daten aus dem CaaS. Dafür benötigt es eine Angabe des zu ermitteltenden Elements sowie der Collection, die das Element beinhaltet. Diese Informationen lassen sich dem Tag über die Attribute itemId und collection übergeben. Das Ergebnis der Anfrage wird in einer Variablen gespeichert, deren Name das Attibut var definiert. Die Variable wird nach einer erfolgreichen Abfrage des angegebenen CaaS-Items im Page-Scope hinterlegt.

Beispiel - JSP-Tag caas:request

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

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

Der Fall, dass für eine definierte Abfrage keine Inhalte im CaaS existieren, lässt sich mit den bekannten JSP-Mitteln abfangen:

Angabe eines Fallback-Contents

<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

Das Tag ermöglicht die Ausführung von Code ausschließlich in der FirstSpirit-Vorschau. Dafür wertet es ein Session-Attribut aus, das der FirstSpiritPreviewFilter setzt. Dieser ist im zuvor installierten Add-on enthalten.

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

Weitere Informationen zur Verwendung des CaaS bzw. des Omnichannel Managers sind in der Content as a Service-Dokumentation bzw. in der Dokumentation des Omnichannel Managers enthalten.

2.1.6. Einbindung des Omnichannel Managers in der Storefront

Die Erstellung und Bearbeitung redaktioneller Inhalte findet FirstSpirit-seitig im ContentCreator statt. In diesem ist mithilfe des Omnichannel Managers die Staged Storefront der Commerce Cloud eingebettet. Die Staged Storefront greift ihrerseits auf den Preview CaaS zu und ermittelt aus diesem die aktuellen FirstSpirit-Inhalte.

Um die Bearbeitung der Inhalte aus der Storefront im ContentCreator zu ermöglichen, ist Commerce Cloud-seitig die Einbindung des JavaScripts des Omnichannel Managers erforderlich. Dafür muss in der javaScript.tag-Datei eine Einbindung der Taglib und des Tags caas:includeOcmScripts erfolgen. Die Auslieferung enthält Storefront-Anpassungen, in denen die Einbindung des Omnichannel Managers bereits erfolgt und somit nicht mehr notwendig ist.

Einbindung der Taglib und des Tags caas:includeOcmScripts

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

<caas:includeOcmScripts/>

2.2. OAuth-Konfiguration

Das FirstSpirit Connect-Modul benötigt für die Abfrage der Informationen aus der Commerce Cloud eine OAuth-Authentifizierung. Daher ist die Konfiguration eines OAuth-Clients innerhalb der Commerce Cloud erforderlich. Für das Anlegen eines solchen OAuth-Clients stehen zwei Möglichkeiten zur Verfügung:

automatisch per Import des nachfolgenden ImpExes
(in der Hybris Admin Console unter Console ImpEx Import)
manuell im Backoffice unter 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; ;

Der für die Vorschau genutzte OAuth-Client benötigt zwingend den Gültigkeitsbereich previewwebservices.

2.3. FlexibleSearch Restrictions

Der Produktreport im ContentCreator zeigt alle Produkte eines Produktkatalogs an und setzt somit voraus, dass die Detailseiten aller angezeigten Produkte aufrufbar sind. Falls Search Restrictions existieren, die den Aufruf der Produktdetailseiten bestimmter Produkte eines Produktkatalogs verhindern, müssen diese um die folgende Bedingung erweitert werden. Innerhalb der Bedingung muss der Platzhalter mit der ID des Produktkatalogs ausgetauscht werden.

Zusätzliche Bedingung innerhalb der Filter-Query einer Search Restriction für Produkte

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

Diese zusätzliche Bedingung verhindert, dass die jeweilige Search Restriction im Kontext der Staged-Version des Produktkatalogs angewandt wird.

Die Konfiguration von Search Restrictions erfolgt im Backoffice unter System Personalization. Im B2B Accelerator muss beispielsweise die Search Restriction Frontend_ProductApprovalStatus wie beschrieben angepasst werden.

Eine Erweiterung ist auch für Search Restrictions notwendig, die Inhaltsseiten betreffen. Auch hierbei muss innerhalb der Bedingung der Platzhalter mit der ID des Inhaltskatalogs ausgetauscht werden.

Zusätzliche Bedingung innerhalb der Filter-Query einer Search Restriction für Seiten

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

Im B2B Accelerator muss beispielsweise die Search Restriction Frontend_PageApprovalStatus wie beschrieben angepasst werden.

3. FirstSpirit - Installation und Konfiguration

Für die Verwendung der Funktionalitäten des FirstSpirit Connect-Moduls ist FirstSpirit-seitig die Installation und Konfiguration unterschiedlicher Komponenten erforderlich. Die folgenden Unterkapitel erläutern die dafür notwendigen Schritte.

Zur Nutzung des FirstSpirit Connect-Moduls müssen außerdem das Content as a Service- sowie das Omnichannel Manager-Modul konfiguriert werden. Die dafür notwendigen Schritte sind in der Content as a Service-Dokumentation bzw. in der Dokumentation des Omnichannel Managers beschrieben.

Neben den Standardgruppen Everyone, Administrators und Developers existieren im Referenzprojekt drei weitere externe Gruppen: Editors, ChiefEditors und ProjectAdmins. Die Gruppen besitzen verschiedene Rechte, die entsprechend ihrer Aufgaben gewählt und für die verschiedenen Verwaltungen definiert wurden. Personen außerhalb dieser Gruppen sind standardmäßig nicht berechtigt das Referenzprojekt zu verwenden.

Besteht darüber hinaus der Bedarf nach weiteren Accounts oder Gruppen, so ist ihre Erzeugung beim Technical Support anzufordern. Für neue Accounts ist dafür eine Angabe der folgenden Informationen erforderlich:

Vor- und Nachname
E-Mail-Adresse
zuzuordnende Gruppen

3.1. Konfiguration der Projekt-Komponente

Für den Einsatz des FirstSpirit Connect-Moduls ist eine projektspezifische Konfiguration notwendig. Diese wird über die Projekt-Komponente vorgenommen, die dem mitgelieferten Referenzprojekt bereits hinzugefügt ist.

Das Referenzprojekt bindet außerdem die Projekt-Komponente der CXT ContentCreator Extension ein. Diese enthält eine vordefinierte Konfiguration, deren Veränderung zu einer Verhaltensänderung des ContentCreators führen kann. Eine Anpassung der Konfiguration ist daher nur nach vorheriger Rücksprache mit dem Technical Support vorzunehmen.

Öffnen Sie für die Konfiguration den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften Projekt-Komponenten.

Abbildung 3. Server-Eigenschaften - Projekt-Komponenten

Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Selektieren Sie den Eintrag FirstSpirit Connect for SAP Commerce Cloud Project Configuration und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren.

Abbildung 4. Projekt-Komponente - Allgemein

URI: Die angegebene URI ist die Server-URI zur Commerce Cloud-Instanz.
Connection timeout (sec): Dieser Parameter bezeichnet die Zeitspanne (in Sekunden), bis der Verbindungsaufbau für die Kommunikation mit der Commerce Cloud abgebrochen wird.
Connection retries: Dieser Parameter definiert die Anzahl der Verbindungsversuche für die Kommunikation mit der Commerce Cloud.

Die nachfolgenden Felder dienen zur Konfiguration der Authentifizierung und sind in jedem Reiter vorhanden. Um die im Reiter Allgemein getätigten Einstellungen zu überschreiben, existiert in den übrigen Tabs die Möglichkeit, den Haken Override general OAuth settings zu setzen.

Auth Server URI: Dieser Parameter entspricht dem Standard-Endpunkt für die OAuth-Authentifizierung (relativ zur URI der Commerce Cloud-Instanz).
Username: In diesem Feld wird der Standardbenutzer für die OAuth-Authentifizierung eingetragen.

Der hier angegebene Benutzer muss in der Commerce Cloud folgenden Benutzergruppen angehören:

previewmanagergroup zur Erzeugung eines Vorschautickets
basecmsmanagergroup zur Anzeige von Produkt- und Kategorieinformationen in den Reports
cmsmanagergroup zur Erzeugung und Aktualisierung von Seiten in der Commerce Cloud

Password: In diesem Feld ist das Passwort des zuvor angegebenen Benutzers einzufügen.
OAuth Client ID: Dieses Feld dient der Angabe der Standard-Client-ID, die für die OAuth-Authentifizierung genutzt wird. Sie wirkt sich auf die Rechte der Nutzer aus.
OAuth Client Secret: Für die OAuth-Authentifizierung wird ein Secret genutzt, welches zu der angegebenen Client-ID passen muss.
OAuth Grant Type: Die OAuth-Authentifizierung benötigt abschließend einen Standard-Grant-Typ. Dieser kann entweder auf password oder client credentials gesetzt werden.
OAuth Einstellungen testen: Dieser Button testet den Verbindungsaufbau anhand der angegebenen Authentifizierungseinstellungen. Falls der Haken Override general OAuth settings in den übrigen Tabs gesetzt ist, werden diese Einstellungen mitgetestet.

Abbildung 5. Projekt-Komponente - Produkt DAP

Collection: In diesem Feld wird der Endpunkt für die Abfrage der Produktdaten festgelegt.

PDP URL

Hier ist die URL einer Produktdetailseite anzugeben. Erlaubt sind sowohl absolute als auch relative URLs. Als Platzhalter für den Produktcode kann {code} verwendet werden. Der Standardwert ist p/{code}.

Header/Extract/Icon/Thumbnail

Suchergebnisse im Produkte-Report zeigen standardmäßig im Kennsatz den Produktnamen, im Ausriss die Katalog-Id und eine Miniaturansicht an. Die Felder Header, Extract, Icon und Thumbnail ermöglichen eine Konfiguration dieser Informationen. Dafür stehen neben einfachen Texteingaben die folgenden Platzhalter zur Verfügung:

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

Die in den Feldern getätigten Eingaben ersetzen die Standardinformationen in den Suchergebnissen des Produkte-Reports. Textuelle Eingaben werden dabei unverändert übernommen. Bleiben die Felder leer, zeigen die Suchergebnisse die Standardinformationen an.

Override general OAuth settings

Die in diesem Reiter enthaltenen Felder für die OAuth-Authentifizierung ermöglichen die Überschreibung der Eingaben im Reiter Allgemein. Die Überschreibung erfolgt durch die Aktivierung der Checkbox Override general OAuth settings. Andernfalls werden weiterhin die Eingaben aus dem Reiter Allgemein für die Authentifizierung verwendet.

Abbildung 6. Projekt-Komponente - Kategorie DAP

Katalog Id: Aus dem an dieser Stelle definierten Katalog werden die Kategorien für das Kategorie-DAP bezogen.
Katalog Version: Für die Konfiguration ist die Version des Produktkatalogs notwendig, aus dem die Kategorien für das Kategorie-DAP bezogen werden.

CDP URL: An dieser Stelle ist die URL einer Kategoriedetailseite einzupflegen. Erlaubt sind sowohl absolute als auch relative URLs. Als Platzhalter für den Kategoriecode kann {code} verwendet werden. Der Standardwert ist c/{code}.
Override general OAuth settings: Die in diesem Reiter enthaltenen Felder für die OAuth-Authentifizierung ermöglichen die Überschreibung der Eingaben im Reiter Allgemein. Die Überschreibung erfolgt durch die Aktivierung der Checkbox Override general OAuth settings. Andernfalls werden weiterhin die Eingaben aus dem Reiter Allgemein für die Authentifizierung verwendet.

Abbildung 7. Projekt-Komponente - Vorschau

Language: Das Kürzel der gewünschten Sprache konfiguriert an dieser Stelle die Sprache des erzeugten Vorschautickets.
Resource Path: Dieses Feld definiert die URL der Ressource des erzeugten Vorschautickets.
Preview Servlet: Dieses Feld enthält den Namen des Preview-Servlet-Endpunkts der Commerce Cloud. Bei der Anbindung an die Version 20.11 der Commerce Cloud ist der Wert cx-preview einzutragen. Für ältere Versionen der Commerce Cloud ist der vorbelegte Wert previewServlet beizubehalten.
Page Id: Dieses Feld gibt die ID der Seite des erzeugten Vorschautickets an.
Catalog Versions: An dieser Stelle sind die Katalogversionen des erzeugten Vorschautickets hinzuzufügen.

Die bisher genannten Einstellungen im Reiter Vorschau korrespondieren zu den Parametern eines Vorschautickets in der Preview API der Commerce Cloud. Ein solches Ticket wird von FirstSpirit angefragt, um die Vorschau einer geschützten Storefront im ContentCreator zu ermöglichen.

Override general OAuth settings: Die in diesem Reiter enthaltenen Felder für die OAuth-Authentifizierung ermöglichen die Überschreibung der Eingaben im Reiter Allgemein. Die Überschreibung erfolgt durch die Aktivierung der Checkbox Override general OAuth settings. Andernfalls werden weiterhin die Eingaben aus dem Reiter Allgemein für die Authentifizierung verwendet.

Abbildung 8. Projekt-Komponente - Inhalte

Site Id: In diesem Feld ist die ID der Commerce Cloud-Site (z. B. powertools) anzugeben.
Content Catalog Id: Äquivalent zur Site Id ist in diesem Feld die Id des Content-Katalogs (z. B. powertoolsContentCatalog) einzutragen.
Content Catalog Version: An dieser Stelle ist auszuwählen, welche Version des Content-Katalogs zu nutzen ist (Staged oder Online).

Template Mappings

Für die Pflege bestehender Commerce Cloud-Seiten in FirstSpirit muss jedem Commerce Cloud-Template eine FirstSpirit-Vorlage zugeordnet werden. Dafür ist an dieser Stelle ein Mapping zwischen den Commerce Cloud-Template-Item-IDs und den entsprechenden FirstSpirit-Seitenvorlagen-UIDs zu definieren.

Da die auf den Templates basierenden Inhaltsseiten unterschiedliche URLs besitzen können, ermöglicht die Spalte Commerce Cloud URL Pattern darüber hinaus jeweils die Erzeugung einer spezifischen Vorschau-URL. Die Eingabe der URL kann entweder relativ zur Storefront oder zum Host erfolgen (siehe nachfolgendes Beispiel). Außerdem ist die Verwendung des Platzhalters pageUid möglich. Bleibt die Spalte leer, wird stattdessen die im Feld Contentpage URL definierte URL für die Vorschaudarstellung der entsprechenden Seite genutzt.

Beispiel
Die in der Abbildung sichtbare Konfiguration hätte folgende Bedeutung:

Tabelle 1. Commerce Cloud URL Pattern - Beispiel
FirstSpirit-Vorlage	Eingabe	resultierende URL	Beschreibung
content_page	/magazin/outdoor	http(s)://<host>/magazin/outdoor	Startet die Eingabe mit einem Slash, wird lediglich die Server-URL erweitert.
content_page_1	---	http(s)://<host>/<storefront-context-root>/preview-content?uid={pageUid}	Da in diesem Fall keine spezifische URL definiert ist, wird stattdessen die allgemeine `Contentpage URL` verwendet.
content_page_2	assortment/{pageUid}	http(s)://<host>/<storefront-context-root>/assortment/{pageUid}	Diese Eingabe besitzt keinen führenden Slash. Sie entspricht daher einer zur Storefront relativen URL. Des Weiteren enthält sie den Platzhalter `pageUid`.
content_page_3	indoor	http(s)://<host>/<storefront-context-root>/indoor	Auch diese Eingabe enthält keinen führenden Slash und führt daher ebenfalls zu einer Erweiterung der Storefront-URL.

Content Page Attribute Mapping

Die Angabe an dieser Stelle entspricht den Mappings der FirstSpirit-Contentpage-Attribute zu den Commerce Cloud-Contentpage-Attributen.

Zur Eingabe der FirstSpirit-Contentpage-Attribute werden folgende FirstSpirit-Eingabekomponenten unterstütuzt: 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.

Beispiel

Beispielhafte Konfiguration der Attribut-Mappings

[{
   "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 diesem Feld ist die UID des Strukturordners, in dem die in FirstSpirit verwalteten Inhaltsseiten abgelegt sind, einzutragen.

Contentpage URL: Inhaltsseiten können spezifische URLs besitzen, die sich optional während der Definition der zuvor zu konfigurierenden Template Mappings festlegen lassen. Verfügt eine Inhaltsseite über keine spezifische URL, wird für ihre Darstellung in der Vorschau stattdessen die in diesem Feld einzutragende allgemeine Contentpage URL genutzt. Für ihre Eingabe sind sowohl absolute als auch relative URLs sowie die Verwendung des Platzhalters {pageUid} erlaubt. Das Feld enthält standardmäßig den Wert preview-content?uid={pageUid}.
Override general OAuth settings: Die in diesem Reiter enthaltenen Felder für die OAuth-Authentifizierung ermöglichen die Überschreibung der Eingaben im Reiter Allgemein. Die Überschreibung erfolgt durch die Aktivierung der Checkbox Override general OAuth settings. Andernfalls werden weiterhin die Eingaben aus dem Reiter Allgemein für die Authentifizierung verwendet.

3.2. Hinzufügen der Web-Komponenten

Für den ContentCreator wird eine Web-Komponente benötigt, die dem mitgelieferten Referenzprojekt bereits hinzugefügt ist. Sie ist standardmäßig global im ServerManager im Bereich Server-Eigenschaften Web-Applikationen installiert. In diesem Fall sind alle für die Web-Komponente erforderlichen Installations- oder Konfigurationsschritte bereits seitens der Crownpeak Technology GmbH durchgeführt.

Alternativ ist jedoch auch eine Installation der Web-Komponente in den Projekt-Eigenschaften möglich. Ausschließlich in diesem Fall muss sie noch auf einem aktiven Webserver installiert werden. Öffnen Sie hierfür den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften Web-Komponenten.

Abbildung 9. Web-Komponenten in den Projekt-Eigenschaften

Innerhalb des Hauptpanels sind verschiedene Registerkarten zu sehen, in denen jeweils eine Liste der bereits vorhandenen Web-Komponenten sichtbar ist. Diese Liste enthält für den ContentCreator die folgenden Einträge:

BasicWorkflows_ContentCreator_Library (nur bei der Verwendung der BasicWorkflows erforderlich)
CXT ContentCreator Extension Extension: WebApp for ContentCreator (nur in Verbindung mit dem Referenzprojekt)
FirstSpirit Connect for SAP Commerce Cloud Web App
FirstSpirit ThirdPartyPreview WebApp

Selektieren Sie in der Registerkarte einen aktiven Webserver über die gleichnamige Auswahlbox und starten Sie die Installation über den Button Installieren. Nach der erfolgreichen Installation öffnet sich ein Dialog, in welchem die Aktivierung des Webservers zu bestätigen ist.

Detaillierte Informationen zur Konfiguration von Web-Komponenten finden Sie in der FirstSpirit Dokumentation für Administratoren.

3.3. Definition der externen Vorschau-URL

Durch die Verwendung des Omnichannel Managers stellt der ContentCreator externe Inhalte aus der Storefront der Commerce Cloud dar, auf die der Omnichannel Manager eine Zugriffsmöglichkeit benötigt. In den ContentCreator-Eigenschaften ist daher die Vorschau-URL der Storefront anzugeben. Diese ist zwingend durch den Parameter firstSpiritPreview=1 zu erweitern, der für die Initialisierung der Vorschau erforderlich ist. Da die Angabe der URL stets projektspezifisch ist, existiert für sie innerhalb des Referenzprojekts keine Standardkonfiguration.

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

Öffnen Sie für die Eingabe den Bereich Projekt-Eigenschaften ContentCreator innerhalb des ServerManagers und tragen Sie in dem Feld Externe Vorschau-URL die URL der Storefront ein.

Abbildung 10. Externe Vorschau-URL

3.4. Ausgabekanal

Zusätzlich zu den bereits vorhandenen Ausgabekanälen eines Projekts wird ein weiterer XML-Kanal benötigt. Dieser muss für leere Projekte manuell angelegt werden, ist innerhalb des mitgelieferten Referenzprojekts FirstSpirit Connect Reference Project jedoch bereits enthalten.

Der Ausgabekanal wurde im ServerManager unter dem Punkt Projekt-Eigenschaften Vorlagensätze angelegt und besitzt folgende Konfiguration:

Abbildung 11. Ausgabekanal

In der gleichnamigen Auswahlbox muss die Konvertierungsregel ausgewählt werden, die für den CaaS anzulegen ist. Eine Beschreibung der dafür notwendigen Schritte ist in der Content as a Service-Dokumentation enthalten.

Der Ausgabekanal ist aktiviert und steht somit im Projekt zur Verfügung. Er dient der Definition der zu übertragenden Inhalte, die während der Generierung in Nachrichten zusammengefasst und an den CaaS übermittelt werden.

3.5. Freigabe-Arbeitsablauf

Die Freigabe von Inhalten durch Redakteure erfolgt innerhalb des mitgelieferten Referenzprojekts FirstSpirit Connect Reference Project über den Freigabe-Arbeitsablauf der BasicWorkflows. Dieser kann alternativ zu projektspezifischen Arbeitsabläufen eingesetzt werden.

Installation des BasicWorkflows-Moduls

Vor der Verwendung des Freigabe-Arbeitsablaufs muss zunächst das BasicWorkflows-Modul auf dem FirstSpirit-Server installiert und die Web-Komponente aktiviert sein. Die dafür notwendigen Schritte sind analog zur Installation der anderen Module und der Aktivierung der dem FirstSpirit Connect-Modul zugehörigen Web-Komponente. Standardmäßig sind diese Schritte bereits durchgeführt.

Der Einsatz der BasicWorkflows im ContentCreator erfordert darüber hinaus die Auswahl des bereitgestellten BasicWorkflows Status Providers im Bereich Projekt-Eigenschaften ContentCreator innerhalb des ServerManagers. Im Referenzprojekt FirstSpirit Connect Reference Project ist diese Einstellung bereits vorgenommen.

Abbildung 12. Element Status Provider

Vorlagen

Die BasicWorkflows benötigen verschiedene Vorlagen. Diese müssen üblicherweise über das Kontextmenü in das verwendete FirstSpirit-Projekt importiert werden. Im Referenzprojekt sind sie jedoch bereits enthalten und ein Import der Vorlagen ist somit nicht notwendig.

Rechtevergabe

Im letzten Schritt muss der Freigabe-Arbeitsablauf in den einzelnen Verwaltungen erlaubt werden, um auf FirstSpirit-Elementen ausgeführt werden zu können. Dafür lässt sich auf den Root-Knoten der Verwaltungen über den Kontextmenüeintrag Extras Rechte ändern die Rechtevergabe öffnen. Dieser Schritt ist im Referenzprojekt ebenfalls bereits durchgeführt und entfällt damit.

Die auf den Root-Knoten der Verwaltungen gesetzten Rechte zur Ausführung des Arbeitsablaufs beziehen sich auf die Gruppe Everyone. Falls dies nicht gewünscht ist, muss eine manuelle Anpassung der Rechte erfolgen.

Nähere Informationen zur Installation, Konfiguration und Funktionalität des Arbeitsablaufs finden Sie in der BasicWorkflows-Dokumentation.

3.6. Projekteinstellungen

Für die Verbindung zwischen FirstSpirit und der Commerce Cloud sind einige projektspezifische Informationen unentbehrlich. Sie werden über das Formular der Projekteinstellungen erfasst und sind innerhalb des verwendeten Projekts anzugeben.

Innerhalb des mitgelieferten Referenzprojekts existiert die Projekteinstellungen-Seite mit der notwendigen Konfiguration bereits. In diesem Fall muss die Erzeugung der Vorlage sowie der erforderlichen Komponenten somit nicht mehr erfolgen.

Änderungen an den Projekteinstellungen sind nicht sofort wirksam, da sie in der Session des Benutzers gespeichert werden. Sie erfordern daher einen Neustart des Clients.

Abbildung 13. Projekteinstellungen

CONTENT PAGE | LANDINGPAGE2 TEMPLATE: Für die Pflege bestehender Commerce Cloud-Inhaltsseiten in FirstSpirit muss jedem Commerce Cloud Page Template eine FirstSpirit-Vorlage zugeordnet werden. Die in diesem Feld ausgewählte Vorlage dient der Pflege von Commerce Cloud-Inhaltsseiten, die auf dem LandingPage2Template basieren. Zur Unterstützung anderer bzw. weiterer Commerce Cloud-Vorlagen muss das Formular der Projekteinstellungen-Seite um weitere Felder dieser Art ergänzt werden. Die Angabe ermöglicht den Skripten page_type_mapping und get_page_type die richtige Zuordnung zwischen den Commerce Cloud-seitigen und FirstSpirit-seitigen Inhaltsseiten herzustellen. Bei Änderungen an der Projekteinstellungen-Seite sind daher auch immer diese zwei Skripte anzupassen.
CONTENT PAGE FOLDER: Alle Inhaltsseiten werden innerhalb des FirstSpirit-Projekts in demselben Inhalte-Ordner erstellt, der an dieser Stelle konfigurierbar ist. Das Skript page_type_mapping benötigt die Angabe des Ordners für die Pflege bestehender Commerce Cloud-Inhaltsseiten.

3.7. Deployment-Auftrag

Die Freigabe von Inhalten sieht standardmäßig keine Aktualisierung des Online CaaS und keine Datenübertragung in die Commerce Cloud vor. Sie umfasst stattdessen lediglich den FirstSpirit-Freigabeprozess, der sich beispielsweise durch die Benutzung des Freigabe-Arbeitsablaufs der BasicWorkflows abbilden lässt. Eine Aktualisierung des Online CaaS sowie eine Datenübertragung in die Commerce Cloud findet erst im Rahmen einer Veröffentlichung statt.

Die Veröffentlichung freigegebener redaktioneller Inhalte erfolgt durch die Ausführung eines CaaS-Auftrags. Er führt eine CaaS-Generierung aus und überträgt die Daten in den Online CaaS, der sie der Commerce Cloud bereitstellt. Darüber hinaus kann durch den Auftrag die Synchronisation des Online Content-Katalogs der Commerce Cloud angestoßen werden.

Die Aktualisierung des Online Content-Katalogs kann verschiedene Abhängigkeiten besitzen. Aus diesem Grund ist die Entscheidung, ob das Approval und die Synchronisation ein Teil des Importprozesses sind, stets projektspezifisch zu treffen.

Es ist auch möglich, lediglich ein Approval und eine direkte Veröffentlichung in den Online Content-Katalog durchzuführen. In diesem Fall ist die Synchronisation der Daten projektspezifisch sicherzustellen.

Das mitgelieferte Referenzprojekt besitzt bereits einen Auftrag, der die folgenden Aktionen enthält:

Abbildung 14. Aktionen des Generierungsauftrags

Die Aktionen Initialize CaaSGeneration, CaaS Generate, CaaS CleanUp und Finalize CaaS Generation entsprechen dem CaaS-Auftrag. Er wird durch die in den nachfolgenden Unterkapiteln beschriebenen Aktionen ergänzt. Da das Bulk Update auf das Approval bzw. die Sync-Definition zugreift, erfolgt die Beschreibung der beiden Aktionen in umgekehrter Reihenfolge.

Die Content as a Service-Dokumentation enthält weitere Informationen zum CaaS-Auftrag.

3.7.1. SAPCC - Bulk Update

In FirstSpirit gepflegte Produktdetailseiten basieren grundsätzlich auf Seiten, die Commerce Cloud-seitig bereits existieren. Die Bearbeitung dieser Seiten bezieht sich deswegen jeweils nur auf ihre Inhalte, nicht jedoch auf ihre Erstellung. Ihre Veröffentlichung erfordert daher lediglich eine Aktualisierung der im Online CaaS gespeicherten Daten. Eine Synchronisation des Online Content-Katalogs der Commerce Cloud ist hingegen nicht notwendig.

Im Gegensatz zu den Produktdetailseiten können Inhaltsseiten in FirstSpirit erzeugt werden. Eine ausschließliche Aktualisierung des Online CaaS ist für ihre Veröffentlichung deshalb nicht ausreichend. Sie muss zusätzlich einen Importprozess für die Inhaltsseiten in die Commerce Cloud umfassen. Dieser Importprozess ist dem Deployment-Auftrag in Form des Skripts SAPCC - Bulk Update als letzte Aktion hinzuzufügen.

Das Bulk Update greift für die Aktualisierung der Online Storefront auf das Approval und die Sync-Definition zu. Sie entsprechen der im nachfolgenden Kapitel beschriebenen Aktion.

Die Aktualisierung des Online Content-Katalogs kann jedoch verschiedene Abhängigkeiten besitzen. Aus diesem Grund ist die Aktion optional und die Entscheidung, ob sie Teil des Importprozesses ist, stets projektspezifisch zu treffen. Fehlt sie, aktualisiert das Bulk Update ausschließlich die Staged Storefront.

Es ist auch möglich, lediglich ein Approval und eine direkte Veröffentlichung in den Online Content-Katalog durchzuführen. In diesem Fall ist die Aktion für das Approval und die Sync-Definition anzupassen und die Synchronisation der Daten projektspezifisch sicherzustellen.

SAPCC - Bulk Update

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

Für die Commerce Cloud-seitige Erzeugung bzw. Aktualisierung der Inhaltsseiten muss dem Importprozess die Zuordnung zwischen den FirstSpirit- und den Commerce Cloud-Inhaltsseiten bekannt sein. Dafür ist ein Mapping zwischen ihnen erforderlich, das in der Projekt-Komponente im Bereich Inhalte zu konfigurieren ist.

An derselben Stelle ist der Referenzname des Strukturordners anzugeben, in dem die Inhaltsseiten innerhalb des FirstSpirit-Projekts gespeichert sind. Der Strukturordner ermöglicht dem Importprozess die Identifikation der zu übertragenden Seiten. Aus diesem Grund darf er nur Inhaltsseiten enthalten, die von FirstSpirit verwaltet werden. Im Rahmen des Deployments führt der Importprozess für alle in diesem Ordner enthaltenen Seiten die Aktualisierung bzw. Erzeugung in der Commerce Cloud aus.

3.7.2. Content Page Approval & Sync Definition

Das Bulk-Update führt standardmäßig nur eine Aktualisierung des Staged Content-Katalogs der Commerce Cloud durch. Um darüber hinaus eine Aktualisierung des Online Content-Katalogs anzustoßen, ist zusätzlich ein Approval und die Synchronisation der betroffenen Seiten notwendig.

Der Importprozess erlaubt für diesen Fall die Ausführung zusätzlicher Aktualisierungslogik, die für jede zu aktualisierende bzw. zu erzeugende Inhaltsseite angewendet wird. Sie kann dem Deployment-Auftrag in Form des Skripts Content Page Approval & Sync Definition hinzugefügt werden. Da das zuvor beschriebene Bulk Update die Aktualisierungslogik verwendet, muss sie vor diesem ausgeführt werden.

Das Approval und die Synchronisation erfolgt mithilfe der API des FirstSpirit Connect-Moduls. Die zugehörige Dokumentation bzw. dessen JavaDoc-JAR ist in der Auslieferung enthalten.

Inhalte im Staged Content-Katalog können Verweise auf Produkte des Staged Product-Katalogs enthalten. Um Inkonsistenzen in den Online-Katalogen zu vermeiden, wird vor der Synchronisation des Content-Katalogs eine Synchronisation des Product-Katalogs empfohlen.

Ein Standardprozess für die Synchronisation verschiedener Kataloge besitzt stets komplexe und projektspezifische Anforderungen. Aus diesem Grund ist die Beschreibung eines solchen Prozesses an dieser Stelle nicht möglich.

Der folgende Code-Ausschnitt zeigt beispielhaft die Definition des Approvals einer importierten Inhaltsseite und deren Synchronisation in den Online Content-Katalog.

Aktualisierungslogik zum Approval und zur Synchronisation einer Inhaltsseite

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. Erweiterung des Standardprozesses

Der zuvor beschriebene Standardprozess zur Freigabe und Veröffentlichung von Inhalten kann beliebig projektspezifisch angepasst oder erweitert werden. Dieses Kapitel beschreibt mögliche Anwendungsfälle und enthält Hinweise für deren Behandlung.

Vorschau von Änderungen an Commerce Cloud-spezifischen Seitenattributen: Redaktionelle Änderungen an Inhalts- oder Produktdetailseiten werden automatisch in den Preview CaaS übertragen und sind damit für die Anzeige in der Vorschau verfügbar. Konträr dazu verhält sich die Verarbeitung von Änderungen an Commerce Cloud-spezifischen Seitenattributen der Inhaltsseiten: Sie werden nicht im CaaS abgelegt, sondern im Rahmen einer Veröffentlichung in den Staged Content-Katalog übertragen.

Sollen diese Änderungen ebenfalls bereits in der Vorschau verfügbar sein, muss ihre Übertragung in den Staged Content-Katalog manuell ausführbar sein. Dazu wird ein Auftrag benötigt, der wie der Deployment-Auftrag aus einer Generierung und einem daran anschließenden Importprozess besteht. Anstelle einer CaaS-Vollgenerierung ist in diesem Fall jedoch eine CaaS-Teilgenerierung zu wählen. Die Aktualisierungslogik für den Importprozess muss außerdem ein Unapproval der Inhaltsseite durchführen und darf keine Synchronisation anstoßen.
Approval einer Inhaltsseite bei der Seitenfreigabe: Mithilfe des Freigabe-Arbeitsablaufs besteht die Möglichkeit, neben der FirstSpirit-Freigabe gleichzeitig ein automatisches Approval der dazugehörigen Commerce Cloud-Seite im Staged Content-Katalog durchzuführen. Dafür ist der Arbeitsablauf so anzupassen, dass er den entsprechenden Deployment-Auftrag aufruft. Um nur die einzelne, freigegebene Seite zu aktualisieren, ist statt der CaaS-Vollgenerierung lediglich eine CaaS-Teilgenerierung auszuführen. Außerdem darf die Aktualisierungslogik auch in diesem Fall - ebenso wie bei der Vorschau von Änderungen an Commerce Cloud-spezifischen Seitenattributen - keine Synchronisation anstoßen.
Hot-Deployment: Ein Hot-Deployment, das der Veröffentlichung einer einzelnen Seite entspricht, verhält sich wie die normale Veröffentlichung freigegebener Seiten. Allerdings ist statt einer Delta- oder Vollgenerierung lediglich eine Teilgenerierung der zu veröffentlichenden Seite durchzuführen.

Direkte Veröffentlichung in den Online Content-Katalog

Der beschriebene Deployment-Auftrag aktualisiert sowohl den Staged als auch des Online Content-Katalog. Dafür stößt er ein Approval und die Synchronisation der betroffenen Inhaltsseiten an. Alternativ dazu besteht die Möglichkeit, lediglich ein Approval und eine direkte Veröffentlichung in den Online Content-Katalog anzustoßen. In diesem Fall entfällt die automatische Synchronisation.

Für die Realisierung der direkten Veröffentlichung ist die Durchführung folgender Schritte erforderlich:

Im ersten Schritt muss innerhalb der Auftragsaktion Content Page Approval & Sync Definition die Sync-Definition entfernt werden. Dafür ist die Aktualisierungslogik, wie im Code-Ausschnitt dargestellt, anzupassen.

Durch die direkte Veröffentlichung und die Anpassung der Aktualisierungslogik entfällt die automatische Synchronisation beider Content-Kataloge. Aus diesem Grund ist projektspezifisch sicherzustellen, dass die Inhalte beider Kataloge weiterhin identisch sind. Andernfalls sind Divergenzen unvermeidbar.

Aktualisierungslogik zum Approval einer Inhaltsseite

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

Durch eine anschließende Duplizierung des bestehenden Auftrags wird ein identischer, zweiter Auftrag erzeugt. Beide Aufträge würden ohne eine weitere Konfiguration in den Content Catalog schreiben, der im Inhalte-Tab der Projekt-Komponente als Content Catalog Version ausgewählt ist. Im Referenzprojekt handelt es sich dabei um den Staged Content Catalog.

Damit der zweite Auftrag in den Online Content Catalog schreibt, ist in den Eigenschaften der Auftragsaktion SAPCC - Bulk Update der Parameter catalogVersion hinzuzufügen und mit dem Wert Online zu konfigurieren. Im Falle eines fehlenden Wertes oder einer falschen Konfiguration, bricht das Bulk Update ab und eine Exception tritt auf. Andernfalls enthält das Log eine Information, welcher Content-Katalog für das Deployment verwendet wird.

Abbildung 15. Parameter catalogVersion

Erfolgt wie in diesem Abschnitt beschrieben das Schreiben in den Online Content Catalog durch einen separaten Auftrag, so ist im Auftrag, der in den Staged Content Catalog schreibt, die CaaS-Generierung anzupassen. Diese muss äquivalent zum Schreiben in den Staged Content Catalog den Preview CaaS befüllen. Informationen zur notwendigen Anpassung der CaaS-Generierung sind im Abschnitt Initialize CaaSGeneration der Content as a Service-Dokumentation enthalten.

4. Anwendungsfälle

Das FirstSpirit Connect-Modul stellt unterschiedliche Möglichkeiten bereit, auf Commerce Cloud-Inhalte zuzugreifen und diese in FirstSpirit zu verwenden. Diese werden nachfolgend anhand des mitgelieferten Referenzprojekts FirstSpirit Connect Reference Project in Form von Anwendungsfällen beschrieben.

4.1. Pflege bestehender Commerce Cloud-Inhaltsseiten

Das FirstSpirit Connect-Modul bietet Redakteuren die Möglichkeit, Inhaltsseiten, die Commerce Cloud-seitig bereits existieren, in FirstSpirit zu pflegen. Die Inhaltsseiten werden dafür mithilfe des Omnichannel Managers innerhalb des ContentCreators dargestellt und integrieren sich so nahtlos in den mit FirstSpirit bekannten Redaktionsprozess.

Die Pflege der Inhaltsseiten in FirstSpirit setzt neben der Einbindung des Omnichannel Managers, die ein Schritt der Installation ist, die Befüllung des Ausgabekanals der Seiten- und Absatzvorlagen voraus. Darüber hinaus ist eine Anpassung des entsprechenden Page Templates in der Commerce Cloud notwendig.

4.1.1. Seitenvorlage

Die Bearbeitung von Inhaltsseiten im FirstSpirit-Projekt erfolgt grundsätzlich auf Basis einer FirstSpirit-Seitenreferenz. Diese und die ihr zugrundeliegende Seite müssen für Commerce Cloud-seitig bereits existierende Inhaltsseiten zunächst angelegt werden. Innerhalb des Referenzprojekts FirstSpirit Connect Reference Project läuft die Erzeugung dieser Seitenreferenz und ihrer Seite automatisch im Hintergrund und für den Redakteur unsichtbar ab. Das Skript page_type_mapping ermittelt dabei anhand des Commerce Cloud Page Templates die zugehörige FirstSpirit-Seitenvorlage, die in den Projekteinstellungen referenziert ist.

Während der Erzeugung einer Inhaltsseite wird in ihrem Formular die ID der zugehörigen Commerce Cloud-Seite gespeichert, die für die Darstellung der Seite in der Vorschau erforderlich ist. Die Seitenvorlage enthält daher die versteckte Eingabekomponente pt_cc_identifier. Werden dem Projekt weitere Seitenvorlagen hinzugefügt, muss ihr jeweiliges Formular diese Eingabekomponente ebenfalls enthalten.

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

Der folgende Code-Ausschnitt zeigt in gekürzter Form den Ausgabekanal der Seitenvorlage im Referenzprojekt:

Ausgabekanal der Seitenvorlage

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

Die Seite besitzt die drei Inhaltsbereiche stage_body, tiles_body und main_body und bildet eine landingLayout2Page.jsp-Seite ab. Während die ersten beiden Inhaltsbereiche der Bearbeitung bereits existierender Inhalte aus der Commerce Cloud dienen, ermöglicht der dritte die Ergänzung weiterer Absätze. Im Referenzprojekt stehen dafür die Absatzvorlagen banner_section, category_teaser_section und text_picture_section zur Verfügung. Ihre Inhalte werden dem in der Vorlage erzeugten JSON-Objekt slots hinzugefügt.

Dafür sind pro Inhaltsbereich zwei Anweisungen notwendig, mit denen sich sowohl statische als auch dynamische Inhalte erfassen lassen. Letztere können ausschließlich im Text-Bild-Absatz enthalten sein, da nur er die Möglichkeit besitzt, dynamische Produktdaten einzubinden. Der Absatz verwendet dafür die Linkvorlage a_product_price_link, in deren Ausgabekanal der Wert des Parameters active für die Variable dynamicContent auf true gesetzt wird.

Zusätzlich zu den redaktionellen Inhalten werden dem in der Vorlage erzeugten JSON-Objekt die previewId sowie die pageRevisionId der Seitenreferenz übergeben: Die previewId wird Commerce Cloud-seitig im PAGE_PREVIEW_DATA-Objekt der Vorlage gespeichert und dient der Identifikation der Seitenreferenz. Die Identifikation erfolgt über das JavaScript des Omnichannel Managers. Die pageRevisionId ist eine technische Abhängigkeit und stellt sicher, dass die Anzeige dynamischer Inhalte im ContentCreator stets aktuell ist.

Das erzeugte JSON-Objekt ist ein Teil des zu generierenden CaaS-Items und lässt sich innerhalb der Commerce Cloud-Templates auslesen.

4.1.2. Absatzvorlage

In einer Commerce Cloud-Seite enthaltene Slots werden FirstSpirit-seitig durch die Absätze banner_section, category_teaser_section und text_picture_section dargestellt. Wird für eine bestehende Commerce Cloud-Seite die entsprechende Inhaltsseite im FirstSpirit-Projekt erzeugt, werden sie automatisch mit angelegt und mit den bestehenden Inhalten befüllt.

Der folgende Code-Ausschnitt zeigt den Ausgabekanal des Text-Bild-Absatzes aus dem Referenzprojekt:

Ausgabekanal des Text-Bild-Absatzes

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

Er besitzt diverse Eingabekomponenten für die Angabe einer Überschrift, eines Texts und eines Bilds, für das sich dessen Position und eine Bildbeschreibung definieren lassen. Ihre Darstellung erfolgt innerhalb eines DIVs, für welches das Attribut data-preview-id mit dem Wert $CMS_VALUE(previewId())$ definiert ist. Das Attribut dient sowohl der Dekoration als auch der Identifikation des Absatzes, die auch in diesem Fall durch das JavaScript des Omnichannel Managers durchgeführt wird. Für die Bereitstellung medienspezifischer Aktionen, wie beispielsweise die Freigabe oder der Zuschnitt eines Bilds, ist dasselbe Attribut auch für das img-Tag angegeben.

Die Dokumentation des Omnichannel Managers enthält zusätzliche Information zur Verwendung der Preview Id.

4.1.3. Commerce Cloud Page Template

Die Erstellung und Bearbeitung redaktioneller Inhalte erfolgt FirstSpirit-seitig im ContentCreator. In diesem ist mithilfe des Omnichannel Managers die Staged Storefront der Commerce Cloud eingebettet. Die Staged Storefront greift ihrerseits auf den Preview CaaS zu und ermittelt aus diesem die aktuellen FirstSpirit-Inhalte. Dies gilt äquivalent für die Online Storefront und den Online CaaS.

Für diese Verkettung sind Anpassungen am Page Template der Commerce Cloud-Inhaltsseite notwendig, die im Verlauf dieses Kapitels erläutert werden. Sie sind in der landingLayout2Page.jsp-Seite, die ein Bestandteil der Auslieferung ist, bereits enthalten und können in dieser nachvollzogen werden.

Der folgende Code-Ausschnitt zeigt die Abfrage eines CaaS-Items, das in der Variable caasItem gespeichert wird. Im ersten Schritt findet dafür die Ermittlung der CaaS-Collection statt, in der die Daten gespeichert sind: Die Speicherung der FirstSpirit-Inhaltsseiten aus dem Referenzprojekt erfolgt immer in die Collection contentpages, während weitere Inhalte in der Standard-Collection content abgelegt werden.

Beispiel - Abfrage des CaaS-Items

<%@ 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" />

Für die Bearbeitung redaktioneller Inhalte zeigt der ContentCreator die bekannten EasyEdit-Buttons an, die beim Hovern zusammen mit einem Rahmen erscheinen. Durch die Verwendung des Omnichannel Managers stellt der ContentCreator jedoch externe Inhalte dar, für deren Hervorhebung der Omnichannel Manager Informationen aus der Commerce Cloud benötigt. Diese werden aus einem Datenobjekt gelesen, dessen Befüllung über das zugehörige Page Template in der Commerce Cloud erfolgt.

Der folgende Code-Ausschnitt zeigt die beispielhafte Befüllung eines solchen Datenobjekts, dem der Page Type, die Preview Id, die Page Id und das Page Template übergeben werden. Die Preview Id entspricht dabei der Id des zuvor ermittelten CaaS-Items. Konnte kein CaaS-Item abgefragt werden, bleibt die Preview Id innerhalb des Datenobjekts leer.

Beispiel - Befüllung eines Datenobjekts

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

Für Produktdetailseiten ist statt der Uid der Produkt-Code als Page-Id anzugeben:

Beispiel - Angabe des Produkt-Codes

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

Zusätzlich zur Ermittlung des CaaS-Items und der Befüllung des Datenobjekts ist die Definition der Ausgabe erforderlich. Dabei ist zu überprüfen, ob das zuvor ermittelte CaaS-Item Inhalte für den entsprechenden Inhaltsbereich besitzt. Ist dies nicht der Fall, lässt sich ein Fallback-Inhalt festlegen.

Der folgende Code-Ausschnitt zeigt die Definition der Ausgabe für den Inhaltsbereich stage_body:

Beispiel - Definition der Ausgabe

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

Sowohl im Positiv- als auch im Fallback-Fall ist die Angabe eines Dom-Elements notwendig, das den FirstSpirit-Inhaltsbereich markiert. Es ermöglicht die visuelle Hervorhebung und die Pflege externer Inhalte im ContentCreator. Dafür muss dem Dom-Element über das Attribut data-slot-name der Name des Inhaltsbereichs übergeben werden. Im Fallback-Fall benötigt das Dom-Element außerdem das Attribut data-fs-content-editing. Es steuert die Anzeige eines Plus-Buttons im ContentCreator, der beim Hovern entweder das Label override content oder add content anzeigt.

override content

Werden im Fallback-Fall bestehende Inhalte aus der Commerce Cloud angezeigt, besitzt der Button beim Hovern das Label override content. Dies bedeutet, dass für den Inhaltsbereich noch kein FirstSpirit-seitiger Inhalt existiert. Aus diesem Grund ist lediglich eine Überschreibung, jedoch keine Editierung des bestehenden Inhalts möglich. Der zuvor dargestellte Code-Ausschnitt zeigt diese Option.

Abbildung 16. Button override content

add content

Enthält das Dom-Element im Fallback-Fall keinen Inhalt, besitzt der Button beim Hovern das Label add content. Diese Situation kann eintreten, wenn Commerce Cloud-seitig für den Bereich beispielsweise im Fall einer leeren Seite kein Inhalt existiert oder wenn für das Dom-Element kein Inhalt definiert wird. Innerhalb der landingLayout2Page.jsp-Seite, die in der Auslieferung enthalten ist, wird diese Option für die Ausgabe des Inhaltsbereichs main_body verwendet:

Beispiel - Fallback für die Ausgabe des Inhaltsbereichs main_body

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

Abbildung 17. Button add content

4.2. Inhaltspflege auf neuen Commerce Cloud-Contentpages

Die Pflege von Inhalten auf neuen Commerce Cloud-Inhaltsseiten besitzt dieselben Voraussetzungen wie die Pflege bestehender Commerce Cloud-Inhaltsseiten.

Allerdings ist die Erstellung neuer Seiten in der Projekt-Komponente zu konfigurieren. Sofern diese Konfiguration gesetzt ist, kann die bekannte Funktionalität des ContentCreators für die Erstellung neuer Seiten genutzt werden.

Das Attribut label neuer Commerce Cloud-Inhaltsseiten wird durch das FirstSpirit Connect-Modul gesetzt und beginnt standardmäßig mit einem Slash (/).

4.3. Dynamische Inhalte

Das FirstSpirit Connect-Modul erlaubt die Pflege dynamischer Inhalte. Dabei handelt es sich um Code, der im Ausgabekanal der FirstSpirit-Vorlage zu definieren ist und im generierten CaaS-Item gespeichert wird. Seine Auswertung erfolgt zum Ausgabezeitpunkt des Inhaltsbereichs im Commerce Cloud Page Template.

FirstSpirit-seitige Anpassungen

Die Einbindung dynamischer Inhalte ist im mitgelieferten Referenzprojekt durch die Linkvorlage a_product_price_link realisiert. Sie lässt sich innerhalb eines Text-Bild-Absatzes verwenden und bindet mithilfe der Template-Sprache Apache Velocity den Namen und den Preis eines Produkts ein. Dafür erfolgt ein Zugriff auf die Kontextobjekte productOptions und productFacade, die das Add-on in der Storefront während der Auswertung bereitstellt:

Das Kontextobjekt productOptions entspricht einer Liste aller Werte des ProductOption-Enums.
Das Kontextobjekt productFacade stellt eine Referenz zur ProductFacade dar.

Der folgende Code-Ausschnitt zeigt den Ausgabekanal der Linkvorlage a_product_price_link im Referenzprojekt:

Ausgabekanal der Linkvorlage

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

Innerhalb der Vorlage wird im ersten Schritt der Produkt-Code des referenzierten Produkts ermittelt und der getProductForCodeAndOptions-Methode zusammen mit dem productOptions-Kontextobjekt übergeben. Dadurch sind innerhalb der Variablen product alle Produktinformationen verfügbar. Um die verwendeten Produktinformationen für die Generierung des CaaS-Items zu erfassen, wird die Variable dynamicContent benötigt. Sie wird innerhalb der FirstSpirit-Seitenvorlage ausgewertet und muss für den Parameter active den Wert true besitzen.

Da die dynamischen Inhalte im Gegensatz zu den statischen Inhalten für die Darstellung im ContentCreator aus der Staged Storefront bezogen werden, müssen sie identifizierbar sein. Sie sind dafür mit einem Dom-Element zu umschließen, welches das Attribut data-dynamic-content mit dem Wert true enthält. Darüber hinaus ist in der Seitenvorlage die Angabe der pageRevisionId erforderlich. Sie dient dem Abgleich, dass die Revision des CaaS-Items stets mit der im ContentCreator angezeigten Seiten übereinstimmt, und ermöglicht andernfalls eine Aktualisierung. Die Abfrage der dynamischen Inhalte aus der Staged Storefront ist notwendig, da ihre Auswertung erst dort erfolgt. Würden sie ebenso wie die statischen Inhalte direkt aus FirstSpirit ermittelt, würde der ContentCreator lediglich den für sie im Ausgabekanal definierten Code anzeigen.

Commerce Cloud-seitige Anpassungen

Die Auswertung des Codes dynamischer Inhalte erfolgt im Commerce Cloud Page Template. Sie wird während des Zugriffs auf den entsprechenden Inhaltsbereich innerhalb des Ergebnisobjekts des caas:request-Tags durchgeführt und liefert einen String zurück. Die Ausgabe unterscheidet sich daher nicht von der statischer Inhalte und ist ebenso zu definieren.

Der folgende Code-Ausschnitt zeigt in gekürzter Form die Definition der Ausgabe für den Inhaltsbereich stage_body in der landingLayout2Page.jsp-Seite, die ein Bestandteil der Auslieferung ist:

Beispiel - Definition der Ausgabe

<%@ 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. Inhaltspflege auf Produktdetailseiten

Die Pflege von Inhalten auf Produktdetailseiten setzt neben den Storefront-Erweiterungen auch die Änderungen im Ausgabekanal der Vorlagen voraus, die im Kapitel Pflege bestehender Commerce Cloud-Inhaltsseiten beschrieben werden.

Anschließend können Produktdetailseiten wie Inhaltsseiten gepflegt werden.

Produktdetail- und Inhaltsseiten müssen in verschiedenen Struktur- und Inhaltsordnern in FirstSpirit sowie unterschiedlichen Collections im CaaS gespeichert werden.

4.5. Löschung von FirstSpirit-verwalteten Contentpages

Im Fall der Inhaltspflege auf Commerce Cloud-Contentpages ist FirstSpirit das führende System, welches die Seiten verwaltet und somit auch für deren Löschung zuständig ist. Für die Löschung dieser Seiten aus der Commerce Cloud kann die FirstSpirit-Executable CMSItemRemoval benutzt werden. Diese Executable kann mit der Angabe eines itemUid-Parameters, der die UID der zu löschenden Seitenreferenz beinhaltet, aufgerufen werden. Alternativ kann die Executable auch innerhalb eines Arbeitsablaufs benutzt werden. In diesem Fall ist sicherzustellen, dass eine Transition trigger_finish_full existiert, da die Executable nach dem erfolgreichem Löschen auf diese Transition weiterschaltet. Dies erlaubt die Integration der Löschung von Seiten aus der Commerce Cloud in einen Lösch-Arbeitsablauf. Der folgende Code-Ausschnitt zeigt den Aufruf der Executable innerhalb eines Skripts.

Aufruf der CMSItemRemoval-Executable

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

Nach dem Löschen einer Seite wird der Redakteur auf die Startseite weitergeleitet.

4.6. Produktreferenzierung

Die Referenzierung von Produkten erfordert Anpassungen im Formular und Ausgabekanal einer Vorlage.

4.6.1. Formular

Für die Referenzierung von Produkten in einer Vorlage muss diese zunächst über ein entsprechendes Formular verfügen. Dieses benötigt mindestens eine FS_INDEX-Komponente zur Speicherung der Produkt-ID.

Formular

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

Der Ausgabekanal erlaubt den Zugriff auf die FS_INDEX-Komponente und die in ihr referenzierten Produkte. Jedes Element der FS_INDEX-Komponente bietet Methoden, um Informationen über das jeweilige Produkt abzufragen und diese beispielsweise auszugeben.

Nutzung eines Produkts im Ausgabekanal

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

Tabelle 2. Methoden
Name	Parameter	Rückgabewert	Beschreibung
get	name: String	String	Liefert den Wert des genannten Attributes oder `null`, wenn das Attribut nicht existiert.
getValueMap		Map<String, String>	Liefert eine Map aller Attribute des Produkts zurück.

Eine Übersicht der zur Verfügung stehenden Attribute und ihrer Bezeichner bietet die Beschreibung des ProductWsDTOs in der Cmswebservices API.

Einige Attribute, wie z. B. name, besitzen sprachabhängige Werte. Aus diesem Grund muss ihr Bezeichner für die Abfrage erweitert werden: name_de.

Der Code-Ausschnitt Nutzung des Produktcodes innerhalb einer Produkt-Verweisvorlage zeigt beispielhaft die Benutzung des Produktcodes zur Verlinkung eines Produkts. Er verwendet verschiedene Eingabekomponenten aus den Projekteinstellungen, die folgendermaßen definiert sind:

Tabelle 3. Eingabekomponenten innerhalb der Projekteinstellungen
Name	Wert (beispielhaft)	Beschreibung
ps_hybrisAcceleratorName	yb2bacceleratorstorefront	Name der Commerce Cloud-Storefront
ps_hybrisSiteName	powertools	Name der Commerce Cloud-Site

Nutzung des Produktcodes innerhalb einer Produkt-Verweisvorlage

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

Die Referenzierung von Kategorien erfordert Anpassungen im Formular und Ausgabekanal einer Vorlage.

4.7.1. Formular

Für die Referenzierung von Kategorien in einer Vorlage muss diese zunächst über ein entsprechendes Formular verfügen. Dieses benötigt mindestens eine FS_INDEX-Komponente zur Speicherung der Kategorie-ID.

Formular

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

Der Ausgabekanal erlaubt den Zugriff auf die FS_INDEX-Komponente und die in ihr referenzierten Kategorien. Jedes Element der FS_INDEX-Komponente ist ein Objekt vom Typ com.espirit.moddev.contentconnect.sap.module.catalogs.productcatalogs.Category, welches im JavaDoc der in der Auslieferung enthaltenen API beschrieben wird.

Eine beispielhafte Nutzung einer Kategorie im Ausgabekanal zeigt der folgende Code-Ausschnitt:

Nutzung einer Kategorie im Ausgabekanal

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

4.8. Generierung der Navigationsstruktur

Das FirstSpirit Connect-Modul erlaubt die Generierung der Navigationsstruktur in FirstSpirit. Die Generierung erfolgt als JSON-Dokument in den CaaS.

Um diese Funktion zu nutzen, wird eine Navigationsfunktion benötigt, die das JSON-Dokument generiert. Der folgende Code-Ausschnitt zeigt ein Beispiel für eine solche Funktion, die alle Elemente im Strukturordner contentpages berücksichtigt.

Navigationsfunktion

<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$]}

Die Ausführung dieser Funktion erfordert eine Seite sowie eine auf ihr basierende Seitenreferenz, die ebenfalls anzulegen ist.

Die Seitenreferenz muss zwingend den Referenznamen main_navigation besitzen.

Die gezeigte Navigationsfunktion erfasst nur die Startseite einer Menüebene. Falls alle Seitenreferenzen erfasst werden sollen, ist eine entsprechende Anpassung der Funktion erforderlich.

Das FirstSpirit Connect-Modul startet bei jeder Erstellung, Änderung, Verschiebung und Löschung eines Elements im Strukturbereich eine Generierung der Seitenreferenz main_navigation. Dadurch spiegelt das Dokument im CaaS stets die aktuelle Navigationsstruktur in FirstSpirit wider. Die CaaS-Konfiguration für den übergeordneten Strukturordner bestimmt dabei, in welcher Collection das Dokument abgelegt wird. Der Name des im CaaS gespeicherten Dokuments lautet main_navigation_<LANGUAGE>.

4.9. Auswahl eines Produkts oder einer Kategorie

Das Modul stellt im ContentCreator einen Produkt- und einen Kategorie-Report bereit. Diese dienen der Darstellung der aus der Commerce Cloud stammenden Produkte und Kategorien. Über das Suchfeld der Reports können die Listen gefiltert werden.

Abbildung 18. Produkte und Kategorien im Report

Die CMS WebServices-Schnittstelle der Commerce Cloud ermöglicht keine Suche in einer anderen Sprache. Eine Suche nach Kategorien oder Produkten in den entsprechenden Reports muss daher mit Suchbegriffen in der Standardsprache der Commerce Cloud erfolgen.

4.10. Einbinden eines Produkts oder einer Kategorie

Ein Produkt oder eine Kategorie kann per Drag and Drop aus dem Report heraus einer FS_INDEX-Eingabekomponente im Bearbeitungsdialog hinzugefügt werden. Alternativ besitzt die Komponente einen Hinzufügen-Button, der einen Auswahldialog öffnet. In ihm sind ebenfalls alle zur Verfügung stehenden Produkte bzw. Kategorien aufgelistet.

Die Speicherung der Auswahl geschieht über den gleichnamigen Button.

4.11. Aufruf einer Inhaltsseite oder Produkt-/Kategoriedetailseite

Inhaltsseiten sowie Produkt- und Kategoriedetailseiten lassen sich sowohl über die Navigation des Shops als auch über den Produkte-, Kategorie- bzw. Suchreport aufrufen. Der Aufruf im Report erfolgt jeweils per Klick auf eine dieser Seiten. Dadurch sind auch Detailseiten abfragbar, die noch nicht in der Hauptnavigation des Shops verfügbar sind.

Zur Bestimmung der URLs von Produkt- und Kategoriedetailseiten verwenden die Reports die URLs aus den Feldern PDP URL und CDP URL, die während der Konfiguration der Projektkomponente anzugeben sind.
Inhaltsseiten können spezifische URLs besitzen, die sich optional während der Definition der Template Mappings festlegen lassen. Verfügt eine Inhaltsseite über keine spezifische URL, wird für sie stattdessen die allgemeine Contentpage URL verwendet. Enthält eines der genannten Felder eine relative URL, wird sie basierend auf der URL der aktuellen Shop-Seite zu einer absoluten URL aufgelöst.

Der Produktreport zeigt alle Produkte des konfigurierten Produktkatalogs an. Dies bedeutet, dass die Detailseiten aller Produkte des Katalogs aufrufbar sein müssen. Um dies sicher zu stellen, muss die Konfiguration der FlexibleSearch Restrictions überprüft werden.

4.12. Bearbeitung von Seitenattributen

Im Gegensatz zur Auslieferung der Inhalte verlagert sich deren Erstellung und Pflege von der Commerce Cloud nach FirstSpirit. FirstSpirit stellt dafür den ContentCreator zur Verfügung. In ihm lassen sich sowohl neue als auch bestehende Commerce Cloud-Seiten darstellen und bearbeiten.

Die Pflege spezifischer Seitenattribute, wie beispielsweise einer SEO-URL, setzt für alle Commerce Cloud-Inhaltsseiten eine entsprechende FirstSpirit-Seitenvorlage voraus. Diese besitzt ein Formular aus verschiedenen Eingabekomponenten, die der Speicherung der Attribute dienen und im ContentCreator über den Bearbeitungsdialog der aktuell angezeigten Seite editierbar sind. Der Bearbeitungsdialog ist über den Eintrag Open page settings im Bereich zur Anzeige der Seiteninformationen aufrufbar, der sich beim Überfahren des Seitenstatus' mit dem Cursor öffnet.

Abbildung 19. Bearbeitung von Seitenattributen

5. Rechtliche Hinweise

FirstSpirit Connect for SAP Commerce Cloud ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.
Für die Verwendung des Moduls gilt gegenüber dem Anwender nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

6. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.

7. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.

Dokumentation

für die Version 25.4.0
Aktualisiert: 16.04.2025

Unternehmen

Kontakt

Crownpeak Technology GmbH
Stockholmer Allee 24
44269 Dortmund, DE
+49 231 477 77 0
Kontaktieren Sie uns