1. Einleitung

Dieses Dokument richtet sich an FirstSpirit-Serveradministratoren, die das CaaS Connect-Modul auf einem FirstSpirit-Server installieren, konfigurieren und betreiben. Es behandelt die technischen Voraussetzungen, die Installation und serverseitige Konfiguration des Moduls sowie die Behebung von Betriebsproblemen. Die redaktionelle Nutzung sowie die projektbezogene Konfiguration werden in der Moduldokumentation beschrieben.

Die in diesem Dokument beschriebenen Themen sind in der Regel nur für On-Premises-Installationen relevant.

1.1. Technische Voraussetzungen

Das Modul setzt FirstSpirit in der Version 5.2.250812 oder neuer sowie Zugriff auf die folgenden externen Systeme voraus:

  • CaaS-Plattform (erforderlich) — das Zielsystem für die synchronisierten Inhalte. Der FirstSpirit-Server muss den Plattform-Endpunkt über das Netzwerk erreichen können, und es muss ein Master-API-Key mit Lese- und Schreibzugriff vorhanden sein. Informationen zur Installation und zum Betrieb der CaaS-Plattform finden Sie im CaaS-Plattform Operations Guide.

  • S3-kompatible Object Storage, wahlweise mit vorgeschalteter CloudFront Distribution (optional) — ein alternatives Hosting-Backend für Mediendateien. Details finden Sie im Kapitel Medienbereitstellung.

2. Einrichtung des Moduls

Die folgenden Abschnitte beschreiben die Schritte, die ein FirstSpirit-Serveradministrator durchführen muss, um das Modul einzurichten, einschließlich Installation und grundlegender Minimalkonfiguration.

2.1. Installation des Moduls

Das Modul hat keine Abhängigkeiten auf andere Module und kann somit sehr einfach auf dem FirstSpirit-Server installiert werden. Da Projekte explizit als CaaS-Projekte ausgezeichnet werden müssen (siehe Moduldokumentation), erfolgt nach Installation des Moduls nicht automatisch ein Abgleich des Datenbestandes.

Nach Installation oder Aktualisierung des Moduls ist ein Neustart des FirstSpirit-Servers erforderlich.

2.2. Konfiguration des Services

Die Service-Komponente CaaS Connect Service ist das Bindeglied zwischen den Projekten auf dem FirstSpirit-Server und der CaaS-Plattform. Solange der Service läuft, werden redaktionelle Änderungen für jedes konfigurierte Projekt automatisch mit CaaS synchronisiert. Der Service benötigt eine valide Konfiguration, deren Einstellungen für alle CaaS-Projekte gelten. Einstellungen können projektspezifisch überschrieben werden. Dies wird im Kapitel zur Projektkonfiguration in der Moduldokumentation erläutert.

Bitte beachten Sie, dass beim Start des CaaS Connect Service geprüft wird, ob eine Verbindung zur CaaS-Plattform aufgebaut werden kann. Wenn diese Prüfung fehlschlägt, wird eine Fehlermeldung im FirstSpirit-Serverlog angefügt. Ist der Service gestoppt, findet keine Synchronisierung statt.

Der Konfigurationsdialog der Service-Komponente CaaS Connect Service zeigt an, welche Felder optional oder verpflichtend sind. Ist ein Feld leer oder die Eingabe ungültig, wird das Feld durch eine rote Umrandung hervorgehoben.

Die Minimalkonfiguration umfasst:

  • die URL einer erreichbaren CaaS-Plattform.

  • einen API-Key mit Lese- und Schreibzugriff auf alle CaaS-Projekte (Master-API-Key).
    Weitere Informationen zu API-Keys und Berechtigungen finden Sie in der CaaS-Plattform-Dokumentation.

  • die Tenant-ID.
    Der Wert darf aus maximal 63 Zeichen bestehen, Groß-/Kleinschreibung wird nicht beachtet.

Die verschiedenen Konfigurationspunkte sind im Kapitel Konfiguration über das Dateisystem näher erläutert.
Informationen zu den Optionen für die Medienbereitstellung finden Sie im Kapitel Medienbereitstellung.

service config empty
Abbildung 1. Konfigurationsdialog der Service-Komponente

Wenn die Passwort-Verschlüsselung im FirstSpirit-Server aktiviert ist, werden die Werte für API Key und Secret Access Key (S3) automatisch verschlüsselt, sobald die Konfiguration über den Dialog gespeichert wird oder beim Start des Services. Die Werte werden im Dialog dann verschlüsselt dargestellt.

2.3. Installation der WebApp-Komponente

Die WebApp-Komponente CaaS Connect Web App ist Bestandteil des Moduls und stellt einige optionale Funktionen im ContentCreator bereit.

Wenn Sie diese Funktionen nutzen möchten, muss die WebApp-Komponente über den ServerManager in der ContentCreator-Webanwendung installiert werden. Details zur Installation finden Sie in der FirstSpirit-Dokumentation zu Web-Applikationen bzw. Web-Komponenten.

Die folgenden Funktionen werden durch die CaaS Connect Web App bereitgestellt:

  • Statusreport für CaaS-Dokumente
    Dieser Dialog ermöglicht es Projektadministratoren, den Synchronisierungsstatus der aktuell angezeigten Seitenreferenz zwischen FirstSpirit und CaaS zu überprüfen.
    Nach erfolgreicher Installation steht der Statusreport-Dialog im ContentCreator über das Menü "Aktionen" zur Verfügung.
    Weitere Informationen zum Inhalt des Statusreports und zu dessen Interpretation finden Sie in der CaaS Connect-Moduldokumentation.

  • CaaS Connect Preview Rendering Plugin
    Dieses Plugin kann im Omnichannel Manager genutzt werden, wie in der entsprechenden OCM-Dokumentation beschrieben. Es rendert das JSON eines CaaS-Dokuments dynamisch in FirstSpirit und liefert es als Antwort auf bestimmte OCM-Methoden zurück.

3. Konfiguration über das Dateisystem

Neben der manuellen Konfiguration über die FirstSpirit-Benutzeroberfläche kann CaaS Connect auch über das Dateisystem konfiguriert werden. Hierfür muss lediglich eine JSON-Konfigurationsdatei angelegt werden. Der Service CaaS Connect Service lädt beim Start automatisch die Datei caasConnect.json, die im FirstSpirit-Server unter ./conf/modules/CaasConnect.CaasConnectService/caasConnect.json liegen muss.

Die folgenden Beispiele zeigen das benötigte und unterstützte Format der Konfigurationsdatei.

Verwenden Sie die Werte der Beispielkonfigurationen niemals unverändert auf Ihren Test- oder Produktivsystemen, sondern ersetzen Sie sie durch auf Ihr Projekt angepasste Werte.
Minimale Beispielkonfiguration
{
  "baseUrl": "http://localhost:8080", (1)
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18", (2)
  "tenantId": "defaultTenant" (3)
}
1 Der Endpunkt der CaaS-Plattform
2 Der API-Key, der für die Datenübertragung zwischen Modul und Plattform verwendet wird
3 Name oder Kürzel des Mandanten
Vollständige Beispielkonfiguration
{
  "baseUrl": "http://localhost:8080", (1)
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18", (2)
  "tenantId": "defaultTenant", (3)
  "mediaConnectorConfig" : { (4)
    "S3": {
      "endpointUri": "https://s3.eu-central-1.amazonaws.com", (5)
      "credentials": { (6)
        "accessKeyId": "mySecretS3KeyId",
        "secretAccessKey": "mySecretS3AccessKey"
      },
      "bucketName": "examplebucketname", (7)
      "timeoutInSeconds": 10,
      "clientRegion": "eu-central-1",  (8)
      "cacheControl": { (9)
        "maxAge": {
          "seconds": 100
        },
        "maxAgeShared": {
          "seconds": 150
        }
      },
      "cloudFront": { (10)
        "endpointUri": "https://cloudfront.amazonaws.com", (11)
        "distributionId": "A4L1CDF3GND316", (12)
        "baseUrl": "https://my-cloudfront-domain.com", (13)
        "invalidateFiles": false (14)
      },
      "seoRouteFactory": "Advanced URLs" (15)
    }
  },
  "proxyAddress": "foo:123" (16)
}
1 Der Endpunkt der CaaS-Plattform
2 API-Key für die Datenübertragung zwischen Modul und Plattform
3 Name oder Kürzel des Mandanten
4 (Optional) Konfiguration für den Upload und die Bereitstellung von Mediendateien über ein S3 Bucket.
Standard: Die CaaS-Plattform wird zur Bereitstellung von Mediendateien verwendet
5 (Optional) URL zu einem S3-kompatiblen API-Endpunkt
Standard: AWS API-Endpunkt (https://s3.<region>.amazonaws.com)
6 (Optional) S3-Zugangsdaten für den Upload von Mediendateien
Standard: Verwendet die "Default Provider Chain" des AWS Java SDK (siehe AWS-Dokumentation)
7 Name des S3 Buckets
8 (Optional) Region des Buckets
Standard: Verwendet die "Default Region Provider Chain" des AWS SDK (siehe AWS-Dokumentation)
9 (Optional) Cache-Control-Metadaten, die dem S3-Objekt beim Upload hinzugefügt werden
Standard: maxAge 300 Sekunden (5 Minuten), maxAgeShared 900 Sekunden (15 Minuten)
10 (Optional) Konfiguration zur Bereitstellung von Mediendateien über eine CloudFront Distribution
Standard: Die URL des S3 Buckets im Virtual-Hosted-Style wird zur Bereitstellung von Mediendateien verwendet (z. B. https://examplebucketname.s3.<region>.amazonaws.com/)
11 (Optional) URL zu einem CloudFront-kompatiblen API-Endpunkt
Standard: AWS CloudFront API-Endpunkt (https://cloudfront.amazonaws.com)
12 ID der CloudFront Distribution
13 Basis-URL der CloudFront-Domain
14 (Optional) Aktiviert/deaktiviert die manuelle Invalidierung von Dateien im CloudFront CDN
Standard: false, Dateien werden nicht manuell invalidiert
15 (Optional) URL Factory, die zur Erzeugung von SEO-Routen in Mediendokumenten verwendet wird Wir empfehlen, "Advanced URLs" als Standard festzulegen Diese Factory wird auch für Binärdaten-URLs von Mediendateien verwendet, sofern in der projektspezifischen Konfiguration keine eigene URL Factory definiert ist (siehe Kapitel zur Projektkonfiguration)
16 (Optional) Endpunkt eines HTTP-Proxys für die Kommunikation mit der CaaS-Plattform oder anderen Diensten (S3, CloudFront)

Nach Änderungen an der Konfigurationsdatei ist ein Neustart des Services erforderlich. Erst danach werden diese aktiv.

Tritt beim Einlesen der Konfigurationsdatei durch den Service ein Fehler auf, wird eine entsprechende Fehlermeldung im FirstSpirit-Log ausgegeben. Da der Service ohne valide Konfigurationsdatei nicht starten kann, ist die Funktionalität des Moduls in diesem Fall stark eingeschränkt.

Bitte beachten Sie, dass beim Start des CaaS Modulservice geprüft wird, ob eine Verbindung zur CaaS-Plattform aufgebaut werden kann. Eine nicht erfolgreiche Verbindungsherstellung seitens des Moduls führt dann zu einer Fehlermeldung im FirstSpirit-Serverlog.

Einige Konfigurationswerte unterliegen neben der Optionalität weiteren Einschränkungen, beispielsweise darf ein Bucket-Name keine Großbuchstaben enthalten. Ungültige Werte werden direkt in der Benutzeroberfläche angezeigt und können nicht gespeichert werden. Wird eine solche ungültige Konfiguration als Datei hinterlegt, erscheint eine entsprechende Fehlermeldung im FirstSpirit-Log und der Service startet nicht.

Wenn die Passwort-Verschlüsselung im FirstSpirit-Server aktiviert ist, werden apiKey und mediaConnectorConfig.S3.credentials.secretAccessKey automatisch verschlüsselt. Weitere Informationen finden Sie in der FirstSpirit-Dokumentation für Administratoren. Bitte beachten Sie, dass das Modul einen intern definierten Schlüssel für die Verschlüsselung verwendet und keine der unter password.encryption.key.* angegebenen Werte verwendet werden.

4. Medienbereitstellung

Binärdaten von Medienelementen werden entweder in der CaaS-Plattform selbst oder in einem S3-kompatiblen Dienst gespeichert. Aus Performance-Gründen empfehlen wir dringend, einen S3-kompatiblen Dienst zur Bereitstellung von Mediendateien zu verwenden.

Der Upload von Binärdaten in die CaaS-Plattform ist die Standardkonfiguration des Moduls. Sollen Binärdaten über einen S3-Dienst ausgeliefert werden, muss die Medienbereitstellungs-Konfiguration der Service-Komponente entsprechend angepasst werden. Gegebenenfalls ist es erforderlich, den Service über die Konfigurationsdatei zu konfigurieren, um alle benötigten Informationen bereitzustellen.

Je nach gewählter Hosting-Option unterscheiden sich die URLs, die auf die Binärdaten verweisen, wie im Anhang beschrieben. Die Anzahl der Mediendateien, die in das Zielsystem übertragen werden, ist für alle Hosting-Optionen identisch.

Wird die Medienbereitstellungs-Option geändert, werden bisherige Binärdaten-URLs ungültig. Sobald ein Medium erneut geändert oder freigegeben wird, werden sowohl Binärdaten als auch URLs aktualisiert. Anstatt Änderungen an allen Mediendateien vorzunehmen, um deren Synchronisierung auszulösen, empfehlen wir die Ausführung des Total Sync-Auftrags.

4.1. Speicherung im CaaS

In diesem Modus werden die Binärdaten von Medien in CaaS-File-Buckets gespeichert und können über die CaaS REST API abgerufen werden. Da dies die Standardkonfiguration ist, sind keine weiteren Anpassungen erforderlich, um diese Option der Medienbereitstellung zu nutzen. Weitere Informationen zu den resultierenden URLs finden Sie im Anhang.

4.2. Speicherung in S3

In diesem Modus werden die Binärdaten der Medien in einen S3 Bucket hochgeladen. Zur Auslieferung können sowohl Amazon S3 als auch S3-kompatible Dienste verwendet werden.

Diese Option setzt voraus, dass ein S3 Bucket eingerichtet ist. Außerdem muss die Konfiguration des Services entsprechend angepasst werden, was über das Dateisystem erfolgt.

Gibt es keine Angabe in der Konfiguration, werden Umgebungsvariablen und System Properties ausgewertet. Weitere Informationen zu einer solchen Konfiguration können der offiziellen Amazon S3-Dokumentation entnommen werden.
Ein Beispiel für einen S3-Objektpfad finden Sie im Anhang.

Bei Verwendung der S3-Speicherung können die Dateien entweder über eine CloudFront Distribution oder direkt über den zugehörigen S3 REST API-Endpunkt abgerufen werden.
In den folgenden Kapiteln werden diese beiden Optionen beschrieben.

4.2.1. Zugriff über CloudFront Distribution

Sie können eine CloudFront Distribution einrichten, um die Mediendateien aus dem S3 Bucket auszuliefern. Die URL zur Binärdatei setzt sich dann aus der Domain der CloudFront Distribution und dem Pfad des S3-Objekts zusammen (siehe Anhang für ein Beispiel).

CloudFront-Caching

Das Modul sendet beim Upload freigegebener Mediendateien in das S3 Bucket immer den Cache-Control-Header, weitere Details finden Sie im Abschnitt S3-Objekt-Metadaten. Sie können Ihre CloudFront Distribution so konfigurieren, dass dieser Header aus den HTTP-Antworten eines Origins berücksichtigt wird. Das vollständige Konfigurationsbeispiel zeigt, wie der Cache-Control-Header angepasst werden kann, um das gewünschte Caching-Verhalten von Mediendateien im CloudFront CDN zu steuern.

4.2.2. Zugriff über die S3 REST API

Wenn kein CDN verwendet wird, werden Mediendateien direkt über die S3 REST API aufgerufen. Die URL zu einer Mediendatei setzt sich dann aus der S3 REST API (Virtual Hosted Endpoint des Buckets) und dem Pfad des S3-Objekts zusammen (siehe Anhang für ein Beispiel).

Weitere Informationen zum Format und dessen Einschränkungen finden Sie unter Virtual hosting of buckets und Amazon S3 Path Deprecation Plan.

4.2.3. S3-Objekt-Metadaten

Beim Upload von Mediendateien in das S3 Bucket werden verschiedene Metadaten-Attribute für das S3-Objekt gesetzt:

  • Content-Type
    Dieses Attribut wird als Content-Type-Response-Header für Anfragen an das S3-Objekt verwendet. Es enthält den MIME-Typ der Mediendatei (z. B. image/png).

  • Cache-Control
    Dieses Attribut wird als Cache-Control-Response-Header für Anfragen an das S3-Objekt verwendet.

    • Für den Freigabestand enthält es standardmäßig den Wert public, max-age=300, s-maxage=900.
      Informationen zu den Konfigurationsmöglichkeiten finden Sie im Kapitel Konfiguration über das Dateisystem.

    • Für den Vorschaustand enthält es den Wert private, no-cache.

5. Fehlerbehandlung

Durch ungültige Konfiguration oder Netzwerkprobleme kann es auf Seiten des CaaS Connect-Moduls zu Fehlern kommen. Alle Fehler werden im FirstSpirit-Log protokolliert.

5.1. Netzwerkfehler oder Überlastung

Das Modul ist auf die uneingeschränkte Verfügbarkeit der CaaS-Plattform angewiesen. Ist die Plattform nicht erreichbar oder kann sie eingehende Anfragen nicht schnell genug verarbeiten, versucht das Modul, die Anfragen zu wiederholen. Führt auch dies nicht zum Erfolg, wird im FirstSpirit-Log ein Fehler ausgegeben, und mögliche Änderungen am Datenbestand werden nicht mit der CaaS-Plattform abgeglichen. Dem Redakteur wird der Fehler nicht mitgeteilt, daher ist die Überwachung des Server-Logs durch die Administration unverzichtbar. Tritt ein Fehler auf, kann er entweder durch Ausführen der Aufträge oder durch erneutes Durchführen der Aktion, die zur Datenänderung geführt hat, korrigiert werden.

5.2. Unzureichende Berechtigungen des API-Keys

Der in der Service-Komponente konfigurierte API-Key wird verwendet, um alle Projekte auf dem Server mit der CaaS-Plattform zu synchronisieren. Der API-Key benötigt daher Schreib- und Leseberechtigungen für alle CaaS-Projekte auf dem FirstSpirit-Server. Weitere Informationen zur Konfiguration von API-Keys finden Sie in der CaaS-Plattform-Dokumentation.

6. Anhang

6.1. Binärdaten-URLs für Mediendateien

Je nach Konfiguration der Medienbereitstellung unterscheiden sich die URLs, die auf die Binärdaten der Mediendateien verweisen.

Die folgende Tabelle gibt einen Überblick über die verschiedenen URL-Formate.

Konfiguration der Medienbereitstellung URL-Format für Binärdaten von Mediendateien

CaaS

https://CAAS-BASE-URL/<tenant id>/<project GID>.<release|preview>.files/<media GID>.<language>_<country>_<resolution>/binary

S3 mit CloudFront Distribution

https://<cloudfront base url>/<s3 object path>

S3 REST API

https://<s3 rest api url>/<s3 object path>
CaaS

Die URL zu den Binärdaten setzt sich aus den folgenden Elementen zusammen:

  • der Basis-URL des CaaS-Endpunkts

  • der CaaS-Datenbank, die der Tenant-ID entspricht.

  • dem CaaS-File-Bucket <project GID>.release.files oder <project GID>.preview.files, je nachdem, ob sich ein Medium im Freigabe- oder Vorschaustand befindet.

  • der FirstSpirit-GID des Mediums sowie Sprache und/oder Auflösung (sofern das Medium von Sprache und/oder Auflösung abhängt).

  • dem Suffix /binary

Im JSON einer Mediendatei verweist die URL zu den Binärdaten auf die CaaS REST API:

Beispiel: JSON eines Mediendokuments mit Verweis auf die CaaS REST API
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            ...
            "url": "https://CAAS-BASE-URL/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.ORIGINAL/binary"
        }
    },
    ...
}
S3-Objektpfad

Der S3-Objektpfad setzt sich zusammen aus:

  • dem konfigurierten Pfadpräfix (Standardpräfix ist /)

  • der GID des Projekts und dem Pfadsegment /preview oder /release, je nachdem, ob sich das Medium im Freigabe- oder Vorschaustand befindet.

  • dem restlichen Pfad und dem Dateinamen, die von der in der Service-Konfiguration definierten URL Factory (siehe seoRouteFactory im vollständigen Konfigurationsbeispiel) bzw., sofern vorhanden, von der projektspezifischen Konfiguration abgeleitet werden.

Beispiel für einen S3-Objektpfad:
/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/images/thisisatest.png

CloudFront

Die Binärdatei ist über eine CloudFront Distribution erreichbar, die so konfiguriert ist, dass sie das S3 Bucket verwendet.
Im JSON einer Mediendatei verweist die URL auf die CloudFront-Domain my-cloudfront-domain.tld:

Beispiel: JSON eines Mediendokuments mit Verweis auf die CloudFront Distribution-Domain
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            ...
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/images/thisisatest.png"
        }
    },
    ...
}
S3 REST API

Die URL zu einer Mediendatei setzt sich aus der S3 REST API und dem Pfad des S3-Objekts zusammen.
Im folgenden Beispiel verweist die URL auf die Original-Auflösung eines Bildes im S3 Bucket my-bucket in der Region eu-central-1:

Beispiel: JSON eines Mediendokuments mit Verweis auf die S3 REST API
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            ...
            "url": "https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/images/thisisatest.png"
        }
    },
    ...
}

7. Rechtliche Hinweise

CaaS ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.

Für die Verwendung des Produkts gilt gegenüber dem Anwender nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

Details zu eingesetzten Software-Produkten Dritter, die nicht von Crownpeak Technology GmbH hergestellt wurden, deren eigenen Lizenzen und gegebenenfalls Aktualisierungsinformationen finden Sie in der mit dem Modul ausgelieferten Datei META-INF/licenses.csv.

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