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.230809 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. 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-Dokumentation zu finden. |
3.1.1. 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 beiden automatisch erstellen 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. 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 Konfiguration der URL Factory, die zur Erzeugung von Medienbinärdaten URLs, sowie Datensatz und Seitenreferenz Routen genutzt wird, 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) und Infix 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 Medienbereitstellung mittels der |
Die angezeigten projektspezifischen API-Keys werden vom CaaS Connect-Modul automatisch erzeugt. Für Vorschau und Freigabe des Projektes wird je ein API-Key mit nur Leseberechtigung und ein API-Key mit Lese- und Schreibberechtigung zur Verfügung gestellt.
3.3. Aufträge
Darüber hinaus erzeugt das Hinzufügen der Projekt-Komponente die zwei Aufträge CaaS Connect Release Generation und CaaS Connect Preview Generation 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 beiden Aufträge zur Synchronisierung genutzt werden. |
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 UI 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. |
|
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 auf Seiten 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 Serverlogs 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.
5.4. Indizes
Indizes, die standardmäßig für eine Collection vorgesehen sind, werden gleichzeitig mit der Collection angelegt. Dies geschieht beim Start des CaaS Connect Service bzw. bei der Ausführung eines Deployment-Auftrags in den CaaS. Kann ein Index nicht erstellt werden, so wird im FirstSpirit-Log eine Warnung ausgegeben.
Sollte es in einer Collection bereits einen Index mit demselben Inhalt aber anderem Namen geben, so bleibt jener unverändert erhalten. Dasselbe gilt für einen gleichnamigen Index mit abweichendem Inhalt. In beiden Fällen kann der neue Index nicht erstellt werden. Der Request wird dann mit HTTP-Status 406 beantwortet und als Warnung geloggt. Solche Warnungen können entweder ignoriert oder der vorliegende Index gelöscht werden. Durch Servicestart bzw. Auftragsausführung wird dann ein erneuter Versuch der Indexerstellung ausgelöst.
Informationen zu vorhandenen Indizes können in jeder Collection unter _indexes abgerufen werden.
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.