ContentConnect

For Salesforce Commerce Cloud

Crownpeak Technology GmbH

18.11.2022
Inhaltsverzeichnis

1. Einleitung

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

Im restlichen Dokument wird anstelle von “Salesforce Commerce Cloud” die Kurzform “Commerce Cloud” benutzt. Damit ist immer ausschließlich die Salesforce Commerce Cloud gemeint.

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 in Form von XML-Dateien und Medien an die Commerce Cloud übermittelt.
Commerce Cloud-seitige Komponenten
Diese Komponenten dienen der Verarbeitung der in FirstSpirit erstellten redaktionellen Inhalte. Die Commerce Cloud integriert diese Daten in den Shop und überführt sie in den Live-Stand.

Ein Bestandteil der Auslieferung des ContentConnect-Moduls ist ein StarterPackage inklusive eines Referenzprojekts und verschiedener Cartridge-Komponenten, die zu großen Teilen auf der Storefront Reference Architecture aufsetzen. 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. Dabei erfolgt die Beschreibung sowohl aus Redakteurssicht als auch aus der Sicht eines FirstSpirit-Entwicklers.

1.1. Funktionsumfang

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

  • Erstellung nativer Commerce Cloud-Inhalte mit FirstSpirit
  • Zugriff auf Produktinformationen über die Open Commerce API (OC API)
  • gleichzeitige Darstellung von Shop-Elementen und redaktionellen Inhalten in der FirstSpirit-Vorschau
  • Übertragung von Inhalten in den Commerce Cloud Storage über WebDAV

Die entsprechenden Funktionalitäten werden mit der Installation und Konfiguration des Moduls sowohl im SiteArchitect als auch 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 überträgt die Informationen in den Live-Stand.

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:

    • ContentConnect-Modul
    • WebDAV-Modul
    • JSTL-Modul
  • Commerce Cloud-Instanzen (Staging & Production)
Architektur
Abbildung 1. Architektur


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

  1. Die Erstellung und Bearbeitung der redaktionellen Inhalte findet FirstSpirit-seitig statt. Die Inhalte ersetzen Platzhalter im HTML-Gerüst, das ebenso wie die auf der Live-Seite angezeigten Produkte jedoch aus der Commerce Cloud stammt. Es wird per https nach FirstSpirit übertragen, wo es für die vollständige Darstellung der Vorschau benötigt wird. Für Produkt- und Kategorieseiten erfordet dies außerdem die Kommunikation mit Controllern, die Teil der ausgelieferten Cartridge sind. Die Übergabe der Produkte nach FirstSpirit erfolgt über die OC API-Schnittstelle der Commerce Cloud Staging Instanz. Diese Schnittstelle wird außerdem genutzt, um verschiedene Aktionen in der Commerce Cloud zu starten.
  2. Alle in FirstSpirit vorgenommenen inhaltlichen Änderungen werden im Rahmen eines Deployments per WebDAV der Commerce Cloud Staging Instanz bereitgestellt. Sie werden in Form von Medien und XML-Dateien in verschiedenen WebDAV-Verzeichnissen abgelegt. Von dort werden sie über Jobs, die durch eine Aktion des Deployments angestoßen werden, in die Library der Commerce Cloud Staging Instanz importiert.
  3. Diese Library wird zusammen mit dem Produktkatalog auf die produktive Commerce Cloud Instanz repliziert. Für die Commerce Cloud ergibt sich somit bei der Auslieferung redaktioneller Inhalte in den Live-Stand keinerlei Unterschied.

Die Commerce Cloud stellt somit die Hauptkomponente dieser Architektur dar. Sie liefert die in FirstSpirit erstellten bzw. gepflegten Inhalte an die Kunden aus und stellt sämtliche Shop-Funktionalitäten zur Verfügung. 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. Konzept

Das ContentConnect-Modul bietet die Möglichkeit, redaktionelle Inhalte FirstSpirit-seitig zu pflegen und diese anschließend per Deployment in die Commerce Cloud zu übertragen. Dafür muss die Verarbeitung von Inhalten in beiden Systemen aufeinander abgestimmt und zueinander kompatibel sein. Die nachfolgenden Unterkapitel beschreiben das zugrunde liegende Konzept, mit dem diese Kompatibilität erreicht wird.

1.3.1. Seiten

Ähnlich wie in FirstSpirit basieren Seiten in der Commerce Cloud auf einer Struktur unterschiedlicher Komponenten. Um redaktionelle Inhalte zwischen den beiden Systemen austauschen zu können, müssen diese Komponenten aufeinander abgestimmt sein.

Innerhalb des in der Auslieferung enthaltenen Referenzprojekts ContentConnect Reference Project werden die Slots durch die Inhaltsbereiche einer Seitenvorlage repräsentiert. Ihnen können Absätze hinzugefügt werden, die jeweils einem Asset entsprechen und je nach Anwendungsfall zusätzlich eine Slot-Konfiguration besitzen (vgl. Abbildung Page Rendering). Mithilfe dieser Konfigurationen lässt sich beispielsweise definieren, welche Zielgruppe den entsprechenden Inhalt sehen darf oder in welchem Zeitraum dieser sichtbar ist. Jede Slot-Konfiguration verweist auf exakt ein Asset.

Mit FirstSpirit lassen sich somit Assets generieren, die über Slots in einer Seite dargestellt werden.

Page Rendering
Abbildung 2. Page Rendering


1.3.2. Vorschau

Die mit dem ContentConnect-Modul realisierte Integration sieht FirstSpirit-seitig lediglich die Erzeugung und Pflege der redaktionellen Inhalte sowie ihre Publizierung in Form von Assets vor. Die Commerce Cloud bestimmt jedoch weiterhin das Rahmenwerk einer Seite, deren Slots die generierten Assets einbinden.

Für die Darstellung der Vorschau einer Seite ermittelt FirstSpirit daher ihre aktuelle Ansicht im Commerce Cloud Storefront und lädt das HTML herunter. Die darin enthaltenen Slots sind durch HTML-Kommentare eindeutig gekennzeichnet. FirstSpirit ersetzt diese Bereiche durch die entsprechenden redaktionellen Inhalte und stellt das Resultat in der Vorschau dar.

1.3.3. Velocity

Alternativ zu dem zuvor beschriebenen Slot-basierten Ansatz bietet Salesforce die Content Integration API (CI API) an. Sie ermöglicht die Salesforce-seitige Auswertung von Velocity-Fragmenten und damit eine einfache Realisierung von Geschäftslogiken auf einer Seite. Des Weiteren bietet sie Redakteuren eine höhere Kontrolle über das Seitenlayout als beim Slot-basierten Ansatz. Die Velocity-Fragmente inklusive der Geschäftslogik werden dabei innerhalb von FirstSpirit gepflegt.

1.3.4. Sprachen

Sowohl Salesforce- als auch FirstSpirit-seitig erfolgt die Pflege redaktioneller Inhalte in verschiedenen Sprachen. Für die Integration ist daher eine Zuordnung zwischen den Sprachen beider Systeme notwendig. Zu diesem Zweck wurde für die im Referenzprojekt verwendeten Sprachen eine Konvention bezüglich ihrer in FirstSpirit definierten Abkürzung getroffen. Diese orientiert sich an den in Salesforce bestehenden Sprachen und sieht vor, jede Abkürzung nach dem Schema SPRACHKÜRZEL_LÄNDERKÜRZEL zu benennen (vgl. Abbildung Sprachen). Dabei entspricht das Sprachkürzel dem ISO-639-Standard und das Länderkürzel dem ISO-3166-Standard.

Darüber hinaus wird im Projekt gewährleistet, dass die FirstSpirit-Mastersprache der Defaultsprache in Salesforce zugeordnet wird.

Sprachen
Abbildung 3. Sprachen


Dieser Sachverhalt wird in den Kapiteln Generierung sowie Homepage genauer behandelt.

1.3.5. Generierung & Deployment

Die Übertragung der FirstSpirit-seitig erstellten Inhalte in den Live-Stand geschieht durch die Commerce Cloud. Ihr müssen die Inhalte daher bereitgestellt werden, was in Form zweier, während der Generierung erzeugter XML-Dateien erfolgt. Während eine dieser Dateien alle im FirstSpirit-Projekt erzeugten Slot-Konfigurationen enthält, beinhaltet die zweite alle Assets.

Das WebDAV-Deployment überträgt die beiden XML-Dateien zusammen mit den generierten Medien in die Commerce Cloud und legt sie im Commerce Cloud Storage ab. Von dort werden sie über einen Job Schedule, der durch den FirstSpirit-Auftrag angestoßen wird, importiert.

1.3.6. Löschen

Die Inhalte eines FirstSpirit-Projekts können jederzeit im Rahmen des gewöhnlichen Redaktionsprozesses verändert oder gelöscht werden. Diese Änderungen müssen Salesforce-seitig übernommen werden. Genauso wie die Übertragung neuer Inhalte erfolgt auch ihre Löschung per Deployment.

Allen Assets und Slot-Konfigurationen wird zu Beginn jeder Vollgenerierung ein aktueller Zeitstempel hinzugefügt. Ihr Zeitstempel divergiert somit von den Zeitstempeln der Inhalte, die Salesforce-seitig noch bestehen, im FirstSpirit-Projekt jedoch bereits gelöscht sind. Die letzte Aktion des Generierungsauftrags ermittelt die Assets und Slot-Konfigurationen mit solch einem veralteten Zeitstempel und veranlasst ihre Löschung.

1.4. Technische Voraussetzungen

Das Modul ContentConnect besitzt die folgenden technischen Voraussetzungen:

  • FirstSpirit-Version: FirstSpirit (Isolated- oder Legacy-Mode) ab 2020-01
  • E-Commerce-Shopsystem Commerce Cloud
  • Storefront Reference Architecture in der Version 6.2.0
  • Crownpeak LINK Cartridges int_espirit, int_espirit_sfra bzw. int_espirit_sg Version 22.1.0
  • Open Commerce API in der Version 22.10 oder höher
  • aktuelle JSTL-Version (Diese wird mit dem JSTL-Modul bereitgestellt)
  • Java 11 oder höher

1.5. Wichtige Hinweise

Dieses Kapitel enthält Hinweise, die bei der Verwendung des ContentConnect-Moduls zu beachten sind.

1.5.1. Content Asset ID

Content Assets, die in FirstSpirit angelegt werden, bekommen von FirstSpirit eine eindeutige ID. Wird in der Commerce Cloud ein Content Asset mit exakt derselben ID angelegt, wird dieses beim Veröffentlichen von FirstSpirit überschrieben.

2. Komponenten

ContentConnect besteht aus verschiedenen Komponenten. Die Funktionalität dieser Komponenten wird in den nachfolgenden Unterkapiteln erläutert.

2.1. ContentConnect-Modul

Das ContentConnect-Modul ist die Hauptkomponente der Verbindung zwischen FirstSpirit und der Commerce Cloud. Es hat eine maßgebliche Bedeutung für den bidirektionalen Datenaustausch zwischen dem FirstSpirit-Server und der Commerce Cloud.

Sowohl im SiteArchitect als auch im ContentCreator wird durch das Modul ein Report bereitgestellt. Dieser Report dient der Darstellung der Produktinformationen aus der Commerce Cloud. Stößt ein Redakteur eine entsprechende Abfrage an, ermittelt das Modul die gewünschten Daten und übergibt sie dem Report. Die zurückgelieferten Daten können anschließend für die Erstellung und Pflege redaktioneller Inhalte weiterverwendet werden.

Wird nach der Erstellung der Inhalte eine Generierung ausgeführt, fasst das Modul sie in Form zweier XML-Dateien zusammen. Die Dateien werden dann vom WebDAV-Modul in den Commerce Cloud Storage übermittelt. Aus diesem liest die Commerce Cloud die Daten aus und überträgt sie in den Live-Stand.

Das ContentConnect-Modul stellt eine API bereit, mit der projektspezifische Funktionalitäten implementiert werden können. Weitere Informationen können der mitgelieferten Javadoc-Dokumentation entnommen werden.

2.2. WebDAV-Modul

Die Erstellung und Bearbeitung der redaktionellen Inhalte findet FirstSpirit-seitig statt. Ihre Übertragung in den Live-Stand erfolgt hingegen durch die Commerce Cloud. Ihr müssen die Inhalte daher bereitgestellt werden. Dafür erstellt das ContentConnect-Modul im Rahmen eines Deployments jeweils eine XML-Datei für die Library und die Slot-Konfiguration. Sie müssen zusammen mit den referenzierten Medien an die Commerce Cloud übergeben werden.

Diese Aufgabe übernimmt das WebDAV-Modul. Es fungiert als Bindeglied zwischen FirstSpirit und der Commerce Cloud und legt die Daten im Commerce Cloud Storage ab. Aus diesem werden sie von der Commerce Cloud ausgelesen.

2.3. JSTL-Modul

Innerhalb des Referenzprojekt ist für die Vorschau bestimmter Seiten die Verwendung von JSTL erforderlich. Dies ermöglicht das JSTL-Modul. Es muss jedoch nur dann auf dem FirstSpirit-Server installiert werden, wenn JSTL noch nicht anderweitig auf dem Server eingebunden ist.

2.4. Commerce Cloud Cartridges

Die Auslieferung enthält die drei Cartridges int_espirit, int_espirit_sfra und int_espirit_sg. Sie unterstützen alle Locales und unterliegen diesbezüglich keinerlei Restriktion.

int_espirit
Die Cartridge int_espirit enthält Skripte, die in den anderen beiden Cartridges genutzt werden. Die bereitgestellten Funktionen dienen z. B. der Abbildung von Commerce Cloud Render Templates auf FirstSpirit-Seitenvorlagen, um damit das Anlegen von Kategorie- und Produktseiten zu ermöglichen (vgl. Product Page Template Mapping, Category Page Template Mappings und Kategorie- und Produktseiten).
int_espirit_sfra

Die Cartridge int_espirit_sfra überschreibt einige Vorlagen der Storefront Reference Architecture, um die FirstSpirit-seitige Vorschau zu ermöglichen. Außerdem enthält die Cartridge die folgenden Controller:

  • Common: Der Controller Common stellt die Standardkomponenten eines Salesforce-Shops als einzelne Widgets bereit.
  • Content: Der Controller Content nimmt die in FirstSpirit gepflegten Velocity-Fragmente entgegen und gibt das daraus gerenderte HTML zurück.
  • CategorySearchResult: Der Controller CategorySearchResult ermittelt die Produkte einer Unterkategorie und stellt diese als ein separates Widget bereit.
  • Product: Der Controller Product stellt die Widgets einer Produkt-Detailseite zur Verfügung und steuert die Anzeige der Produkt-Detailseite im Live-Stand.
  • RenderTemplate: Der Controller RenderTemplate ermittelt für ein gegebenes Produkt oder eine gegebene Kategorie das Commerce Cloud Render Template. Er verwendet dabei die Möglichkeiten der Storefront Reference Architecture und greift auf die Funktionen der Cartridge int_espirit zurück.
  • Search: Der Controller Search ermöglicht die Darstellung von FirstSpirit Kategorie-Detailseiten im Live-Stand.
int_espirit_sg
Für Shops, die nicht auf der Storefront Reference Architecture basieren, enthält die Cartridge int_espirit_sg eine entsprechende Implementierung des Controllers RenderTemplate.

3. Commerce Cloud - Installation und Konfiguration

Für die Verwendung der Funktionalitäten des ContentConnect-Moduls ist die Installation und Konfiguration unterschiedlicher Komponenten erforderlich. Die folgenden Unterkapitel erläutern die notwendigen Schritte für die Installation und Konfiguration der Commerce Cloud-seitigen Komponenten. Die zugehörige Import-Datei befindet sich im Ordner data.

3.1. Einrichtung der Cartridges

In der Auslieferung sind drei Cartridges enthalten, die zunächst in die Commerce Cloud übertragen werden müssen. Verschiedene Methoden hierzu beschreibt die Commerce Cloud-Dokumentation unter Salesforce B2C Commerce 22.10Developing Your SiteDevelopment ComponentsCartridges.

Anschließend muss die Cartridge int_espirit allen Sites, die FirstSpirit-Inhalte empfangen sollen, hinzugefügt werden. Entsprechende Instruktionen finden sich in der Commerce Cloud-Dokumentation unter Salesforce B2C Commerce 22.10Developing Your SiteDevelopment ComponentsRegister a Cartridge. Sites, die auf der Storefront Reference Architecture aufsetzen und in FirstSpirit gepflegt werden, benötigen in ihrem Cartridge-Pfad außerdem int_espirit_sfra. Basiert eine Site hingegen auf SiteGenesis, muss ihr Cartridge-Pfad um int_espirit_sg ergänzt werden.

Die drei Cartridges unterstützen alle Locales und unterliegen diesbezüglich keinerlei Restriktion.

3.2. Import der zip-Datei importExamples

Für die Einrichtung der Job Schedules sowie der Content-Bereinigung und für die Slot-Konfigurationen sind die verschiedene Dateien erforderlich, die in der Datei importExamples.zip gespeichert sind. Die zip-Datei ist innerhalb der Auslieferung im Verzeichnis metadata enthalten und muss in der Commerce Cloud bereitgestellt werden. Dafür ist sie über die Seite AdministrationSite DevelopmentSite Import & Export zu importieren. Die in ihr enthalten Dateien setzen unterschiedliche Konfigurationsschritte voraus, die in den entsprechenden Unterkapiteln im Detail erläutert werden.

3.3. Einrichtung der Job Schedules

Um die von FirstSpirit generierten Inhalte und Slot-Konfigurationen in die Commerce Cloud zu importieren, ist für jede Site ein Job Schedule in der Commerce Cloud anzulegen. Die Auslieferung enthält daher im Verzeichnis metadata die zip-Datei importExamples.zip, die wie zuvor beschrieben einen Import in die Commerce Cloud erfordert.

Die mit der zip-Datei importierten Jobs besitzen standardmäßig die Job-IDs FirstSpirit-Import-RefArch und FirstSpirit-Import-RefArchGlobal. Die ID stellt die Eindeutigkeit der Jobs für die verschiedenen Sites sicher und lässt sich auf der Seite AdministrationOperationsJobs beliebig anpassen. Es wird empfohlen, die ID der jeweiligen Site in die zugehörige Job-ID aufzunehmen, um die Eindeutigkeit zu gewährleisten.

Die in der Datei konfigurierten Job Schedules bestehen aus drei Job Steps vom Typ Import Content, Import Content Slots und Rebuild Search Index. Alle drei Job Steps besitzen initial den Scope RefArch bzw. RefArchGlobal, der auf die entsprechende Site umzustellen ist. Darüber hinaus definieren sie unterschiedliche Parameter, deren Default-Werte größtenteils beibehalten werden können. Lediglich die Parameter WorkingFolder und FileNamePattern sind projektspezifisch anzupassen. Der Bearbeitungsdialog öffnet sich per Klick auf den Namen des Job Steps.

WorkingFolder
Der Parameter WorkingFolder gibt - relativ zum IMPEX-Verzeichnis - den Pfad zu dem Verzeichnis an, das die von FirstSpirit generierten XML-Dateien enthält. Sein Wert muss für beide Job Steps identisch sein.
FileNamePattern
Der Parameter definiert den Namen der von FirstSpirit generierten XML-Dateien. Im Fall des Job Steps ImportContent muss er den Wert fs_import_library.xml und für den Job Step ImportContentSlots den Wert fs_import_slot_configuration.xml besitzen.

Allgemeine Informationen zur Erzeugung von Job Schedules sind in der Commerce Cloud-Dokumentation im Kapitel Administering Your OrganizationJobsCreating Jobs enthalten.

Die drei Job Steps und ihre Parameter sind in der Commerce Cloud Dokumentation in den Kapiteln ImportContent, ImportContentSlots und SearchReindex beschrieben.

3.4. Einrichtung der Content-Bereinigung

Um von FirstSpirit verwaltete Assets und Slot-Konfigurationen, die innerhalb von FirstSpirit gelöscht wurden, auch aus der Commerce Cloud zu löschen, sind folgende Schritte zu befolgen:

Import der benutzerdefinierten System-Objekt-Attribute
Zur Persistierung von Zeitstempeln der Generierung benutzt die Content-Bereinigung innerhalb von Assets und Slot-Konfigurationen das benutzerdefinierte Attribut fsGenerationTime. Dieses muss den System-Objekten (Content und Slot-Konfigurationen) zunächst hinzugefügt werden. Für das Anlegen der benutzerdefinierten System-Objekt-Attribute muss die zip-Datei importExamples.zip in der Commerce Cloud verfügbar sein. Sie ist innerhalb des Verzeichnisses metadata gespeichert, das in der Auslieferung enthalten ist. Ihre Bereitstellung erfolgt über den zuvor beschriebenen Importprozess.

Anlegen weiterer Custom-Attributes für Assets
Die Menge der zu löschenden Content Assets kann auf Basis beliebiger weiterer Custom-Attributes zusätzlich eingeschränkt werden. Ist dies gewünscht, sind entsprechende Attribute für Content Assets anzulegen. Eine Beschreibung hierzu findet sich in der Commerce Cloud-Dokumentation unter dem Punkt Salesforce B2C Commerce 22.10Administering Your OrganisationBusiness ObjectsCreating Custom Attributes for Business Objects

Erzeugung von Search-Refinements für Assets
Für das neu erzeugte Attribut fsGenerationTime und die zusätzlich angelegten Custom-Attributes ist außerdem ein Commerce Cloud Search Refinement anzulegen. Dies beschreibt die Commerce Cloud-Dokumentation unter dem Punkt Merchandising Your SiteContent AssetsWorking with Content AssetsCreating Content Search Refinements.

Nach dem Import der benutzerdefinierten System-Object-Attribute und dem Anlegen des Search-Refinements ist es notwendig die Search Indexes der Site neu zu bauen.

3.5. OC API Settings

Unter anderem für die Reports und das Deployment wird die OC API eingesetzt. Für die verwendete Client ID müssen daher Salesforce-seitig die entsprechenden Rechte gesetzt werden.

Die im folgenden beschhriebenen Anpassungen an den Rechten können auch den separaten Dateien Shop OCAPI-Settings und Data OCAPI-Settings entnommen werden.

Die verwendete Client ID benötigt Rechte zur Ausführung von GET-Anfragen über die ShopAPI auf folgende Ressourcen. Diese müssen je nach Anwendungsfall im globalen oder Site-spezifischen Kontext gesetzt werden.

  • /products/*/variations
  • /products/*
  • /product_search/variations

Bei Verwendung der Content-Bereinigung außerdem:

  • /content_search

Zusätzlich werden Rechte zur Ausführung von GET-, POST und DELETE-Anfragen über die DataAPI für folgende Ressourcen vorausgesetzt. Sie sind ausschließlich im globalen Kontext zu definieren.

  • /catalogs (nur GET)
  • /catalogs/*/categories (nur GET)
  • /jobs/*/executions (GET & POST)
  • /jobs/*/executions/* (nur GET)

Bei Verwendung der Content-Bereinigung außerdem:

  • /sites/*/slot_configuration_search (nur POST)
  • /libraries/*/content/* (nur DELETE)
  • /sites/*/slots/*/slot_configurations/* (nur DELETE)

Die Verwendung der Sorting Rules erfordert darüber hinaus die folgende Definition:

  • /sites/*/sorting_rule_search (nur POST)

Sollen optional Workflows zur Löschung von Library folder und Folder assignments verwendet werden, so sind Rechte zur Ausführung von DELETE-Anfragen über die DataAPI auf folgende Ressourcen notwendig:

  • /libraries/*/folders/*
  • /libraries/*/folder_assignments/*/*

3.6. Slot-Konfigurationen

Durch die Vorlagen der Cartridge int_espirit_sfra werden der Site neue Slots hinzugefügt. Die Auslieferung stellt dafür die zip-Datei importExamples.zip mit Slot-Konfigurationen für diese Slots zur Verfügung. Sie ist innerhalb des Verzeichnisses metadata gespeichert, das in der Auslieferung enthalten ist. Die Bereitstellung der zip-Datei in der Commerce Cloud erfolgt über den zuvor beschriebenen Importprozess.

4. FirstSpirit - Installation und Konfiguration

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

4.1. Installation der Module

Die ContentConnect-Auslieferung enthält drei Module, die auf dem FirstSpirit-Server hinzugefügt werden müssen. Öffnen Sie für die Installation der Module den ServerManager und wählen Sie den Bereich Server-EigenschaftenModule.

Modulverwaltung in den Server-Eigenschaften
Abbildung 4. Modulverwaltung in den Server-Eigenschaften


Im Hauptpanel ist eine Liste aller auf dem FirstSpirit-Server installierten Module zu sehen. Wählen Sie nach dem Klicken auf Installieren nacheinander zunächst die mitgelieferte contentconnect-fsm-<Versionsnummer>.fsm und anschließend die WebDavDeployment-<Versionsnummer>.fsm sowie die jstl.fsm aus. Bestätigen Sie die Auswahl jeweils mit Öffnen. Nach der erfolgreichen Installation wurden der Liste die Ordner ContentConnect, WebDavDeployment und JSTL hinzugefügt, von denen jeder Alle Rechte erhalten muss.

Das JSTL-Modul muss nur dann installiert werden, wenn JSTL noch nicht anderweitig auf dem Server eingebunden ist.

Nach jeder Installation oder Aktualisierung eines Moduls ist ein Neustart des FirstSpirit-Servers notwendig.

4.2. WebDAV-Verwendung mit https

Um den WebDAV-Server mit https statt http zu verwenden, ist grundsätzlich keine zusätzliche Konfiguration notwendig. Für https wird jedoch im Allgemeinen eine lokale vom Unternehmen verwaltete Zertifizierungsstelle verwendet. Dessen Zertifikat muss inklusive der gesamten Kette bis zum Zertifikat des WebDAV-Servers der JVM des FirstSpirit-Servers zur Verfügung gestellt werden.

Die JVM erwartet diese öffentlichen Zertifikate als PKCS12- oder JKS-Datei.

Importieren Sie die öffentlichen Root- oder Zwischenzertifikate über das folgende Kommando in eine JKS-Datei und beantworten Sie die Frage, ob dem Zertifikat vertraut werden soll, mit Ja Dieser Vorgang muss für jedes Zertifikat wiederholt werden.

keytool -import -file cert1.crt -keystore truststore.jks –storepass changeit

Kopieren Sie den erzeugten Trust Store in das Verzeichnis firstspirit5conf ihres FirstSpirit-Servers und fügen Sie die folgenden Zeilen der Datei firstspirit5conffs-wrapper.conf hinzu.

wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks
wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit
wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS

Die Parameter müssen über einen Neustart des FirstSpirit-Servers aktiviert werden.

Sollte der WebDAV-Server eine wechselseitige SSL-Authentifizierung erwarten, muss über die folgenden Aufrufe zunächst ein Client-Zertifikat erstellt und signiert werden.

openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr

Die Datei request.csr wird an die Zertifizierungsstelle versandt, die mit der Datei cert.crt antwortet. Der private Schlüssel, das öffentliche Zertifikat und das Zertifikat der Zertifizierungsstelle müssen anschließend in einem von der JVM zu lesenden Key Store zusammengefasst werden.

cd firstspirit5/conf
openssl pkcs12 -export -in public.crt -inkey private.key \
-out clientcert.p12 -CAfile authority.crt

Falls die Zertifikatskette aus einem oder mehreren Zwischenzertifikaten besteht, können diese via keytool importiert werden.

keytool -import -file intermediate1.crt -trustcacerts \
-keystore clientcert.p12 -storepass changeit

Der Key Store lässt sich über das Hinzufügen der folgenden Zeilen in die firstspirit5conffs-wrapper.conf an die JVM des FirstSpirit-Servers übergeben.

wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12
wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit
wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12

4.3. Projekt-Import

Ein Bestandteil des in der Auslieferung enthaltenen StarterPackages ist das Referenzprojekt ContentConnect Reference Project, das auf dem FirstSpirit-Server zu installieren ist. Öffnen Sie dafür im ServerManager den Import-Dialog über den Menüpunkt ProjektImportieren und wählen Sie über den Button Lokal die Datei ContentConnectReferenceProject.tar.gz aus ihrem lokalen Dateisystem aus. Vergeben Sie anschließend einen Projektnamen sowie eine Beschreibung und bestätigen Sie den Import mit Ja. Nach der erfolgreichen Installation wurde das Projekt der Liste im Hauptpanel hinzugefügt (vgl. Abbildung Importiertes Projekt im ServerManager).

Importiertes Projekt im ServerManager
Abbildung 5. Importiertes Projekt im ServerManager


Neben den Standardgruppen Everyone und Administrators existieren im Referenzprojekt vier weitere Benutzergruppen: Editors, ChiefEditors, Developers und ProjectAdmins. Diese Gruppen besitzen verschiedene Rechte, die entsprechend der Aufgaben der jeweiligen Gruppe gewählt wurden. Benutzer außerhalb dieser Gruppen sind standardmäßig nicht berechtigt das Referenzprojekt zu verwenden.

4.4. Konfiguration der Projekt-Komponente

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

Öffnen Sie für die Konfiguration der Projekt-Komponente den ServerManager und wählen Sie den Bereich Projekt-EigenschaftenProjekt-Komponenten. Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Selektieren Sie den Eintrag ContentConnect Project Configuration und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren (vgl. Abbildung Konfigurationsdialog der Projekt-Komponente).

Die nachfolgende Konfiguration wird von den Modul-Services verwendet. Jegliche Änderung an der Konfiguration erfordert einen Neustart des Services und aller laufenden Clients. Andernfalls wird die entsprechende Änderung weder von den Services noch von den Clients übernommen.

Konfigurationsdialog der Projekt-Komponente
Abbildung 6. Konfigurationsdialog der Projekt-Komponente


Base URL

In dem Dialog wird zunächst die Base URL erfasst, die sich aus der URL der Commerce Cloud-Instanz und der ID der verwendeten Site ergibt:

https://<SUBDOMAIN INSTANCE>.demandware.net/s/<SITE ID>

Basierend auf dieser Struktur ist stets eine eindeutige Verbindung zwischen dem FirstSpirit-Projekt und der Commerce Cloud-Site sichergestellt.

Bei der Base URL handelt es sich um ein Pflichtfeld.

Um Zertifikatsprobleme zu vermeiden, ist sicherzustellen, dass die Subdomain keine Punkte im Namen enthält.

Storefront Hostname

Dieses Konfigurationsfeld ist optional und sollte nur ausgefüllt werden, wenn sich der Hostname der Storefront Base URL in den Projekteinstellungen vom Hostname der in diesem Dialog konfigurierten Base URL unterscheidet. In diesem Fall ist hier der Hostname inklusive Protokoll der Storefront Base URL einzutragen.

Beispiel:

https://<DIFFERENT SUBDOMAIN INSTANCE>.demandware.net/

Client ID
Die Client ID ist ebenfalls ein Pflichtfeld. Sie wird für die Verwendung der Open Commerce Shop API benötigt.

Die Client ID und die Base URL sind für die Verbindung zwischen der Commerce Cloud und FirstSpirit zwingend erforderlich. Ist eine der beiden Angaben fehlerhaft oder nicht vorhanden, wird der jeweilige Report für die Produktsuche in beiden FirstSpirit-Clients ausgeblendet.

Password
Die Komponenten der ContentConnect-API setzen eine passwortbasierte Authentifizierung gegenüber der Commerce Cloud voraus. Aus diesem Grund ist zusätzlich zur Client ID ein Passwort erforderlich, das während der Registrierung des API Clients bei der Commerce Cloud definiert wird.
Refinements
In diesem Konfigurationsfeld sind Refinements definiert, die der Verfeinerung der Produktsuche dienen. Die Angabe der Refinements erfolgt in Form einer kommaseparierten Liste von Schlüssel-Wert-Paaren.

Es werden maximal die ersten neun angegebenen Schlüssel-Wert-Paare genutzt, da die Commerce Cloud nicht mehr als neun Refinements akzeptiert.

Das Format der Werte der Schlüssel-Wert-Paare entspricht dem von der Commerce Cloud erwarteten Format für Refinement-Werte. Es können also mehrere Werte sowie Wertmengen für ein Refinement angegeben werden:

  • cgid=new-arrivals|electronics
  • price=(0..100)

Die Filterung nach einer Kategorie geschieht ebenfalls über ein Refinement, weshalb zwei Sonderfälle zu beachten sind:

Im ersten Fall

  • wird in der Produktsuche nach einer Kategorie gefiltert und
  • die Konfiguration enthält neun Refinement-Definitionen,
  • von denen keine das Kategorie-Refinement cgid ist.

In diesem Fall liegen insgesamt zehn Refinement-Definitionen vor, was unzulässig ist. Deshalb wird ein Refinement aus der Konfiguration ignoriert, um stattdessen die Kategorie-Filterung zu ermöglich.

Im zweiten Fall

  • wird in der Produktsuche ebenfalls nach einer Kategorie gefiltert und
  • die Konfiguration enthält das Kategorie-Refinement cgid.

In diesem Fall gibt es eine doppelte Definition für das Kategorie-Refinement cgid: eine aus der Modulkonfiguration und eine aus der Produktsuche, wobei letztere verwendet wird. Der Wert aus der Konfiguration dient dann als Default-Wert und kann vom Redakteur überschrieben werden.

Locale
Die Locale gibt den Sprachkontext des aktuellen Projekts an. Erlaubt ist die Angabe maximal einer ID einer aktiven Locale, die für Storefront-Anfragen in der oben konfigurierten Site erlaubt ist. Falls das Feld leer bleibt, wird der Parameter locale in Storefront-Anfragen nicht verwendet.
Auth User
Ist die Beschränkung des Zugriffs in der Commerce Cloud aktiviert, muss in diesem Feld der User storefront angegeben werden.
Auth Password
Die Angabe in diesem Feld entspricht dem zum storefront User gehörenden Passwort.
Product Page Template Mapping

Über den Produkte-Report können komfortabel Produktseiten erstellt werden, die im Referenzprojekt die Seitenvorlage Product Detail Page verwenden. Um dies zu ermöglichen, erlaubt dieses Konfigurationsfeld die Abbildung von Salesforce Render Templates auf FirstSpirit-Seitenvorlagen. Dabei gelten folgende Regeln:

  • Das Feld enthält entweder gar keinen Inhalt oder ein oder mehrere Mappings.
  • Bleibt das Feld leer, ist die Verwendung von Produktseiten im Projekt deaktiviert.
  • Mappings werden durch eine kommaseparierte Liste angegeben <mapping>,<mapping>
  • jedes Mapping ist folgendermaßen aufgebaut: <isml_template>:<fs_template>
  • Um für alle ISML-Templates, die kein explizites Mapping besitzen, eine Seitenvorlage zu konfigurieren, ist folgende Form zu verwenden: default:<fs_template>
Default Folder (Product Pages)
Für eine neue Produktseite muss bekannt sein, wo diese in der Struktur einzubinden ist. Dafür ist an dieser Stelle der Referenzname des Struktur-Ordners Product Pages angegeben. In ihm werden innerhalb des Referenzprojekts alle neuen Produktseiten erstellt. Bleibt das Feld leer, muss die Auswahl einer Menüebene durch den Redakteur erfolgen.
Editable Folder (Product Pages)
Mit dieser Checkbox lässt sich festlegen, ob die im Feld Default Folder (Product Pages) getroffene Auswahl durch einen Redakteur geändert werden kann. Initial ist die Funktion aktiviert. Ist sie deaktiviert, wird die entsprechende Eingabekomponente im Dialog zur Erstellung einer Kategorie- oder Produktseite versteckt. Der Redakteur besitzt in diesem Fall keine Möglichkeit, den Menüpunkt einer neu erstellten Kategorie- oder Produktseite zu wählen bzw. zu ändern.

Das Feld Default Folder (Product Pages) und die Checkbox Editable Folder (Product Pages) werden ignoriert, wenn das Feld Product Page Template Mapping leer ist. Ist jedoch ein Mapping definiert, muss zwingend der Referenzname eines Struktur-Ordners angegeben oder die Checkbox aktiviert sein. Andernfalls ist die Erstellung neuer Produktseiten aufgrund der fehlenden Zuordnung zu einer Menüebene nicht möglich und es treten Fehler auf.

Category Page Template Mappings

Über dieses Konfigurationsfeld kann das Mapping von Seitenvorlagen für das Anlegen von Kategorieseiten über den Kategorie-Report, konfiguriert werden. Dabei gelten folgende Regeln:

  • Das Feld enthält entweder gar keinen Inhalt oder ein oder mehrere Mappings.
  • Bleibt das Feld leer, ist die Verwendung von Kategorieseiten im Projekt deaktiviert.
  • Mappings werden durch eine kommaseparierte Liste angegeben <mapping>,<mapping>
  • Jedes Mapping ist folgendermaßen aufgebaut: <isml_template>:<fs_template>[:fallback_category]
  • Der dritte Bestandteil des Mappings ist optional und dient der Angabe einer Fallback-Kategorie für Kategorieseiten, die auf dem angegebenen ISML-Template basieren
  • Um für alle ISML-Templates, die kein explizites Mapping besitzen, eine Seitenvorlage und optional eine Fallback-Kategorie zu konfigurieren, ist folgende Form zu verwenden: default:<fs_template>[:fallback_category]

Kategorien können innerhalb der Commerce Cloud als offline markiert werden. Diese Offline-Kategorien werden über den Storefront nicht ausgeliefert, wodurch für sie auch keine Vorschau erzeugt werden kann. Damit es dennoch möglich ist, über den FirstSpirit-Report auch Kategorieseiten für Offline-Kategorien zu pflegen, müssen für die dazugehörigen ISML-Templates Fallback-Kategorien angegeben werden. Innerhalb der Vorschau einer Seite einer Offline-Kategorie wird diese dann durch die konfigurierte Fallback-Kategorie ersetzt.

Wir empfehlen, separate FirstSpirit-Vorlagen für Produktseiten und Kategorieseiten zu verwenden.

Default Folder (Category Pages)
Äquivalent zu den Produktseiten muss auch für jede neue Kategorieseite bekannt sein, wo diese in der Struktur einzubinden ist. Dafür ist an dieser Stelle der Referenzname des Struktur-Ordners Category Pages angegeben. In ihm werden innerhalb des Referenzprojekts alle neuen Kategorieseiten erstellt. Bleibt das Feld leer, muss die Auswahl einer Menüebene durch den Redakteur erfolgen.
Editable Folder (Category Pages)
Äquivalent zur Checkbox Editable Folder (Product Pages) kann an dieser Stelle festgelegt werden, ob Redakteure die im Feld Default Folder (Category Pages) getroffene Auswahl ändern können. Initial ist die Funktion aktiviert. Ist sie deaktiviert, wird die Auswahlmöglichkeit im Dialog zur Erstellung einer Kategorieseite versteckt. Der Redakteur besitzt in diesem Fall keine Möglichkeit, den Menüpunkt für eine neue Seite zu wählen bzw. zu ändern.

Das Feld Default Folder (Category Pages) und die Checkbox Editable Folder (Category Pages) werden ignoriert, wenn das Feld Category Page Template Mappings leer ist. Ist jedoch ein Mapping definiert, muss zwingend der Referenzname eines Struktur-Ordners angegeben oder die Checkbox aktiviert sein. Andernfalls ist die Erstellung neuer Kategorieseiten aufgrund der fehlenden Zuordnung zu einer Menüebene nicht möglich und es treten Fehler auf.

Template Instantiation Script Uid
Über dieses Konfigurationsfeld kann optional ein Skript gewählt werden, das vor und nach der Anlage von Kategorie- oder Produktseiten ausgeführt wird. Das angegebene Skript create_sfcc_item_wizard dient der Ausführung projektspezifischer Aktionen, die für die Vorschauerzeugung notwendig sind. Im Referenzprojekt markiert es die erzeugte Kategorie- oder Produktseite für alle Sprachen als übersetzt.

Es ist zu beachten, dass nur der Code aus dem HTML-Kanal des Skripts ausgeführt wird.

View Type Priority
Die Bilder der aus der Commerce Cloud stammenden Produkte werden stets in verschiedenen Größen bereitgestellt. Es kann jedoch nicht vorausgesetzt werden, dass für jede Größe ein Bild hinterlegt wurde. Aus diesem Grund kann an dieser Stelle kommasepariert die View Type Priority der zu berücksichtigenden Bildgrößen definiert werden.

Im auf der Abbildung Konfigurationsdialog der Projekt-Komponente dargestellten Fall wird für jedes Produkt das zugehörige mittelgroße (medium) Bild ermittelt und bei dessen Existenz verwendet. Liegt jedoch kein mittelgroßes Bild vor, wird anschließend das große (large) bzw. gegebenenfalls das kleine (small) Bild abgerufen.

Da das Feld keine Pflichteingabe erwartet, kann es vorkommen, dass keine Priorität definiert wird und das Feld leer bleibt. In diesem Fall werden Suchergebnisse für eine Produktabfrage ohne ein Bild dargestellt.

Image Service Base URL
Die Commerce Cloud stellt einen sogenannten Dynamic Imaging Service bereit. Ist seine Verwendung gewünscht, ist an dieser Stelle die URL des Images Services in der Form http[s]://<image server host name> anzugeben. Produktbilder werden dann über den Image Service abgerufen.

Die Angabe der Image Service Base URL ist optional. Wird das Feld jedoch mit einer URL gefüllt, so muss diese Eingabe fehlerfrei sein. Andernfalls wird der jeweilige Report für die Produktsuche in beiden FirstSpirit-Clients ausgeblendet. Dies gilt auch dann, wenn die Client ID und die Base URL korrekt sind (siehe oben).

Die Filterung nach Kategorien unterscheidet sich je nach verwendetem Report. Im Report für die Produktsuche ist eine Filterung über alle Kategorien möglich. Im Report für die Kategoriesuche ist die Filterung hingegen nur über die Toplevel-Kategorien möglich.

Show Category Report

Über diese Checkbox kann die Einblendung des Kategoriereports gesteuert werden. Standardmäßig ist dieser deaktiviert und somit nur der Report für die Produktsuche aktiv.

Kategorie-Report
Abbildung 7. Kategorie-Report


Test Configuration
Über den Button Test Configuration lassen sich die eingetragenen Eingaben überprüfen. Dabei werden neben der Client ID, der Base URL und - wenn vorhanden - der Image Service Base URL auch die Konfigurationen für die Produkt- und Kategorieseiten berücksichtigt.

4.5. Hinzufügen der Web-Komponenten

Für die Vorschau und den ContentCreator werden zwei Web-Komponenten benötigt, die dem mitgelieferten Referenzprojekt bereits hinzugefügt sind. Sie müssen jedoch noch auf einem aktiven Webserver installiert werden. Öffnen Sie hierfür den ServerManager und wählen Sie den Bereich Projekt-EigenschaftenWeb-Komponenten.

Innerhalb des Hauptpanels sind verschiedene Registerkarten zu sehen, in denen jeweils eine Liste der bereits vorhandenen Web-Komponenten sichtbar ist. Diese Liste enthält sowohl für die Vorschau als auch für den ContentCreator die folgenden Einträge (vgl. Abbildung Web-Komponenten in den Projekt-Eigenschaften):

  • ContentConnect Web Component
  • FS_JSTL_WebApp

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

Detaillierte Informationen zum Hinzufügen von Web-Komponenten finden Sie in der FirstSpirit Dokumentation für Administratoren.

Web-Komponenten in den Projekt-Eigenschaften
Abbildung 8. Web-Komponenten in den Projekt-Eigenschaften


4.6. Konfiguration der Web-Komponente

Teil der Web-Komponente des ContentConnect-Moduls sind der Preview Proxy und der Preview Filter. Beide Komponenten lassen sich über die web.xml konfigurieren und sind in den beiden folgenden Kapiteln näher beschrieben.

4.6.1. Preview Proxy

Treten bei der Vorschau Probleme mit Cross-Origin Requests aufgrund der Same-Origin Policy moderner Webserver auf, so können diese durch den Einsatz des im ContentConnect-Modul enthaltenen Preview Proxys behoben werden.

Dazu sind die Aufrufe der betroffenen Ressourcen über den Preview Proxy zu leiten. Wie dies im Projekt bewerkstelligt wird, erläutert das Kapitel Vorschau.

Der Preview Proxy ist über die web.xml mit folgendem Parameter konfigurierbar:

ParameterDefaultwertBeschreibung

connection.keepalive

60

Die Dauer der Aufrechterhaltung einer Verbindung innerhalb des Preview Proxys in Sekunden. Ein zu hoher Wert kann zu Problemen bei der Abfrage von Ressourcen führen.

Beispiel

Ein beispielhafter Ausschnitt aus der web.xml, in dem der Parameter des Preview Proxys konfiguriert ist und außerdem der vorkonfigurierte URL-Pfad angepasst wurde, könnte wie folgt aussehen:

Beispielhafte web.xml. 

<servlet>
    <servlet-name>ContentConnectPreviewProxy</servlet-name>
    <servlet-class>com.espirit.moddev.demandware.preview.proxy.ProxyServlet</servlet-class>
    <load-on-startup>0</load-on-startup>
    <init-param>
      <param-name>connection.keepalive</param-name>
      <param-value>120</param-value>
   </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>ContentConnectPreviewProxy</servlet-name>
    <url-pattern>/assets/*</url-pattern>
</servlet-mapping>

4.6.2. Preview Filter

Der ContentConnect Preview Filter ermittelt für die Darstellung einer Seite in der FirstSpirit-Vorschau die notwendigen Informationen. Im Slot-basierten Ansatz identifiziert er dafür die richtige Storefront-URL, lädt anhand dieser das HTML herunter und ersetzt die darin enthaltenen Slots durch die entsprechenden redaktionellen Inhalte. Bei Verwendung der CI API lässt er hingegen die in FirstSpirit gepflegten Velocity-Fragmente Salesforce-seitig auswerten und stellt das jeweilige Ergebnis an der entsprechenden Stelle auf der Seite in der FirstSpirit-Vorschau dar.

Für die Durchführung dieser Schritte benötigt er einige Informationen, die über diverse Parameter in der web.xml der hinzugefügten Web-Komponente (sowohl für die Vorschau als auch für den ContentCreator) konfigurierbar sind. Diese beziehen sich auf unterschiedliche Aspekte, die sich in vier Gruppen unterteilen lassen.

Die web.xml der im Tab Vorschau hinzugefügten Web-Komponente erfordert die Anpassung des Parameters dispatcher. Standardmäßig besitzt die web.xml den Wert FORWARD für diesen Parameter. Im Fall der Vorschau im SiteArchitect benötigt er jedoch den Wert REQUEST und ist entsprechend zu ersetzen.

Anpassung in der web.xml für die Vorschau im SiteArchitect. 

<filter-mapping>
   <filter-name>ContentConnectPreviewFilter</filter-name>
   <url-pattern>/*</url-pattern>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>

Darüber hinaus ist eine Konfiguration der einzelnen Parameter ausschließlich dann notwendig, wenn ihre Defaultwerte nicht den projektspezifischen Gegebenheiten entsprechen.

Storefront URL Parameter

Wie bereits beschrieben ermittelt der Preview Filter sowohl im Slot-basierten Ansatz als auch bei der Verwendung der CI API Salesforce-seitig die notwendigen Informationen und stellt sie in der FirstSpirit-Vorschau dar. Dafür ist eine projektspezifische Storefront-URL erforderlich. Da diese in den Projekteinstellungen gepflegt wird, benötigt der Preview Filter zur Abfrage die Angabe der zugehörigen Eingabekomponente.

ParameterDefaultwertBeschreibung

storefront.url.baseUrlFormField

ps_storefrontUrlBaseUrl

Die Eingabekomponente für die Angabe der Basis-URL des Storefronts, die um den Page Type und die ID des anzuzeigenden Elements (z.B. Produkt-, Kategorie- oder Asset-ID) erweitert wird. Sie wird in den Projekteinstellungen gepflegt.

Die Syntax für die Storefront Base URL kann im Kapitel Salesforce B2C Commerce 22.10Merchandising Your SiteSearch Engine OptimizationURL SyntaxSalesforce B2C Commerce URL Syntax Without SEO der Salesforce Commerce Cloud Dokumentation nachgeschlagen werden.

Als Wert der Eingabekomponente ps_storefrontUrlBaseUrl darf innerhalb der Projekteinstellungen lediglich der Teil bis zur Locale und nicht die gesamte URL angegeben werden.

Bsp.: https://www.mystore.com/on/demandware.store/​Sites-YourShopHere-Site/

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

Storefront Crop Marks Parameter

Die in den redaktionellen Inhalten enthaltenen Platzhalter bestehen jeweils aus einem Start- sowie End-Kommentar und besitzen standardmäßig das Format <!-- CMS-<IDENTIFIER>-START --> bzw. <!-- CMS-<IDENTIFIER>-END -->. Über ein Toggle in den Projekteinstellungen, das bei Bedarf hinzuzufügen ist, kann jedoch die Verwendung individueller Affixe aktiviert werden. In diesem Fall werden die Defaultwerte überschrieben und stattdessen die spezifischen Präfixe bzw. Suffixe verwendet. Um dem Preview Filter den Zugriff auf diese Informationen zu ermöglichen, benötigt er die Angabe der zugehörigen Eingabekomponenten.

ParameterDefaultwertBeschreibung

storefront.cropMarks. customAffixes.enabledFormField

ps_storefrontCropMarksCustomAffixesEnabled

Das Toggle in den Projekteinstellungen zur De-/Aktivierung der Verwendung individueller Affixe.

storefront.cropMarks. opening.prefixFormField

ps_storefrontCropMarksOpeningPrefix

Die Eingabekomponente in den Projekteinstellungen zur Angabe eines Präfixes für den Start-Kommentar.

storefront.cropMarks. opening.suffixFormField

ps_storefrontCropMarksOpeningSuffix

Die Eingabekomponente in den Projekteinstellungen zur Angabe eines Suffixes für den Start-Kommentar.

storefront.cropMarks. closing.prefixFormField

ps_storefrontCropMarksClosingPrefix

Die Eingabekomponente in den Projekteinstellungen zur Angabe eines Präfixes für den End-Kommentar.

storefront.cropMarks. closing.suffixFormField

ps_storefrontCropMarksClosingSuffix

Die Eingabekomponente in den Projekteinstellungen zur Angabe eines Suffixes für den End-Kommentar.

Storefront Protection Parameter

Es besteht die Möglichkeit, die Verbindung zur Commerce Cloud über eine Authentifizierung zu schützen. Sie kann Salesforce-seitig de-/aktiviert werden und muss FirstSpirit-seitig über das entsprechende Toggle in den Projekteinstellungen übernommen werden. Im Fall der Aktivierung sind zusätzlich die benötigten Zugangsdaten anzugeben. Der Preview Filter muss auf diese Informationen zugreifen können und benötigt daher die Angabe der zugehörigen Eingabekomponenten.

ParameterDefaultwertBeschreibung

storefront.protection.enabledFormField

ps_storefrontProtectionEnabled

Die Eingabekomponte in den Projekteinstellungen zur De-/Aktivierung der Authentifizierung für die Storefront-URL.

storefront.protection.userFormField

ps_storefrontProtectionUser

Die Eingabekomponente in den Projekteinstellungen für die Erfassung des Storefront-Benutzers.

storefront.protection.passwordFormField

ps_storefrontProtectionPassword

Die Eingabekomponente in der Projekteinstellungen für das Passwort des Storefront-Benutzers.

Storefront Downloader Parameter

Zusätzlich zu den übrigen Parametern, die hauptsächlich der Ermittlung der richtigen Storefront-URL dienen, muss es im Slot-basierten Ansatz möglich sein, das Verhalten des Preview Filters während des Herunterladens des HTMLs der entsprechenden Seite zu steuern. Dafür besitzt er verschiedene Parameter, die in den Projekteinstellungen pflegbar sind. Der Preview Filter muss auf diese Informationen zugreifen können und benötigt daher die Angabe der zugehörigen Eingabekomponenten.

Die Storefront Downloader Parameter werden zur Initialisierung des Filters im Slot-basierten Ansatz benutzt. Aus diesem Grund besitzen sie für den Fall einer fehlenden oder leeren Eingabekomponente einen festen Fallback-Wert.

ParameterDefaultwertBeschreibung

storefront.downloader.maxConnections

ps_storefrontDownloaderMaxConnections

Die Eingabekomponente in den Projekteinstellungen zur Angabe der maximalen Anzahl parallel zulässiger Verbindungen zum Storefront.

Der Fallback-Wert beträgt 100.

storefront.downloader.socketTimeout

ps_storefrontDownloaderSocketTimeout

Die Eingabekomponente in den Projekteinstellungen zur Angabe der Zeitspanne (in Millisekunden), in der eine Antwort vom Storefront erwartet wird.

Der Fallback-Wert beträgt 10000.

storefront.downloader.retryCount

ps_storefrontDownloaderRetryCount

Die Eingabekomponente in den Projekteinstellungen zur Angabe der maximalen Anzahl der Verbindungsversuche.

Der Fallback-Wert beträgt 3.

Die Verwendung der folgenden beiden Parameter wird nur in Ausnahmefällen empfohlen, da diese die Zertifikatsprüfung für https-Anfragen umgehen. Dies kann notwendig sein, wenn Zertifikatsfehler eine Anzeige der Vorschau verhindern und das Problem nicht serverseitig behoben werden kann.

ParameterDefaultwertBeschreibung

storefront.downloader.certificatesCheck

true

Das Setzen dieses Parameters auf false deaktiviert Zertifikatsprüfungen für https-Anfragen. Dies hat zur Folge, dass zunächst alle https-Anfragen zur Anzeige der Vorschau blockiert werden. Um Anfragen gegen einzelne Seiten zu erlauben, ist der Hostname der entsprechenden Seiten in die sslWhitelist einzutragen.

storefront.downloader.sslWhitelist

leer

Über die sslWhitelist werden bei deaktivierter Zertifikatsprüfung die Hostnamen gepflegt, die von der Blockierung ausgenommen werden sollen. Mehrere Hostnamen sind als kommaseparierte Liste einzutragen.

Storefront Cache Parameter

Das vom Preview Filter heruntergeladene HTML Slot-basierter Seiten wird in einem Cache vorgehalten, so dass es nicht bei jedem Aufruf neu von der Commerce Cloud bezogen werden muss. Ein solcher Cache existiert sitzungsübergreifend für jedes Projekt auf dem FirstSpirit-Server. Dieser Cache besitzt einige Parameter, die in den Projekteinstellungen pflegbar sind. Der Preview Filter muss auf diese Informationen zugreifen können und benötigt daher die Angabe der zugehörigen Eingabekomponenten.

Wie die Downloader Parameter werden auch die Cache Parameter zur Initialisierung des Filters im Slot-basierten Ansatz benutzt. Aus diesem Grund besitzen sie für den Fall einer fehlenden oder leeren Eingabekomponente einen festen Fallback-Wert.

ParameterDefaultwertBeschreibung

storefront.cache.maxEntries

ps_storefrontDownloaderMaxCacheEntries

Die Eingabekomponente in den Projekteinstellungen zur Angabe der maximalen Anzahl der Elemente im Cache.

Der Fallback-Wert beträgt 500.

storefront.cache.refreshAfterWrite

ps_storefrontCacheRefreshAfterWrite

Die Eingabekomponente in den Projekteinstellungen zur Angabe der Zeitspanne (in Stunden), bis ein Element im Cache als veraltet markiert wird.

Der Fallback-Wert beträgt 1.

Wenn ein Eintrag als veraltet markiert ist, wird er bei der nächsten Anfrage asynchron neu von der Commerce Cloud bezogen. Bis dieser Vorgang abgeschlossen ist, liefert der Cache den veralteten Eintrag, so dass keine Verzögerung entsteht.

storefront.cache.expireAfterWrite

ps_storefrontCacheExpireAfterWrite

Die Eingabekomponente in den Projekteinstellungen zur Angabe der Zeitspanne (in Stunden), bis ein Element im Cache als entfernbar markiert wird.

Der Fallback-Wert beträgt 24.

Wenn ein Eintrag als entfernbar markiert ist, kann er von neuen Elementen aus dem Cache verdrängt werden. Wird ein Element nach seiner Verdrängung erneut angefragt, muss es neu von der Commerce Cloud bezogen werden.

storefront.cache.excludePatterns

ps_storefrontCacheExcludePatterns

Die Eingabekomponente in den Projekteinstellungen zur Angabe von Storefront URLs, die nicht im Cache vorgehalten werden sollen. Die Angabe der URLs erfolgt in Form einer Liste von regulären Ausdrücken.

Der Fallback-Wert ist eine leere Liste.

Jedes Element der Listenkomponente muss zwingend ein Textfeld mit dem Namen st_storefrontCacheExcludePattern besitzen, welches den regulären Ausdruck enthält.

Beispiel

Ein beispielhafter Ausschnitt aus der web.xml, in der zwei Parameter des Preview Filters konfiguriert sind, könnte wie folgt aussehen:

Beispielhafte web.xml. 

<filter>
   <filter-name>ContentConnectPreviewFilter</filter-name>
   <filter-class>com.espirit.moddev.demandware.preview.PreviewFilter</filter-class>
   <init-param>
      <param-name>storefront.downloader.socketTimeout</param-name>
      <param-value>ps_myCustomStorefrontDownloaderSocketTimeout</param-value>
   </init-param>
   <init-param>
      <param-name>storefront.downloader.retryCount</param-name>
      <param-value>ps_myCustomStorefrontDownloaderRetryCount</param-value>
   </init-param>
</filter>

4.7. Auflösungen

Das Referenzprojekt ContentConnect Reference Project besitzt unterschiedliche Absätze, mit denen sich auf den verschiedenen Seiten Bilder einbinden lassen. Die Bilder sollen durch den Redakteur auf einen bestimmten Bildausschnitt zugeschnitten werden können. Diese Funktionalität wird über die Angabe einer Auflösung aktiviert.

Angabe der Auflösung. 

$CMS_REF(st_picture, resolution:"RESOLUTION")$

Für das Referenzprojekt werden die Auflösungen BANNER, SLIDE, GRID_ELEMENT_HIGH, GRID_ELEMENT_WIDE, GRID_ELEMENT_SQUARE, IMAGE_MAP, ARTICLE_TEASER_IMAGE und TECHNOLOGY_IMAGE benötigt. Sie sind bereits innerhalb des ServerManagers im Bereich Projekt-EigenschaftenAuflösungen angelegt und an den entsprechenden Stellen in den Absätzen angegeben.

Auflösungen
Abbildung 9. Auflösungen


4.8. Deployment-Auftrag

Für die Übermittlung der in FirstSpirit erstellten Inhalte in den Commerce Cloud Storage besitzt das mitgelieferte Referenzprojekt einen Auftrag, der die folgenden Aktionen enthält (vgl. Abbildung Aktionen des Generierungsauftrags). Eine Beschreibung der einzelnen Aktionen erfolgt in den nachfolgenden Unterkapiteln.

Weitere Informationen zur Erstellung eines Auftrags sind in der FirstSpirit Dokumentation für Administratoren zu finden.

Aktionen des Generierungsauftrags
Abbildung 10. Aktionen des Generierungsauftrags


4.8.1. Initialize SFCC Deployment

Im ersten Schritt erfolgt die Initialisierung des Deployments. Dies beinhaltet die Einrichtung der Content-Bereinigung, während der ein der Generierung vorausgehender Zeitstempel erzeugt wird. Diesen Zeitstempel verwendet die Cleanup-Aktion im letzten Schritt des Auftrags zur Löschung veralteter Assets und Slot-Konfigurationen. Der Auftrag enthält dafür die Aktion Salesforce Commerce Cloud Initializer:

Auftragsaktion
Abbildung 11. Auftragsaktion


Für die Verwendung der Content-Bereinigung muss die Initialisierung zwingend die erste Aktion des Auftrags sein. Andernfalls kommt es zu Inkonsistenzen im Datenbestand.

4.8.2. Content Preparation - Vollgenerierung

Für das Deployment der für die Commerce Cloud relevanten Inhalte sind diese zunächst aus dem Projekt zu ermitteln. Dafür muss eine Vollgenerierung durchgeführt werden, die alle referenzierten Medien in der richtigen Auflösung generiert. Außerdem erzeugt sie die in den Projekteinstellungen initialisierten XML-Kollektoren und füllt sie anhand der in den Vorlagen enthaltenen xmlCollector-Aufrufe.

Der Auftrag besitzt daher die Generierungsaktion Content Preparation, in deren Eigenschaften die folgenden Optionen aktiviert sind (vgl. Abbildung Aktion Content Preparation):

  • Vollgenerierung durchführen
  • Generierungsverzeichnis vorher leeren
  • Medien im Generierungsverzeichnis erzeugen

Das definierte Präfix für absolute Pfade /firstspirit wird in der Aktion WebDAV-Deployment benötigt.

Der Einsatz des WebDAV-Moduls ist nur in Verbindung mit dem Standard-URL-Creator möglich. Für die Pfaderzeugung ist daher der Eintrag Default URLs ausgewählt, der an dieser Stelle zwingend notwendig ist.

In der Registerkarte Erweitert sind außerdem die Vorlagensätze aller im Projekt vorhandenen Sprachen selektiert. Des Weiteren wurde die Variable dwre_xmlGeneration hinzugefügt, die den Wert false enthält. Sie wird in den nachfolgenden XML Import File-Aktionen auf den Wert true gesetzt und stellt sicher, dass die Erzeugung der XML-Dateien für die Slot-Konfigurationen und die Assets erst nach der Generierung erfolgt. Die Erzeugung der XML-Datei wird durch die im Projekt enthaltene XML-Vorlage gesteuert.

Aktion Content Preparation
Abbildung 12. Aktion Content Preparation


4.8.3. XML Import File - Teilgenerierungen

Alle an die Commerce Cloud übermittelten Daten werden von dieser in Form von XML-Dateien erwartet. Aus diesem Grund müssen die während der Vollgenerierung ermittelten Informationen aus den erzeugten XML-Kollektoren ausgelesen werden. Sie sollen stattdessen in eine jeweils zu erstellende XML-Datei geschrieben werden.

Der Auftrag verfügt daher für jeden in den Projekteinstellungen initialisierten XML-Kollektor eine weitere Generierungsaktion. Im Gegensatz zur Aktion Content Preparation handelt es sich bei ihnen jedoch um Teilgenerierungen. In ihren Eigenschaften ist daher die Option Teilgenerierung durchführen für folgende Startpunkte aktiviert. Als Startpunkt dient jeweils eine der auf der XML-Vorlage basierenden Seitenreferenzen (vgl. Abbildung Teilgenerierung).

In der Registerkarte Erweitert jeder dieser Aktionen wurde außerdem die Variable dwre_xmlGeneration hinzugefügt, die den Wert true enthält. Zusammen mit dem jeweils ausgewählten Startknoten stellt sie sicher, dass die selektierte Seitenreferenz erst zu diesem Zeitpunkt generiert wird. Somit liegen alle benötigten Informationen für die Erstellung der XML-Datei bereits vor und es können keine Lücken auftreten. Die Erzeugung der XML-Datei wird durch die im Projekt enthaltene XML-Vorlage gesteuert.

Teilgenerierung
Abbildung 13. Teilgenerierung


4.8.4. WebDAV-Deployment

Die mit den Teilgenerierungen erzeugten XML-Dateien müssen anschließend an die Commerce Cloud übermittelt werden. Die Publizierung erfolgt über eine Skript-Aktion, für die in ihren Eigenschaften folgende Parameter definiert sind:

Eigenschaften
Abbildung 14. Eigenschaften


url

Die URL gibt den Host und den Pfad auf dem WebDAV-Server an. Sie besitzt immer die folgende Struktur:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/…​/<PREFIX>/<SITE ID>

Der Pfad entspricht dem Ort, an dem die jeweilige XML-Datei während des Imports erwartet wird. Er muss auf ein bereits existierendes Verzeichnis verweisen.

Des Weiteren muss das Präfix dem Präfix für absolute Pfade der Vollgenerierung entsprechen.

user

Für die Übertragung der Daten wird ein technischer User benötigt, der zur Nutzung der WebDAV-Schnittstelle berechtigt ist. Er muss Schreibrechte besitzen und wird an dieser Stelle mit seinem Namen angegeben.

Unter Administering Your OrganizationPermissions, Users, and RolesRoles and PermissionsCreate a Role enthält die Salesforce-Dokumentation Informationen, wie diese Rechte zu setzen sind.

password
Für den zuvor angegebenen User wird zusätzlich die Angabe des Passworts benötigt.

Der technische Benutzer unterliegt den durch die Commerce Cloud definierten Passwort-Bestimmungen. Diese erfordern eine mindestens vierteljährliche Änderung des Passworts. Der Wert des Parameters muss in jedem dieser Fälle zwingend angepasst werden.

mediaurl

Der bei der Generierung erzeugte Medien-Ordner und sein Inhalt müssen in ein separates Verzeichnis übertragen werden, um der Commerce Cloud den Import zu ermöglichen. Dieses Verzeichnis ist über den Parameter mediaurl festgelegt. Die mediaurl besitzt immer die folgende Struktur:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Libraries/<SITE ID|LIBRARY ID>/default/<PREFIX>

Die mediaurl muss auf ein existierendes Verzeichnis zeigen.

Wie schon bei der URL muss das Präfix der mediaurl dem Präfix für absolute Pfade der Vollgenerierung entsprechen.

Bei der Benutzung einer privaten Library ist die Angabe der Site ID anstelle der Library ID im Pfad erforderlich.

srcprefixdir
Soll nur ein bestimmtes Verzeichnis an die Commerce Cloud übertragen werden, kann es über den optionalen Parameter srcprefixdir relativ zum Root-Knoten des Generierungsverzeichnisses angegeben werden. Wird der Parameter nicht definiert oder für ihn kein Wert gespeichert, wird das gesamte Generierungsverzeichnis übertragen.
purge
Dieser Parameter ist optional und kann nur den Wert true oder false besitzen. Der Wert true bewirkt, dass alle Dateien und Verzeichnisse unterhalb der angegebenen URL vor dem Start der Übertragung gelöscht werden. Besitzt der Parameter den Wert false oder keinen Wert, bleiben alle bestehenden Dateien und Verzeichnisse unterhalb der angegebenen URL bestehen. Neue Daten werden entweder hinzugefügt oder im Fall bereits existierender Daten überschreiben sie diese.

Das WebDav-Deployment darf nicht im Fehlerfall ausgeführt werden.

4.8.5. Trigger SFCC Import Job Schedule

Nach der Publizierung der erzeugten XML-Dateien durch das WebDAV-Deployment wird der angelegte Job Schedule ausgeführt. Dieser löst Salesforce-seitig den Import der generierten Inhalte und Slot-Konfigurationen in die Commerce Cloud aus. Das ContentConnect-Modul stellt zu diesem Zweck die Auftragsaktion Salesforce Commerce Cloud Importer zur Verfügung:

Auftragsaktion
Abbildung 15. Auftragsaktion


Die Aktion stellt einen Konfigurationsdialog bereit, in dem neben einem frei zu vergebenen Namen zwei Parameter zu definieren sind:

Parameter der Auftragsaktion
Abbildung 16. Parameter der Auftragsaktion


Import Job ID
Dieses Feld enthält die ID des angelegten Job Schedules.
Timeout
Der Wert in diesem Feld stellt die Zeitspanne in Sekunden dar, in der sekündlich der Status des Job Schedules abgefragt wird. Falls der Job Schedule in der angegebenen Zeitspanne nicht beendet wurde, wird diese Auftragsaktion als fehlerhaft gekennzeichnet. Der Defaultwert beträgt 10 Sekunden.

Da der Salesforce Commerce Cloud Importer ein erfolgreiches WebDAV-Deployment voraussetzt, darf auch dieser nicht im Fehlerfall ausgeführt werden.

4.8.6. Salesforce Commerce Cloud Cleanup

Nach der Ausführung des angelegten Job Schedules wird die Content-Bereinigung ausgeführt. Dabei werden alle veralteten Assets und Slot-Konfigurationen über die OC API abgefragt und anschließend gelöscht. Hierfür stellt das ContentConnect-Modul die Auftragsaktion Salesforce Commerce Cloud Cleanup zur Verfügung:

Auftragsaktion
Abbildung 17. Auftragsaktion


Neben einem frei zu vergebenden Namen für diese Auftragsaktion enthält der dazugehörige Konfigurationsdialog folgende Parameter:

Parameter der Auftragsaktion
Abbildung 18. Parameter der Auftragsaktion


Use different site
Die Content-Bereinigung nutzt eine Commerce Cloud-Site für die Suche nach den zu löschenden Content Assets und Slot-Konfigurationen. Die Checkbox Use different site erlaubt die Nutzung der Content-Bereinigung für eine andere als die konfigurierte Site.
Site Id
Falls die Checkbox Use different site aktiv ist, ist in diesem Feld die Commerce Cloud-Site anzugeben, die bei der Content-Bereinigung genutzt werden soll.
Content asset cleanupEnabled
Diese Checkbox erlaubt die De-/Aktivierung der Content-Bereinigung von Assets.
Library Id
In diesem Feld ist die ID der Content Library anzugeben, aus der Content Assets gelöscht werden. Im Fall einer privaten Libary entspricht die Library ID der Site ID.
Additional refinement(s)

In diesem Feld können Attributnamen und -werte zur weiteren Filterung der zu löschenden Content Assets angegeben werden. Die Angabe muss die folgende Form besitzen:

ATTRIBUTE_NAME=ATTRIBUTE_VALUE [; ATTRIBUTE_NAME=ATTRIBUTE_VALUE] ...

Die Attributwerte können folgende Parameter enthalten:

ParameterErsetzung durch

${projectId}

Die ID des generierten FirstSpirit-Projekts

${projectName}

Der Name des generierten FirstSpirit-Projekts

Die angegebenen Attribute müssen als Custom-Attributes in der Commerce Cloud existieren und über die FirstSpirit-Generierung mit Werten befüllt worden sein, bevor die hier beschriebene Filterung genutzt werden kann.

Slot configuration cleanupEnabled
Diese Checkbox erlaubt die De-/Aktivierung der Content-Bereinigung von Slot-Konfigurationen.
Filter query

Dieses Feld dient der Filterung der zu löschenden Slot-Konfigurationen. Die Angabe eines Filters erfolgt als Query-Dokument im JSON-Format. Innerhalb der Abfrage können die Parameter des Felds Additional refinement(s) genutzt werden, wie das folgende Beispiel einer TextQuery veranschaulicht:

"text_query": {
    "fields": ["c_fsProjectId"],
    "search_phrase": "${projectId}"
}

Falls das Feld Filter query leer bleibt, nutzt das ContentConnect-Modul eine MatchAllQuery, wodurch die zu löschenden Slot-Konfigurationen nicht weiter gefiltert werden.

Um Inkonsistenzen im Datenbestand bzw. einen Datenverlust zu vermeiden, muss die Aktion Salesforce Commerce Cloud Cleanup der letzten Aktion des Auftrags entsprechen. Aus demselben Grund setzt die Content-Bereinigung voraus, dass mit dieser Aktion ausschließlich Vollgenerierungen ausgeführt werden. Des Weiteren wird während der Ausführung des Cleanups von Replikationen innerhalb der Commerce Cloud abgeraten.

Da der Salesforce Commerce Cloud Cleanup eine erfolgreiche Ausführung des Job Schedules und somit den Import des Contents voraussetzt, darf auch dieser im Fehlerfall nicht ausgeführt werden.

4.9. Arbeitsabläufe

Die Freigabe, das Löschen und die Publizierung von Inhalten durch Redakteure erfolgt innerhalb des mitgelieferten Referenzprojekts ContentConnect Reference Project über Arbeitsabläufe. Es enthält aus diesem Grund einen Publish-Arbeitsablauf sowie die BasicWorkflows, die alternativ zu projektspezifischen Arbeitsabläufen eingesetzt werden können.

Installation des BasicWorkflows-Moduls

Vor der Verwendung der Arbeitsabläufe 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 zugehörigen Web-Komponenten. Die Web-Komponente der BasicWorkflows wird allerdings nur in der Registerkarte ContentCreator benötigt.

Der Einsatz der BasicWorkflows im ContentCreator erfordert darüber hinaus die Auswahl des bereitgestellten BasicWorkflows Status Providers im Bereich Projekt-EigenschaftenContentCreator innerhalb des ServerManagers. Im Referenzprojekt ContentConnect Reference Project ist diese Einstellung bereits vorgenommen (vgl. Abbildung Element Status Provider).

Element Status Provider
Abbildung 19. Element Status Provider


Des Weiteren ist im Bereich Projekt-EigenschaftenOptionen der Arbeitsablauf zum Löschen von Elementen vorausgewählt. Dies bewirkt, dass jede Handlung zum Löschen von Elementen innerhalb des Projekts (Entf-Taste, Lösch-Symbol) über ihn ausgeführt wird. Das native (von einem Arbeitsablauf unabhängige) Löschen von Elementen steht somit nicht zur Verfügung – auch nicht für den Administrator.

Vorlagen

Die BasicWorkflows sowie der mit dem StarterPackage mitgelieferte Arbeitsablauf benötigen verschiedene Vorlagen. Diese müssen für die BasicWorkflows üblicherweise über das Kontextmenü in das verwendete FirstSpirit-Projekt importiert werden. Im Referenzprojekt sind sie jedoch bereits vorhanden und ein Import der Vorlagen ist somit nicht notwendig.

Der Publish-Arbeitsablauf stößt den Deployment-Auftrag an und benötigt dafür dessen Namen. Weicht dieser von dem Ausdruck Generate and deploy to SFCC ab, ist innerhalb des Skripts SFCC Release Deployment der Wert der Variablen scheduleName entsprechend anzupassen.

Rechtevergabe

Im letzten Schritt müssen die Arbeitsabläufe 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 ExtrasRechte ä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 der Arbeitsabläufe beziehen sich auf die Gruppe Everyone. Falls dies nicht gewünscht ist, muss eine manuelle Anpassung der Rechte erfolgen.

Nähere Informationen finden Sie in der BasicWorkflows-Dokumentation.

4.10. Projekteinstellungen

Für die Verbindung zwischen FirstSpirit und der Commerce Cloud sind einige projektspezifische Informationen unentbehrlich (vgl. Abbildung Projekteinstellungen). Sie werden über das Formular der Projekteinstellungen erfasst und sind innerhalb des Referenzprojekts anzugeben.

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

Projekteinstellungen
Abbildung 20. Projekteinstellungen


Storefront Base URL

Das Feld dient der Angabe der Basis-URL des Storefronts, die um den Page Type und die ID des anzuzeigenden Elements (z. B. Produkt-, Kategorie- oder Asset-ID) erweitert wird. Sie besitzt das folgende Format:

https://<SUBDOMAIN INSTANCE>/on/demandware.store/Sites-<SIDE ID>-Site

Weitere Informationen zur Storefront Base URL erhalten Sie in der Commerce Cloud Dokumentation im Kapitel Merchandising Your SiteSearch Engine OptimizationURL SyntaxSalesforce B2C Commerce URL Syntax Without SEO.

Als Wert der Storefront Base URL darf entsprechend ihres genannten Formats lediglich der Teil bis zur Locale und nicht die gesamte URL angegeben werden.

Beispiel:

https://www.mystore.com/on/demandware.store/​Sites-YourShopHere-Site/

SFCC Content Asset ID Prefix
Zur eindeutigen Identifizierung der durch FirstSpirit erzeugten Content Assets ist an dieser Stelle ein Präfix für die Content Asset ID zu definieren.
Preview Protection (BasicAuth)
Innerhalb der Commerce Cloud lässt sich der Zugriff auf den Storefront schützen, indem der Site Status Online (protected) aktiviert wird. Besteht diese Einschränkung, muss in FirstSpirit der User storefront angegeben werden. Durch die Aktivierung des Toggles werden die Felder User und Password eingeblendet.
User
Ist die Beschränkung des Zugriffs in der Commerce Cloud aktiviert, muss in diesem Feld der User storefront angegeben werden.
Password
In diesem Feld erfolgt die Angabe des zum storefront Users gehörenden Passworts.
StarterPackage Version
Dieses Feld dient allein zur Anzeige der Version des verwendeten Referenzprojekts.
Enable Custom Affixes
Das Toggle ermöglicht die Verwendung individueller Affixe für die in den Vorlagen enthaltenen HTML-Kommentare, mit denen die für die Vorschau zu ersetzenden Inhalte gekennzeichnet sind. Diese besitzen standardmäßig das Format <!-- CMS-<IDENTIFIER>-START --> bzw. <!-- CMS-<IDENTIFIER>-END -->. Mit der Aktivierung des Toggles werden alle vier Affixe überschrieben und die Defaultwerte somit nicht mehr berücksichtigt. Die spezifischen Werte lassen sich anschließend über die nachfolgenden Felder angeben. Fehlt trotz aktiviertem Toggle eines der Eingabefelder, wird für das entsprechende Affix ein Leerstring verwendet.

Für die individuellen Affixe gilt das Format <!-- [OPENING_PREFIX]<IDENTIFIER>[OPENING_SUFFIX] --> bzw. <!-- [CLOSING_PREFIX]<IDENTIFIER>[CLOSING_SUFFIX] -->.

Leerzeichen, die in den Konfigurationsfeldern vor oder hinter einem individuellen Affix angegeben sind, werden ignoriert.

Die Aktivierung des Toggles ohne die Definition mindestens eines Affixes kann zu unerwartetem Verhalten führen.

Innerhalb des Referenzprojekts besitzen alle HTML-Kommentare das Standardformat. Aus diesem Grund enthält die Vorlage für die Projekteinstellungen weder das Toggle noch die Eingabefelder für die Verwendung individueller Affixe.

Opening Prefix/Opening Suffix
Das öffnende Präfix und das öffnende Suffix bilden zusammen mit dem Identifier den Start-HTML-Kommentar und markieren den Anfang des zu ersetzenden Inhalts.
Closing Prefix/Closing Suffix
Das schließende Präfix und das schließende Suffix bilden zusammen mit dem Identifier den End-HTML-Kommentar und markieren das Ende des zu ersetzenden Inhalts.
Storefront-URL Controller Form Field
Zur Bestimmung der Storefront-URL muss der ContentConnect Preview Filter wissen, welchen Controller (z. B. Home, Page oder Search) er ansprechen soll. Diese Information ist in der Regel abhängig von der anzuzeigenden Seite, weshalb der Preview Filter sie aus einer Eingabekomponente des Formulars der Vorschauseite ausliest. Dabei verwendet er standardmäßig das Feld pt_storefrontUrlController. Dieses Verhalten kann in den Projekteinstellungen über das Feld ps_storefrontUrlControllerFormField konfiguriert werden, in das bei Bedarf der Name des auszulesenden Formularfeldes einzutragen ist.

Innerhalb des Referenzprojekts besitzen alle Seitenvorlagen standardmäßig die Eingabekomponente pt_storefrontUrlController. Aus diesem Grund ist das Feld zur Konfiguration ihres Namens nicht in der Vorlage der Projekteinstellungen enthalten.

Storefront-URL Context ID Form Field
Zusätzlich zum Controller benötigt der ContentConnect Preview Filter in manchen Fällen eine ID (z. B. eine Produkt-, Kategorie-, oder Content Asset-ID), die er ebenfalls au