1. Einleitung
CaaS Connect stellt die redaktionellen Daten von FirstSpirit über ein einheitliches JSON-basiertes Datenformat beliebigen Endpunkten bereit. Die Verwendung des CaaS Connect-Moduls ab Version 3 und der CaaS-Plattform reduziert den Konfigurations- und Administrationsaufwand im FirstSpirit-Projekt für die Auslieferungsschicht erheblich.
|
Content as a Service wird im Folgenden als CaaS abgekürzt. |
1.1. Technische Voraussetzungen
Neben der FirstSpirit Version 5.2.250812 setzt das Modul den Zugriff auf die CaaS-Plattform voraus.
Hierfür muss ein API-Key mit entsprechenden Berechtigungen konfiguriert und die Erreichbarkeit des Plattform-Endpunkts über das Netzwerk sichergestellt sein. Weitere Informationen zur Installation und Verwendung der CaaS-Plattform finden Sie in der entsprechenden Dokumentation.
2. 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, erfolgt nach Installation des Moduls nicht automatisch direkt ein Abgleich des Datenbestandes. Damit das Modul erwartungsgemäß funktioniert, muss zwingend die Service-Komponente konfiguriert werden.
|
Nach Installation oder Aktualisierung des Moduls ist zwingend ein Neustart des FirstSpirit-Servers nötig. |
3. Komponenten
Im Folgenden werden alle Komponenten des Moduls und deren Administration beschrieben.
3.1. Service
Die Service-Komponente CaaS Connect Service ist das Bindeglied zwischen den Projekten auf dem FirstSpirit-Server und der CaaS-Plattform. Damit Projektinhalte zur Plattform übertragen werden, muss der Service gestartet sein. Ist der Service gestoppt, findet kein Abgleich statt. Für den Betrieb des Services ist eine valide Konfiguration nötig.
3.1.1. Konfigurationsdialog
Der Konfigurationsdialog der Service-Komponente CaaS Connect Service zeigt an, welche Felder optional oder verpflichtend sind. Ist ein Feld leer oder die Eingabe fehlerhaft, wird das Feld durch eine rote Umrandung hervorgehoben. Die Minimalkonfiguration umfasst eine erreichbare CaaS-Plattform und einen API-Key, der auf alle CaaS-Projekte lesenden und schreibenden Zugriff hat. Die verschiedenen Konfigurationspunkte sind in dem Kapitel Konfiguration über das Dateisystem näher erklärt. Weitere Informationen zu API-Keys und Berechtigungen sind in der CaaS-Plattform-Dokumentation zu finden.
|
Bitte beachten Sie, dass beim Start des CaaS Modulservice 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. |
|
Die Tenant-ID darf aus maximal 63 Zeichen bestehen und Groß-/Kleinschreibung wird nicht beachtet. |
|
Eine ausführliche Erläuterung des hieraus entstehenden URL-Schemas ist in der CaaS Connect-Moduldokumentation zu finden. |
|
Wenn die Passwort-Verschlüsselung im FirstSpirit-Server aktiviert ist, werden die Werte von |
3.1.2. Medienbereitstellung
Medienbinärdaten können entweder über die CaaS-Plattform oder über einen S3-kompatiblen Service bereitgestellt werden. Der Upload der Binärdaten in die CaaS-Plattform ist die Standardkonfiguration. Sofern Binärdaten in einem S3-Service ausgeliefert werden sollen, muss die Konfiguration der Service-Komponente CaaS Connect Service entsprechend angepasst werden.
|
Wird die Medienbereitstellung 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 auf selbige aktualisiert. Gegebenenfalls ist ein direkter Vollabgleich gewünscht, sodass keine Änderung im Projekt stattfinden muss. Hierfür kann über die automatisch erstellten Aufträge für jedes Projekt ein Vollabgleich ausgelöst werden. |
Bereitstellung über S3:
Es können sowohl Amazon S3 als auch S3-kompatible Services zur Auslieferung verwendet werden. Die Angabe eines S3-Endpunkts ist optional. Ist kein Endpunkt angegeben, wird davon ausgegangen, dass Amazon S3 angesteuert wird. In diesem Fall muss eine Client-Region angegeben werden, damit der Amazon-Endpunkt bestimmt werden kann. Er setzt sich so zusammen: s3.$clientRegion.amazonaws.com. Die Zugangsdaten für den S3-Service sind ebenfalls optional. 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.
|
Sofern ein S3-kompatibler Service ohne eine CloudFront-Domain benutzt wird, werden die Links der Binärdaten von Medien im Virtual Hosted-Style Format ausgegeben. Für genauere Informationen bezüglich des Formats und dessen Einschränkungen siehe Virtual hosting of buckets und Amazon S3 Path Deprecation Plan. |
3.2. Projekt-Komponente
Das Hinzufügen der Projekt-Komponente CaaS Connect Projekt-App aktiviert das CaaS Connect-Modul im jeweiligen Projekt.
3.2.1. Konfigurationsdialog
Der Konfigurationsdialog der Projekt-Komponente stellt nützliche Informationen wie die CaaS-Basis-URLs oder projektspezifische API-Keys dar und erlaubt weitere projektspezifische Konfiguration.
Die angezeigten projektspezifischen API-Keys werden vom CaaS Connect-Modul automatisch erzeugt. Für Vorschau- und Freigabestand des Projektes wird je ein API-Key mit nur Leseberechtigung und ein API-Key mit Lese- und Schreibberechtigung zur Verfügung gestellt. Zusätzlich wird je ein GraphQL-API-Key für den Vorschau- und Freigabestand erzeugt. Diese Keys erlauben ausschließlich die Ausführung der jeweiligen GraphQL-App.
- Generierung URLs/Routen
-
Die URL Factory, die im Standard zur Erzeugung von Medienbinärdaten URLs, sowie Datensatz und Seitenreferenz Routen genutzt wird, ist
Advanced URLs. Diese URL Factory kann projektspezifisch überschrieben werden. Wir empfehlen die Benutzung einer URL Factory, welche die FirstSpirit-Registry als Persistenz benutzt. Von den Standard-FirstSpirit-Url-Factories, verwenden die folgenden die FirstSpirit-Registry:Advanced URLs,Default URLs (SEO),Multiview URLs (SEO)undInfix URLs (SEO).
|
Nach Änderung der URL Factory in der Projekt-Komponente müssen die Daten im CaaS mit einer erneuten Synchronisierung überschrieben werden, damit sich die Änderung auf die CaaS-Inhalte auswirkt. Weitere Informationen zum Überschreiben der CaaS-Daten mittels der Aufträge sind dem Kapitel Überschreiben des kompletten Datenbestands zu entnehmen. |
|
Die konfigurierte URL Factory wird zur Erzeugung von Medienbinärdaten-URLs nur dann verwendet, wenn die |
- Remote-Datensätze
-
Durch die Nutzung von Referenzen für Remote-Datensätze im Projekt wird die Last beim Verteilen von Datensätzen an die Zielprojekte vermieden, Änderungen sind dadurch schneller sichtbar. In diesem Fall werden URLs, die auf Remote-Datensätze verweisen, direkt auf das Quellprojekt geleitet. Wir empfehlen diese Konfiguration zu benutzen.
|
Die generierten Collection-API-Keys, die Sie in der Projekt-App-Oberfläche sehen, sind projektspezifisch. Wenn Sie Remote-Datensatzreferenzen verwenden, können diese nicht auf Datensätze zugreifen, die sich in einem separaten Projekt befinden. Sie werden manuell einen API-Key mit den entsprechenden Berechtigungen für die referenzierten Projekte anlegen müssen, um auf die Daten zuzugreifen. Alternativ können die generierten GraphQL-API-Keys zur erfolgreichen Abfrage der GraphQL-Apps verwendet werden, da sie nicht auf bestimmte Collections beschränkt sind. |
3.2.2. Aufträge
Darüber hinaus erzeugt das Hinzufügen der Projekt-Komponente mehrere Aufträge im jeweiligen Projekt. Diese führen für den Freigabe- oder Vorschaustand eine vollständige Synchronisierung des Datenbestands zwischen FirstSpirit und CaaS durch. Sollten bereits vorhandene Projektinhalte existieren, können ebenfalls die Aufträge zur Synchronisierung genutzt werden.
Weitere Informationen können dem Kapitel Manueller Vollabgleich aus der Moduldokumentation entnommen werden.
|
Aufträge werden durch die Installation oder Aktualisierung der Projekt-Komponente automatisch aktualisiert und deren Konfigurationen wieder in den Ursprungszustand zurückgesetzt. Sind Änderungen an den Aufträgen notwendig und sollen persistent sein, so können diese auf einer Kopie der Aufträge angewandt werden. |
3.3. WebApp-Komponente
Die WebApp-Komponente CaaS Connect Web App stellt einen Statusreport für CaaS-Dokumente im ContentCreator bereit. Dieser Dialog ermöglicht es Projektadministratoren, den Synchronisierungszustand der aktuell angezeigten Seitenreferenz zwischen FirstSpirit und dem CaaS zu überprüfen.
3.3.1. Installation
Damit diese UI-Erweiterung im ContentCreator genutzt werden kann, muss die WebApp-Komponente über den ServerManager in der ContentCreator-Webanwendung installiert werden. Details zur Installation finden sich in der FirstSpirit-Dokumentation zu Web-Applikationen bzw. Web-Komponenten.
Nach erfolgreicher Installation steht im ContentCreator der Statusreport-Dialog über das Menü "Aktionen" zur Verfügung.
3.3.2. Statusreport für CaaS-Dokumente
Der Statusreport dient der punktuellen Überprüfung, ob ein FirstSpirit-Element im CaaS existiert und ob die Inhalte übereinstimmen. Er unterstützt Projektadministratoren beim Erkennen von Abweichungen, indem er für jede Sprach- und Standkombination den aktuellen Status anzeigt. Zudem werden weiterführende Informationen, wie die zugehörigen Revisionen und Links zum CaaS-Dokument, bereitgestellt.
Es ist zu beachten, dass eine Ungleichheit der Dokumente nicht zwangsläufig auf einen Fehler im Synchronisierungsprozess hinweist:
-
Die Ursache kann an fehlenden Vorbedingungen auf FirstSpirit-Seite liegen, wie noch nicht erfolgten Freigaben oder fehlenden Referenzen.
-
Zudem kann die Übertragung einer kürzlich bearbeiteten Seite in den CaaS eine gewisse Zeit in Anspruch nehmen, sodass ein Element noch als nicht "IN_SYNC" angezeigt wird, während es sich noch im Synchronisierungsprozess befindet.
Diese Ursachen sollten geprüft werden, bevor von einem technischen Fehler ausgegangen wird.
Wenn ein Element im CaaS fehlt oder der Inhalt abweicht, kann es aus dem Dialog heraus erneut synchronisiert werden. Sollte danach weiterhin ein unerwünschter Status bestehen, kann der Statusreport als JSON-Datei heruntergeladen und an den technischen Support zur Analyse weitergegeben werden.
|
Synchronisierungen, die über den Dialog ausgelöst wird, zählen ebenso wie die Aufträge gegen das Fair-Use-Limit von CaaS Connect. |
- Statusübersicht
-
Für jede Sprache und jeden Stand (Vorschau/Freigabe) wird der Synchronisierungsstatus angezeigt:
Status Symbol Bedeutung In Sync
✓
Element und CaaS-Dokument stimmen inhaltlich überein.
Out of Sync
✗
Die Inhalte von Element und CaaS-Dokument weichen voneinander ab. Dieser Status tritt beispielsweise dann auf, wenn die eventgetriebene Verarbeitung einer Veränderung für das Elementes noch nicht abgeschlossen ist, oder wenn sich außerhalb des CMS gepflegte Inhalte ändern, die in FirstSpirit referenziert sind.
Missing in CaaS
✗
Das Dokument wurde im CaaS nicht gefunden. Der Synchronisierungsstatus lässt sich somit nicht bestimmen. Dies ist z.B. dann der Fall, wenn ein FirstSpirit- Projekt importiert wurde, aber noch keine initiale Befüllung des CaaS stattfand.
Content unavailable
✗
Das Rendering des Elements ist fehlgeschlagen, z. B. aufgrund einer gelöschten Seitenvorlage. Weitere Informationen können über den "Details"-Button aufgerufen werden. Die Ursache muss auf FirstSpirit-Seite behoben werden, bevor eine Synchronisierung in den CaaS möglich ist.
Never Released
ℹ
Das Element wurde noch nie freigegeben, sodass daher im Freigabe-Stand des CaaS kein Dokument existieren kann.
- Filter und Sortierung
-
Die Statusanzeige kann nach Sprache, Vorschau-/Freigabestand sortiert und nach synchronisierten bzw. abweichenden Dokumenten gefiltert werden.
- Links
-
Für jedes Dokument kann ein Link zum entsprechenden CaaS-Dokument in die Zwischenablage kopiert werden.
- Synchronisierung der Dokumente
-
Einzelne Dokumente können direkt aus dem Dialog heraus erneut in den CaaS synchronisiert werden. Es kann zwischen Vorschau- und Freigabestand gewählt werden. Eine Auswahl einzelner Sprachen ist hingegen nicht möglich.
Die so angestoßene Synchronisierung geschieht parallel zu bereits laufenden Synchronisierungsprozessen, die mittels Eventing oder Auftrag begonnen wurden.
- Pipeline-Status
-
Im Dialogkopf wird der aktuelle Verarbeitungsstatus der Synchronisierung angezeigt. Die Anzeige aktualisiert sich automatisch alle zwei Sekunden und zeigt an, ob derzeit Dokumente vom Modul verarbeitet werden. Der Pipeline-Status zeigt nicht an, wie viele Dokumente aktuell auf eine Verarbeitung warten.
Zustand Bedeutung Leerlauf (grün)
Es werden aktuell keine Events verarbeitet.
Aktiv (blau)
Dokumente befinden sich in der Verarbeitung. Neben der Anzahl wird der Zeitstempel des ältesten noch nicht verarbeiteten Dokumente angezeigt.
Verzögert (orange)
Ein Dokument hat eine Verzögerung von mehr als 30 Sekunden. Dies kann auf eine etwas erhöhte Last oder ein komplexes Element hinweisen.
Kritisch (rot)
Ein Dokument hat eine Verzögerung von mehr als 2 Minuten. Dies weist auf eine hohe Last im Synchronisierungsprozess hin.
- Statusreport herunterladen
-
Der vollständige Statusreport inklusive des Synchronisationsprotokolls kann als JSON-Datei heruntergeladen werden. Falls Sie sich im Zuge einer etwaigen Diskrepanz an unseren technischen Support wenden, fügen Sie diese Datei bitte als Information bei.
4. Konfiguration über das Dateisystem
Neben der händischen Konfiguration über die FirstSpirit-Oberflä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 Pfad ./conf/modules/CaasConnect.CaasConnectService/caasConnect.json liegen muss. Die folgenden Beispiele zeigen die in der Konfigurationsdatei benötigte und unterstützte Struktur.
|
Die folgenden Beispielkonfigurationen dürfen nicht auf Test- oder Produktivsystemen eingesetzt werden und müssen durch kundenspezifische Werte ersetzt werden. |
caasConnect.json Datei
{
// Wo die CaaS Plattform erreichbar ist
"baseUrl":"http://localhost:8080",
// Der API-Key der für Datenübertragung zwischen Modul und Plattform verwendet wird
"apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
// Der Name oder Kürzel des Mandanten
"tenantId": "defaultTenant"
}caasConnect.json Datei
{
// URL zur API der CaaS Plattform
"baseUrl":"http://localhost:8080",
// API-Key zur Datenübertragung zwischen Modul und Plattform
"apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
// Der Name oder Kürzel des Mandanten
"tenantId": "defaultTenant",
// (Optional) Konfiguration zum Upload und Bereitstellung der Mediendateien über ein S3 Bucket
// Defaultkonfiguration: CaaS wird zur Bereitstellung von Mediendateien benutzt
"mediaConnectorConfig" : {
"S3": {
// (Optional) URL zu einem S3-kompatiblen API Endpunkt
// Defaultkonfiguration: AWS API Endpunkt (https://s3.{Region}.amazonaws.com)
"endpointUri": "https://s3.eu-central-1.amazonaws.com",
// (Optional) S3 Credentials für den Upload von Mediendateien
// Defaultkonfiguration: Verwendet die "Default provider chain" des AWS Java SDK (siehe https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html#credentials-chain)
"credentials": {
"accessKeyId": "mySecretS3KeyId",
"secretAccessKey": "mySecretS3AccessKey"
},
// Name des S3 Buckets
"bucketName": "examplebucketname",
"timeoutInSeconds": 10,
// (Optional) Region des Buckets
// Defaultkonfiguration: Verwendet die "Default region provider chain" des AWS SDK (siehe https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/region-selection.html#automatically-determine-the-aws-region-from-the-environment)
"clientRegion": "eu-central-1",
// (Optional) "Cache-Control" Metadatenattribut, das dem S3 Objekt beim Upload hinzugefügt wird
// Defaultkonfiguration: maxAge 300 Sekunden (5 Minuten), maxAgeShared 900 Sekunden (15 Minuten)
"cacheControl": {
"maxAge": {
"seconds": 10
},
"maxAgeShared": {
"seconds": 15
}
},
// (Optional) Konfiguration zur Bereitstellung der Mediendateien über eine CloudFront Distribution
// Defaultkonfiguration: URL des S3 Buckets im virtuellen Hosting-Stil wird zur Bereitstellung von Mediendateien benutzt (z.B. https://examplebucketname.s3.{Region}.amazonaws.com/)
"cloudFront": {
// (Optional) URL zu einem CloudFront-kompatiblen API Endpunkt
// Defaultkonfiguration: AWS CloudFront API Endpunkt (https://cloudfront.amazonaws.com)
"endpointUri": "https://cloudfront.amazonaws.com",
// Id der zu verwendenden CloudFront Distribution
"distributionId": "A4L1CDF3GND316",
// Base Url der zu verwendenden CloudFront Domain
"baseUrl": "https://my-cloudfront-domain.com",
// (Optional) Aktiviert/Deaktiviert die manuelle Invalidierung von Dateien im CloudFront CDN
// Defaultkonfiguration: Dateien werden nicht manuell invalidiert (invalidateFiles = false)
"invalidateFiles": false
},
// (Optional) URL Factory, die zur Erzeugung von SEO Routen innerhalb von Medienbinärdaten-URLs verwendet wird
"seoRouteFactory": "Advanced URLs"
}
},
// (Optional) Endpunkt eines HTTP Proxys, der zur Kommunikation mit der CaaS Plattform oder anderen Services (S3, CloudFront) genutzt werden soll
"proxyAddress": "foo:123"
}|
Kommt es beim Lesen der Konfigurationsdatei durch den Service zu einem Fehler, 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 Eingaben unterliegen neben Optionalität noch weiteren Einschränkungen, beispielsweise kann ein Bucket-Name keine Großbuchstaben beinhalten. Ungültige Eingaben werden in der Benutzeroberfläche direkt angezeigt und können nicht gespeichert werden. Wird eine solche ungültige Konfiguration als Datei hinterlegt, kommt es zu oben genannter Fehlermeldung im FirstSpirit-Log und der Service startet nicht. |
|
Nach Änderungen an der Konfiguration ist es notwendig den Service neu zu starten. Erst danach sind diese aktiv. |
|
Wenn die Passwort-Verschlüsselung im FirstSpirit-Server aktiviert ist, werden die Werte für die Felder |
|
Das Hinzufügen einer Projekt-Komponente zu einem Projekt ist über die FirstSpirit-API möglich. ModuleAdminAgent.installProjectApp("CaasConnect", caasConnectProjectAppName, project) |
5. Fehlerbehandlung
Durch ungültige Konfiguration oder Netzwerkprobleme kann es zu Fehlern aufseiten des CaaS Connect-Moduls kommen. Alle Fehler werden im FirstSpirit-Log ausgegeben.
5.1. Netzwerkfehler oder Überlastung
Das Modul ist auf die einwandfreie Verfügbarkeit der CaaS-Plattform angewiesen. Ist die Plattform nicht erreichbar oder kann sie die eingehenden Anfragen nicht ausreichend schnell 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, die durch die durchgeführte Aktion ausgelöst wurden, werden nicht mit der CaaS-Plattform abgeglichen. Dem Redakteur wird der Fehler nicht mitgeteilt, daher ist das Überwachen des Server-Logs durch die Administration essenziell. Tritt ein Fehler auf, kann entweder durch Ausführen der Standard-Aufträge oder erneutes Durchführen der fehlgeschlagenen Aktion der Abgleich korrigiert werden.
5.2. Konfiguration des API-Keys
Der in der Service-Komponente konfigurierte API-Key wird verwendet, um alle Projekte auf dem Server mit der CaaS-Plattform abzugleichen. Der API-Key benötigt daher Schreib- und Leserechte für alle CaaS-Projekte, auf dem FirstSpirit-Server. Weitere Information zur Konfiguration von API-Keys finden Sie in der CaaS-Plattform-Dokumentation.
5.3. Push-Benachrichtigungen (Change Streams)
Die Change Stream Definitionen sind in den Metadaten der Collections zu finden. Sie werden gleichzeitig mit der Collection angelegt. Sollten sie fehlen, können sie wiederhergestellt werden, indem ein neues Deployment in den CaaS per Auftrag angestoßen wird.
6. 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 möglicherweise fremden, nicht von der Crownpeak Technology GmbH hergestellten, eingesetzten Software-Produkten, deren eigenen Lizenzen und gegebenenfalls Aktualisierungsinformationen, finden Sie in der Datei META-INF/licenses.csv, die mit dem Modul ausgeliefert wird.
7. Hilfe
Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.