1. Einleitung

Das CaaS Connect-Modul verbindet die FirstSpirit-Redaktionsumgebung mit der CaaS-Plattform, unserer Content-Delivery-Schicht. In FirstSpirit erstellte redaktionelle Inhalte werden automatisch mit der CaaS-Plattform synchronisiert und dort über eine REST API und eine GraphQL API als standardisierte JSON-Dokumente bereitgestellt. Front-End-Anwendungen konsumieren diese Inhalte direkt von der CaaS-Plattform.

Templating in FirstSpirit entfällt und wird auf das Front-End bzw. auf Front-End-Services verlagert (siehe Crownpeak PWA Template für eine Referenzimplementierung einer Progressive Web App). FirstSpirit-Entwickler können sich somit auf das Modellieren fachlicher Objekte und das Gestalten der zugehörigen Eingabekomponenten konzentrieren.

Die Anbindung an die CaaS-Plattform ist für die Redaktion weitgehend unsichtbar. Sobald in FirstSpirit eine Änderung vorgenommen wird, wird die Synchronisierung im Hintergrund ausgelöst und die CaaS-Plattform spiegelt die Änderung unmittelbar wider. Redakteure können den aktuellen Datenstand direkt über die CaaS-Plattform einsehen; ein technischer Eingriff ist nur im Fehlerfall erforderlich.

1.1. Geltungsbereich dieses Dokuments

Dieses Dokument richtet sich an FirstSpirit-Entwickler und Projektadministratoren, die mit Projekten arbeiten, in denen das CaaS Connect-Modul verwendet wird. Es behandelt die Aktivierung und projektspezifische Konfiguration des Moduls, das Datenformat der CaaS-Dokumente, Aufträge für den Datenabgleich, die Speicherung von Mediendateien, den Statusreport sowie die GraphQL API.

Die Installation und serverseitige Konfiguration des Moduls werden in der Administrator-Dokumentation beschrieben.

2. Erste Schritte

2.1. Aktivierung des Moduls

Sobald die Installation des CaaS Connect-Moduls und die grundlegende Konfiguration des CaaS Connect Service abgeschlossen sind (in SaaS-Umgebungen automatisch, in On-Premises-Installationen durch den FirstSpirit-Serveradministrator), muss das Modul aktiviert werden. Dies geschieht, indem die Projekt-Komponente CaaS Connect Projekt-App jedem Projekt hinzugefügt wird, dessen Inhalte in die CaaS-Plattform übertragen werden sollen.

Details finden Sie in der FirstSpirit-Dokumentation zu Projekt-Komponenten.

Durch die Aktivierung des Moduls für ein Projekt ist die Synchronisierung der Projektinhalte mit der CaaS-Plattform eingerichtet. Außerdem werden die erforderlichen Collections und einige API-Keys in der CaaS-Plattform automatisch angelegt. Schließlich werden die Aufträge für die manuelle Synchronisierung der Projektinhalte angelegt und konfiguriert (siehe Kapitel Aufträge für den Datenabgleich).

2.2. Endpunkte und API-Keys

Die Projekt-Komponente enthält einen Konfigurationsdialog, der nützliche Informationen wie alle CaaS-Endpunkte und projektspezifische API-Keys anzeigt. Er bietet außerdem verschiedene Konfigurationsoptionen, die im Kapitel zur Konfiguration beschrieben werden.

project app endpoints
Abbildung 1. Konfigurationsdialog: "Endpunkte"

Alle vom CaaS Connect-Modul für das Projekt angelegten Collections werden im Bereich "Endpunkte" des Konfigurationsdialogs aufgelistet.

project app apikeys
Abbildung 2. Konfigurationsdialog: "API-Keys"

Die angezeigten projektspezifischen API-Keys werden vom CaaS Connect-Modul automatisch erzeugt. Für den Vorschau- und Freigabestand des Projekts wird jeweils ein API-Key mit reiner Leseberechtigung und ein API-Key mit Lese- und Schreibberechtigung bereitgestellt. Zusätzlich wird je ein GraphQL-API-Key für Vorschau- und Freigabestand bereitgestellt. Diese Keys erlauben ausschließlich die Ausführung der jeweiligen GraphQL-App.

3. Modulkonzepte

3.1. Unterstützte FirstSpirit-Elemente

Das Modul erzeugt für die folgenden FirstSpirit-Elemente Dokumente in der CaaS-Plattform:

  • Seitenreferenzen

  • Medien

  • Globale Inhaltsseiten

  • Projekteinstellungsseite

  • Datensätze

Jedes Element wird durch mehrere Dokumente repräsentiert. Sowohl für den Vorschau- als auch für den Freigabestand wird für jede Sprache des FirstSpirit-Projekts, die in der Sprachkonfiguration des Projekts mit Sprache generieren markiert ist, ein Dokument erzeugt. Dies gilt auch für sprachunabhängige Medienelemente. Jedes dieser Dokumente kann mit einer eindeutigen URL identifiziert und referenziert werden.

3.2. Datensynchronisierung

Inhaltsänderungen werden über FirstSpirit-Events automatisch und nahezu in Echtzeit im Hintergrund mit der CaaS-Plattform synchronisiert. Dadurch sind die Daten in der CaaS-Plattform stets aktuell und spiegeln den aktuellen Stand des Projekts in FirstSpirit wider. Es gibt nur wenige Szenarien, in denen ein manueller Vollabgleich zwischen FirstSpirit und der CaaS-Plattform erforderlich sein kann:

  • Befüllung des CaaS mit bereits vorhandenen Projektdaten zum Start eines Projekts

  • Abgleich der Daten bei Dateninkonsistenzen zwischen FirstSpirit und der CaaS-Plattform

  • Aktualisierung der CaaS-Daten nach einer Änderung der Konfiguration, die sich auf die Daten auswirkt (z. B. Änderung der URL Factory oder der CaaS-Tags)

Für diesen Zweck stellt das CaaS Connect-Modul Aufträge zur Verfügung. Details zu den Aufträgen und deren Konfiguration finden Sie im Kapitel Aufträge für den Datenabgleich.

3.3. Vorschau- und Freigabestand

Eine wesentliche Unterscheidung zwischen Vorschau- und Freigabe-Datenständen wird sowohl von FirstSpirit als auch vom CaaS Connect-Modul vorgenommen. Auch die CaaS-Plattform führt beide Datenstände, die durch unterschiedliche CaaS-URLs unterscheidbar sind (siehe URL-Schema für CaaS-Dokumente). Eine Synchronisierung beider Datenstände erfolgt immer auf Basis bestimmter Aktionen, die die Redaktion in FirstSpirit vornimmt. Freigabeaktionen sind dabei die einzigen Aktionen, die den Freigabestand aktualisieren; alle anderen Änderungen wirken sich ausschließlich auf den Vorschaustand aus.

Projekt ohne "Freigabe nutzen"

Falls die Freigabefunktion im FirstSpirit-Projekt deaktiviert wurde (siehe FirstSpirit-Dokumentation zu Projekteigenschaften), werden nur Vorschau-Datenstände in den CaaS übertragen. Um Daten im Freigabestand zu aktualisieren, muss ein manueller Vollabgleich mit den CaaS Connect-Aufträgen ausgeführt werden.

3.4. URL-Schema für CaaS-Dokumente

Die CaaS-URL eines Dokuments besteht aus den folgenden Elementen:

  • Die Tenant-ID ist der gepflegte Name oder das Kürzel des Mandanten.
    Sie wird im CaaS Connect Service vom Serveradministrator gesetzt.

  • Der Projektbezeichner ist die GID des FirstSpirit-Projekts.

  • Der Collection-Bezeichner enthält entweder den Wert release.content oder preview.content.
    Er erlaubt die Unterscheidung zwischen Freigabe- und Vorschaustand.

  • Der Dokumentbezeichner setzt sich aus der FirstSpirit-GID des FirstSpirit-Elements und der Locale (Sprache und Land) zusammen.
    Hinweis: Die Projekteinstellungsseite verwendet als Bezeichner projectsettings anstelle der GID.

Gemeinsam mit der Basis-URL des CaaS-Endpunkts ergibt sich die vollqualifizierte URL eines Dokuments:

https://CAAS-BASE-URL/<tenant id>/<project identifier>.<collection identifier>/<document identifier>

Beispiel:

Die Tenant-ID lautet defaultTenant. Die FirstSpirit-Projekt-GID lautet e54cb80e-1f9c-4e8d-84b8-022f473202eb. Für die Vorschau einer Seite mit der GID f6910b22-6ae8-4ce1-af45-c7b364b3117a in englischer Sprache sieht die URL wie folgt aus:

https://CAAS-BASE-URL/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.content/f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB

Eine Übersicht aller Collection-URLs des Projekts erhalten Sie in diesem Kapitel.

4. Datenformat von CaaS-Dokumenten

Das CaaS-JSON-Format wird automatisch erzeugt, FirstSpirit-Templating wird hierbei nicht verwendet. Das CaaS-JSON-Format basiert auf dem toJson-Standard von FirstSpirit und wird vom CaaS Connect-Modul sowohl um CaaS-spezifische JSON-Format-Konfigurationen als auch um einige Attribute erweitert, die dessen Verwendung vereinfachen. Dies umfasst Funktionen wie die Reduzierung der Ausgabe von Datensätzen auf Referenzen, die indirekte Referenzierung von Datensätzen einer Content-Projektion und die Aktivierung der Ausgabe von FirstSpirit-Metadaten.

Das Format kann nicht angepasst werden. Diese Einschränkung ermöglicht es der CaaS-Plattform, ein vollständiges, standardisiertes Datenformat auszuliefern, sodass alle konsumierenden Endpunkte mit demselben Datenformat arbeiten können.

Wir raten dringend davon ab, eigene Dokumente, das heißt Dokumente mit einem abweichenden Datenformat, in den von CaaS Connect angelegten Collections zu erzeugen, um zu vermeiden, dass die Funktionalität anderer Features des CaaS Connect-Moduls beeinträchtigt wird oder Probleme für API-Nutzer entstehen.

Details zu den CaaS-spezifischen Attributen werden in den folgenden Abschnitten erläutert.

4.1. Datensatz-URLs

FirstSpirit adressiert einzelne Datensätze nicht, sondern arbeitet mit Content-Projektionen oder -Selects und bettet Datensätze in Seiten ein. In CaaS-Projekten werden einzelne Datensätze durch eine eindeutige URL identifiziert und können darüber abgefragt werden. Daher betten Seiten Datensätze nicht ein, sondern enthalten Referenzen auf die in der CaaS-Plattform gespeicherten Datensätze.

JSON-Ausschnitt: Beispiel einer Datensatz-Referenz in einem Seitendokument
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "entityType" : "product",
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products"
      },
      "url" : "https://CAAS-BASE-URL/<TENANT-ID>/<PROJECT-UUID>.preview.content/fae0687b-c365-4851-919e-566f4d587201.en_GB"
   }
}

4.2. Datensatz-Routen

Das Attribut routes ist ein Array, das alle verfügbaren Content-Projektionen eines Datensatzes als einzelne Objekte auflistet. Ein Datensatz besitzt mehrere Routen, wenn er Teil mehrerer Content-Projektionen ist und somit mehrere Vorschauseiten für diesen Datensatz verfügbar sind.

Das Attribut route ist veraltet und wurde durch das neue routes-Array ersetzt, wird aber aus Kompatibilitätsgründen weiterhin hinzugefügt.

Das Attribut pageRef ist die FirstSpirit-GID der zugehörigen Seitenreferenz.

JSON-Ausschnitt: Beispiel einer Route in einem Datensatz
{
  "routes": [
          {
            "pageRef": "39332e1e-0a42-4fb9-934a-dd3efe58cbc8",
            "route": "/Company/Press/Solar-systems-unveiled-at-Old-Trafford-stadium.html"
          },
          {
            "pageRef": "78dc7762-657b-4524-ab00-debbfd5e6d62",
            "route": "/Company/Solarnews/Solar-systems-unveiled-at-Old-Trafford-stadium.html"
          }
  ]
}

Weitere Informationen zur Erzeugung der Datensatz-Route finden Sie im Kapitel Alternative URL-Erzeugung.

4.3. PageRef-Routen

Das Attribut route enthält die mit der konfigurierten projektspezifischen URL Factory gerenderte URL einer Seitenreferenz (PageRef).

JSON-Ausschnitt: Beispiel einer Route in einer PageRef
{
  "fsType": "PageRef",
  "name": "news_overview",
  "route": "/Company/Press/Press-Overview.html"
}

Weitere Informationen zur Erzeugung der PageRef-Route finden Sie im Kapitel Alternative URL-Erzeugung.

4.4. Locale

Das Attribut locale enthält die Attribute identifier (Abkürzung der Sprache), country (zugehöriges Land) und language (zugehörige Sprache).

JSON-Ausschnitt: Beispiel einer Locale
{
    "locale": {
        "identifier": "EN",
        "country": "GB",
        "language": "en"
    }
}

4.5. Medienreferenzen

Medienreferenzen verweisen auf das zugehörige Dokument des Mediums. Die URLs zu den eigentlichen Binärdaten des Mediums befinden sich im referenzierten Dokument.

JSON-Ausschnitt: Beispiel einer Medienreferenz
{
   "st_header_image": {
        "fsType": "FS_REFERENCE",
        "name": "st_header_image",
        "value": {
            "fsType": "Media",
            "name": "header_home",
            "identifier": "b7fd2e2c-a022-44d6-ae2d-f0b9fd48f9a2",
            "uid": "header_home",
            "uidType": "MEDIASTORE_LEAF",
            "mediaType": "PICTURE",
            "url": "https://CAAS-BASE-URL/defaultTenant/631e4786-0dc3-4db6-bad8-adaad685944a.preview.content/b7fd2e2c-a022-44d6-ae2d-f0b9fd48f9a2.de_DE"
        }
    }
}

4.6. Content-Projektionen

Bei Verwendung der Standard-JSON-Konfiguration von FirstSpirit enthalten die JSON-Daten von Content-Projektionen bzw. deren Absätzen Referenzen auf die zugehörigen Datensätze. Das CaaS Connect-Modul verwendet jedoch eine spezifische Konfiguration für das JSON-Format, sodass die Datensätze nicht direkt, sondern indirekt über ein Query-Objekt referenziert werden. Hierzu enthält das Query-Objekt identifizierbare Attribute der Content-Projektion.

JSON-Ausschnitt: Beispiel einer Content-Projektion
{
   "displayName" : "blog",
   "entityType" : "blog",
   "filterParams" : {},
   "fsType" : "Content2Section",
   "maxPageCount" : 0,
   "name" : "blog",
   "ordering" : [
      {
         "ascending" : false,
         "attribute" : "fs_id"
      }
   ],
   "query" : null,
   "recordCountPerPage" : 1,
   "schema" : "global",
   "template" : {
      "displayName" : "Blog entry",
      "fsType" : "TableTemplate",
      "identifier" : "e657e0f0-0fd3-456f-b5ab-560a879ca748",
      "name" : "Blog entry",
      "uid" : "global.blog",
      "uidType" : "TEMPLATESTORE_SCHEMA"
   }
}

4.7. Fehlerhafte Referenzen

Ab FirstSpirit 2026.5 rendert FirstSpirit referenzierte Inhaltselemente, die nicht gerendert werden können — zum Beispiel weil sie noch nicht freigegeben sind — als unvollständiges Objekt mit brokenReference: true, anstatt sie vollständig wegzulassen. CaaS Connect fügt diesen unvollständigen Objekten ein url-Attribut hinzu, damit konsumierende Anwendungen das entsprechende CaaS-Dokument identifizieren und laden können, sobald es verfügbar ist.

Seitenreferenzen und Medienreferenzen tragen brokenReference: true direkt am Referenzobjekt:

JSON-Ausschnitt: Beispiel einer nicht veröffentlichten Seitenreferenz
{
   "fsType" : "PageRef",
   "brokenReference" : true,
   "identifier" : "b0ac2697-79b8-4c9e-a35c-fc7c4ba6212b",
   "url" : "https://CAAS-BASE-URL/<TENANT-ID>/<PROJECT-UUID>.preview.content/b0ac2697-79b8-4c9e-a35c-fc7c4ba6212b.en_GB"
}

Datensatz-Referenzen tragen brokenReference: true am inneren target-Objekt; das url-Attribut wird dem umschließenden value-Objekt hinzugefügt:

JSON-Ausschnitt: Beispiel einer nicht veröffentlichten Datensatz-Referenz in einem Seitendokument
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products",
         "brokenReference" : true
      },
      "url" : "https://CAAS-BASE-URL/<TENANT-ID>/<PROJECT-UUID>.preview.content/fae0687b-c365-4851-919e-566f4d587201.en_GB"
   }
}

4.8. Projekt-Mastersprache

Das Projekteinstellungsdokument besitzt das Attribut projectConfiguration mit dem Unterattribut masterLocale, in dem die Mastersprache des Projekts enthalten ist.

JSON-Ausschnitt: Beispiel der Projekt-Mastersprache
{
  ..,
  "projectConfiguration": {
    "masterLocale": "en_GB"
  }
}

Eine Änderung der Projekt-Mastersprache aktualisiert das Dokument in der CaaS-Plattform nicht automatisch. Um das Dokument zu aktualisieren, können die Projekt-Aufträge Total Sync für den Datenabgleich verwendet werden (siehe Kapitel Total Sync).

5. Konfigurationsoptionen

CaaS Connect bietet wichtige projektspezifische Konfigurationsoptionen, die in den folgenden Abschnitten beschrieben werden.

5.1. Alternative URL-Erzeugung

Zur Erzeugung von Medien-Binärdaten-URLs sowie der Routen für Datensatz- und PageRef-Dokumente wird eine URL Factory verwendet. Die Standard-URL-Factory ist Advanced URLs.

Die CaaS Connect Projekt-App erlaubt die Konfiguration einer alternativen URL Factory.
Bitte beachten Sie, dass die konfigurierte URL Factory für Medien-Binärdaten-URLs nur dann verwendet wird, wenn die Medien in S3 gespeichert werden (was im Crownpeak-SaaS-Angebot der Standard ist).

project app config urlfactory blurred
Abbildung 3. Konfigurationsdialog der CaaS Connect-Projekt-Komponente: Konfiguration der URL Factory

Wir empfehlen die Verwendung einer URL Factory, welche die FirstSpirit-Registry als Persistenz nutzt. 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 einer Änderung der Konfiguration der URL Factory ist es notwendig, alle CaaS-Inhalte zu überschreiben, damit die Änderungen wirksam werden. Hierzu empfehlen wir die Verwendung der Total Sync-Aufträge für den Datenabgleich (siehe Kapitel Datensynchronisierung).

5.2. Remote-Datensätze

CaaS Connect bietet die Möglichkeit, Referenzen für Datensätze zu verwenden, anstatt die Datensatzdaten in den Seitendokumenten einzubetten. Dies kann in der CaaS Connect Projekt-App konfiguriert werden.

project app config datasets blurred
Abbildung 4. Konfigurationsdialog der CaaS Connect-Projekt-Komponente: Remote-Datensätze

Durch die Verwendung von Referenzen für Remote-Datensätze im Projekt wird die Last bei der Verteilung von Datensätzen an die Zielprojekte vermieden, sodass Änderungen schneller sichtbar werden. In diesem Fall werden URLs, die auf Remote-Datensätze verweisen, direkt auf das Quellprojekt geleitet. Wir empfehlen diese Konfiguration zu verwenden.

Die generierten Collection-API-Keys, die Sie in der Oberfläche der Projekt-App sehen, sind projektspezifisch. Wenn Sie Remote-Datensatzreferenzen verwenden, können diese nicht auf Datensätze zugreifen, die sich in einem separaten Projekt befinden. Sie müssen manuell einen zusätzlichen API-Key mit den entsprechenden Berechtigungen für die referenzierten Projekte anlegen. Alternativ können die generierten GraphQL-API-Keys für erfolgreiche Abfragen der GraphQL-Apps verwendet werden, da sie nicht auf bestimmte Collections beschränkt sind.

5.3. Übertragene Auflösungen

Es ist möglich zu steuern, welche Auflösungen bei einer Generierung an die CaaS-Plattform übertragen werden. Dies wird erreicht, indem den gewünschten Auflösungen im FirstSpirit-Projekt Tags mit der Bezeichnung CaaS zugewiesen werden. Weitere Informationen zum Taggen von Auflösungen finden Sie in der FirstSpirit-Dokumentation für Administratoren.

Ist im ServerManager kein CaaS-Tag für das jeweilige Projekt konfiguriert, werden standardmäßig die zugehörigen Binärdaten für alle im Projekt vorhandenen Auflösungen übertragen.

Wir empfehlen dringend, die Anzahl der Auflösungen auf die tatsächlich benötigten zu beschränken, da dies die Laufzeit der Event-Verarbeitung und der Sync-Aufträge erheblich reduzieren kann.

Bei der Übertragung von Bildern in den CaaS berechnet FirstSpirit alle Auflösungen und speichert sie in einem Cache. Solange dieser Cache noch nicht gefüllt ist, ist die Laufzeit der Event-Verarbeitung und der Sync-Aufträge, insbesondere bei deren initialer Ausführung, extrem verzögert. Durch das Setzen des hier beschriebenen CaaS-Tags kann dieser Situation entgegengewirkt werden.

Beim Export von Projekten sollte zudem die Option "Automatisch berechnete Auflösungen exportieren" aktiviert bleiben, damit der Auflösungs-Cache nach dem Import bereits gefüllt ist.
add resolution tag
Abbildung 5. Hinzufügen eines neuen Tags

Im folgenden Beispiel werden nur drei Auflösungen in den CaaS übertragen.

resolution list
Abbildung 6. Auflistung der Projektauflösungen

Bitte beachten Sie, dass bereits übertragene Binärdaten durch nachträgliche Änderungen am Auflösungs-Tag nicht aus dem CaaS entfernt werden.

Außerdem werden die CaaS-Daten durch eine Änderung der CaaS-Tags nicht automatisch aktualisiert; eine Synchronisierung muss manuell über die Total Sync-Aufträge gestartet werden (siehe Kapitel Total Sync).

6. Aufträge für den Datenabgleich

Ein manueller Vollabgleich der Daten kann über die folgenden Aufträge erfolgen, die mit der Installation der CaaS Connect Projekt-App automatisch erstellt werden (siehe Aktivierung des Moduls).

Beide Aufträge entfernen nach einem erfolgreichen Lauf zudem veraltete Dokumente aus der CaaS-Plattform. Endet die Pipeline des Auftrags mit Fehlern, wird der Aufräum-Schritt übersprungen, um zu vermeiden, dass Dokumente gelöscht werden, die möglicherweise lediglich nicht aktualisiert werden konnten.

schedules sync
Abbildung 7. Sync-Aufträge des CaaS-Moduls

Änderungen an der Konfiguration dieser Aufträge sind nicht persistent, da die Aufträge bei Installation oder Aktualisierung der Projekt-Komponente in ihren Ursprungszustand zurückgesetzt werden. Sollen Änderungen an der Konfiguration dieser Aufträge persistent sein, müssen diese auf eine Kopie des jeweiligen Auftrags angewendet werden.

Abhängig von der Größe der Projekte und der daraus resultierenden Datenmenge kann die Laufzeit der Aufträge sehr lang sein. Dies trifft insbesondere auf die Total Sync-Aufträge zu. Faktoren sind neben der reinen Anzahl der Elemente im FirstSpirit-Projekt auch die Anzahl der Sprachen und insbesondere die Anzahl der Bild-Auflösungen.

Die Laufzeit für die Berechnung und Übertragung der Auflösungen kann durch die Konfiguration von CaaS-Tags signifikant reduziert werden, siehe Kapitel Übertragene Auflösungen.

6.1. Smart Sync

Die Aufträge

  • CaaS Connect - Smart Sync (fast, sends changed data) - PREVIEW und

  • CaaS Connect - Smart Sync (fast, sends changed data) - RELEASE

führen einen intelligenten Vollabgleich der Vorschau- bzw. Freigabe-Datenbestände zwischen FirstSpirit und der CaaS-Plattform durch. Dabei werden ausschließlich veraltete Dokumente angelegt oder aktualisiert. Zur Identifikation veralteter Dokumente werden die Revisionsinformationen der zugehörigen FirstSpirit-Elemente herangezogen.

In bestimmten Fällen werden nicht alle Dokumente aktualisiert, obwohl in FirstSpirit relevante Änderungen vorgenommen wurden. Um eine Aktualisierung dieser Dokumente zu erzwingen, müssen die CaaS Connect - Total Sync …​-Aufträge verwendet werden.

6.2. Total Sync

Die Aufträge

  • CaaS Connect - Total Sync (slow, sends all data) - PREVIEW und

  • CaaS Connect - Total Sync (slow, sends all data) - RELEASE

führen einen Vollabgleich der Vorschau- bzw. Freigabe-Datenbestände zwischen FirstSpirit und der CaaS-Plattform durch. Dabei werden Dokumente aller FirstSpirit-Elemente angelegt und aktualisiert (im Gegensatz zu den Smart Sync-Aufträgen), unabhängig von deren FirstSpirit-Revisionsinformationen.

6.3. Drosselung von Synchronisations-Aufträgen (nur CaaS Connect SaaS)

Synchronisations-Aufträge belasten den FirstSpirit-Server deutlich stärker als der reguläre ereignisbasierte Abgleich. Sie scannen sämtliche FirstSpirit-Elemente des Projekts und erzeugen dadurch zusätzliche Last auf CPU, Arbeitsspeicher und Datenbank. Der Total Sync-Auftrag erstellt darüber hinaus jedes Dokument in der CaaS-Plattform neu.
Synchronisations-Aufträge sind daher ausschließlich für die initiale Einrichtung und die Wiederherstellung nach Dateninkonsistenzen vorgesehen — nicht für den laufenden Betrieb.

Zum Schutz der Systemstabilität von FirstSpirit wird in Crownpeak-SaaS-Umgebungen zukünftig eine rollierende Drosselung dieser Aufträge eingeführt. Potenziell von dieser Drosselung betroffene Kunden werden proaktiv informiert, bis die Beschränkung tatsächlich in Kraft tritt.

Diese Drosselung gilt ausschließlich für Crownpeak-SaaS-Kunden.
Selbstgehostete FirstSpirit-Installationen laufen ohne konfiguriertes Limit.

Limit

Innerhalb eines rollierenden Zeitraums von 7 Tagen dürfen maximal 100.000 Dokumente synchronisiert werden. Jedes Dokument, das in der CaaS-Plattform aktualisiert wird, wird auf dieses Budget angerechnet. Total Sync-Aufträge aktualisieren jedes Dokument bedingungslos und verbrauchen somit Budget proportional zur Projektgröße.

Funktionsweise

Vor jeder Auftragsausführung prüft das System das rollierende Budget:

  • Ist Budget verfügbar, läuft der Auftrag bis zum Abschluss; ein laufender Auftrag wird niemals während der Ausführung unterbrochen.

  • Ist das Budget aufgebraucht, wird der Auftrag sofort mit Fehlerstatus abgelehnt und ein Log-Eintrag gibt an, wann das Budget wieder verfügbar sein wird.

Der aktuelle Budgetstand wird zu Beginn und zum Ende jedes Auftrags im Auftragsprotokoll festgehalten.

Ein einzelner großer Auftrag kann das gesamte Budget verbrauchen und nachfolgende Aufträge für den Rest des 7-Tages-Fensters blockieren. Wenden Sie sich in einem Notfall an den Customer Support, um eine Rücksetzung des Budgets zu beantragen.

7. Speicherung von Mediendateien

In der Crownpeak-SaaS-Umgebung werden die Binärdaten der Mediendateien in einem S3 Bucket gespeichert und können über ein Content Delivery Network (CloudFront Distribution Service) abgerufen werden. Für On-Premises-Installationen werden auch andere Hosting-Optionen unterstützt, weitere Informationen finden Sie in der Administrator-Dokumentation.

Für sprachunabhängige Medien wird genau eine Binärdatei übertragen. Für sprachabhängige Medien wird je eine Binärdatei pro Sprache des FirstSpirit-Projekts übertragen, die mit Sprache generieren markiert ist. Zusätzlich werden für Bilder die Binärdaten jeder Auflösung übertragen, sofern kein CaaS-Tag gesetzt wurde.

7.1. Zugriff auf Binärdaten

Ein Mediendokument enthält URL-Attribute, die auf die jeweiligen Binärdaten verweisen. Wo sich diese URL innerhalb des Mediendokuments befindet, hängt vom Medientyp ab.

Beispiel eines Mediendokuments:
Der folgende Codeausschnitt zeigt beispielhaft den Inhalt eines Mediendokuments vom Typ PICTURE, einschließlich der URLs, die auf die Binärdaten der einzelnen Auflösungen des Bildes verweisen. Ist in den Auflösungseinstellungen das CaaS-Tag gesetzt, werden im resolutionsMetaData-Objekt nur diese getaggten Auflösungen aufgeführt.

Beispiel: JSON eines Bild-Mediendokuments im Vorschaustand
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    "displayName": "thisisatest",
    "identifier": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61",
    "uid": "thisisatest",
    "uidType": "MEDIASTORE_LEAF",
    "fileName": "thisisatest",
    "languageDependent": false,
    "mediaType": "PICTURE",
    "description": null,
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png"
        },
        "Teaser": {
            "fileSize": 1192,
            "extension": "png",
            "mimeType": "image/png",
            "width": 111,
            "height": 65,
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest_Teaser.png"
        }
    },
    "metaFormData": {},
    "changeInfo": {
        "date": "2021-05-10T10:41Z",
        "revision": 21077
    },
    "locale": {
        "identifier": "EN",
        "country": "US",
        "language": "en"
    },
    "_etag": {
        "$oid": "60990def3542845893b034da"
    }
}

7.2. CloudFront-Caching

Bei Änderungen an den Binärdaten von Medien werden deren Dateien nicht sofort im Cache der CloudFront Distribution invalidiert. Stattdessen findet eine automatische Aktualisierung nach maximal 15 Minuten statt, sofern die CloudFront Distribution so konfiguriert ist, dass der Cache-Control-Header aus den HTTP-Antworten eines Origins berücksichtigt wird. In der Crownpeak-Cloud ist dies standardmäßig aktiv.

Weitere Informationen zum Cache-Control-Header finden Sie in den Informationen zum Caching in der Administrator-Dokumentation.

8. Sichtbarkeit von Absätzen

In FirstSpirit ist es möglich, Absätze auszublenden. Die Daten dieser Absätze werden je nach Vorschau- oder Freigabestand unterschiedlich behandelt.

In FirstSpirit ausgeblendete Absätze sind immer Teil der Vorschaudaten, jedoch niemals in den Freigabedaten enthalten. Die Vorschaudaten enthalten pro Absatz zusätzlich ein JSON-Attribut mit dem Namen displayed. Dieses zeigt an, ob der Absatz ein- oder ausgeblendet ist und somit, ob er als Teil der Freigabedaten in den CaaS übertragen wird.

Demnach ergeben sich folgende Möglichkeiten für Absätze:

Sichtbarkeit Teil des Vorschaustandes Wert von displayed im Vorschaustand Teil des Freigabestandes

Eingeblendet

Ja

true

Ja

Ausgeblendet

Ja

false

Nein

Bitte beachten Sie, dass das displayed-Attribut nur im Vorschaustand vorhanden ist. Im Freigabestand sind nur eingeblendete Absätze vorhanden, daher wird dieses Attribut dort nicht verwendet.

9. Push-Benachrichtigungen (Change Streams)

Häufig ist es wünschenswert, über Änderungen in der CaaS-Plattform informiert zu werden. Hierzu bietet die CaaS-Plattform Change Streams. Dieses Feature ermöglicht es, eine WebSocket-Verbindung zur CaaS-Plattform aufzubauen, über die Events zu den verschiedenen Änderungen publiziert werden.

Standardmäßig wird für jede vom CaaS Connect angelegte Collection ein crud-Change Stream bereitgestellt. Der Change Stream benachrichtigt alle verbundenen Clients über alle Change Events der Typen insert, replace, update und delete. Er ist unter <collectionUrl>/_streams/crud erreichbar. Die genaue Definition der Change Streams kann jederzeit in den Metadaten der Collection abgerufen werden.

Weitere Informationen zur Nutzung von Change Streams finden Sie in der CaaS-Plattform-Dokumentation.

10. Indizes

Um Dokumente aus der CaaS-Plattform über ein Attribut abzufragen, das nicht der Dokumentbezeichner ist, können Filter verwendet werden, in denen Kriterien für die zurückzugebenden Dokumente festgelegt sind.

Beispiel:
Um ein CaaS-Dokument (eine FirstSpirit-Seitenreferenz) mit dem Namen services abzurufen, wird mit der folgenden URL ein GET-Request ausgeführt:
https://CAAS-BASE-URL/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.content?filter={"name": "services"}

10.1. Automatisch angelegte Indizes

Die Performance solcher Filterabfragen kann durch die Verwendung von Indizes deutlich verbessert werden. Daher werden auf einigen vom CaaS Connect angelegten Collections automatisch verschiedene Indizes auf häufig genutzte Dokument-Attribute angelegt.

Folgende Indizes werden in den Collections preview.content und release.content für jedes Projekt angelegt:

  • idx_identifier_lang_country mit der Attribut-Kombination identifier, locale.language und locale.country

  • idx_entity_lang_country mit der Attribut-Kombination entityType, locale.language und locale.country

  • idx_fstype_lang_country mit der Attribut-Kombination fsType, locale.language und locale.country

  • idx_route mit dem Dokument-Attribut route

  • idx_routes_route mit dem Dokument-Attribut routes.route

  • idx_changeinfo_lastsynced mit dem Dokument-Attribut changeInfo.lastSynced

  • idx_fstype_template_uid mit der Attribut-Kombination fsType und template.uid

  • idx_fstype_page_template_uid mit der Attribut-Kombination fsType und page.template.uid

  • idx_fstype_media_type mit der Attribut-Kombination fsType und mediaType

Details zu allen existierenden Indizes können unter
https://CAAS-BASE-URL/<tenant id>/<project gid>.<preview|release>.content/_indexes/ abgerufen werden.

Die Reihenfolge der Index-Felder ist relevant. Bitte stellen Sie anhand der Datenbank-Dokumentation sicher, dass Ihre Filterabfragen so formuliert sind, dass die Indizes auch genutzt werden.

Weitere Informationen zu Indizes finden Sie in der CaaS-Plattform-Dokumentation.

10.2. Eigene Indizes

Sie können eigene Indizes über die REST API der CaaS-Plattform anlegen. Hierfür werden die folgenden Informationen benötigt:

  • ein autorisierter API-Key

  • eine Collection-URL

  • ein Indexname

  • ein Indexbody

Um das Erstellen eines Index zu vereinfachen, bietet CaaS Connect zudem das Executable CaasConnectCreateIndexExecutable an. Dieses erfordert lediglich die Angabe des Indexnamens und seines Bodys; die übrigen Parameter werden aus dem aufrufenden Kontext ermittelt.

Ein Anwendungsbeispiel für das Executable sind FirstSpirit-Generierungen. Es kann innerhalb von Generierungen in Skript-Aktionen verwendet werden.

#Executable class
com.espirit.caasconnect.executable.CaasConnectCreateIndexExecutable

Beispielhafte Parameterkonfiguration einer Skript-Aktion in einer FirstSpirit-Generierung

Name Wert

indexName

idx_page_lang

indexBody

{ "keys": { "page.uid": 1, "locale.language": 1 } }

Übergeben Sie in den Eigenschaften einer Generierung die Parameter aus der Tabelle oben, wird bei Ausführung der Generierung der folgende Index angelegt:

{
    "v": 2,
    "key": {
        "page.uid": 1,
        "locale.language": 1
    },
    "_id": "idx_page_lang"
}

Weitere Informationen zum Anlegen von Indizes finden Sie in der Dokumentation von RESTHeart.

Wenn die Indexerstellung aufgrund sehr großer Datenmengen im CaaS länger dauert, wird ein Fehler protokolliert. Es ist möglich, dass die Indexerstellung auch nach mehr als einer Stunde noch erfolgreich abgeschlossen wird.

11. Statusreport für CaaS-Dokumente

Sofern die WebComponent CaaS Connect Web App installiert ist, steht für Projektadministratoren ein Statusreport-Dialog im ContentCreator zur Verfügung.

Er dient der Überprüfung, ob ein FirstSpirit-Element im CaaS verfügbar ist und ob die Inhalte übereinstimmen. Er unterstützt Projektadministratoren beim Erkennen von Abweichungen, indem er für jede Sprach- und Datenstandkombination den aktuellen Status anzeigt. Zudem werden weiterführende Informationen, wie die zugehörigen Revisionen und Links zum CaaS-Dokument, bereitgestellt.

Derzeit werden folgende FirstSpirit-Elemente unterstützt:

  • Seitenreferenzen

  • Datensätze

  • Medien

Der Dialog ist für Seitenreferenzen über das Menü "Aktionen" erreichbar. Der Aufruf für Datensätze erfolgt über das Kontextmenü eines ausgewählten Elements innerhalb der Datensatzverwaltung. Analog dazu kann der Dialog über das Kontextmenü eines ausgewählten Mediums in der Medienverwaltung geöffnet werden. Der entsprechende Eintrag im Kontextmenü ist durch das Symbol saas sync gekennzeichnet.

caas document status
Abbildung 8. CaaS document status report im ContentCreator

Bitte beachten Sie, dass eine Abweichung zwischen Dokumenten 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 einige 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 werden, zählen ebenso wie Sync-Aufträge gegen das Drosselungslimit 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 Element 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 im Freigabestand des CaaS kein Dokument existieren kann.
Filter und Sortierung

Die Statusanzeige kann nach Sprache und Vorschau-/Freigabestand sortiert sowie 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 über Eventing oder einen Auftrag gestartet 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 Dokuments 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.

12. FirstSpirit GraphQL API

Das CaaS Connect-Modul unterstützt seit Version 3.25.10 die Erzeugung und Provisionierung der FirstSpirit GraphQL API. Ab Version 3.59.2 ist diese Funktion stabil und allgemein verfügbar.

Die FirstSpirit GraphQL API ermöglicht es, FirstSpirit-Inhalte mit GraphQL abzufragen, einschließlich Filterung, Sortierung und Paginierung. Die Möglichkeiten zur Abfrage von Inhalten sind somit nahezu identisch mit den Collection-Endpunkten der REST API.

12.1. API-Deployment/Provisionierung

Im Gegensatz zur REST API der CaaS-Plattform, die unabhängig vom CaaS Connect-Modul bereitgestellt wird, wird die FirstSpirit GraphQL API dynamisch vom CaaS Connect provisioniert. Dazu nutzt das CaaS Connect-Modul die Management-API für GraphQL-Applikationen der CaaS-Plattform.

Initiale (automatische) Provisionierung

Die FirstSpirit GraphQL APIs werden beim Service-Start sowie nach Installation/Aktualisierung der Projekt-Komponente erstmalig provisioniert, sofern die FirstSpirit GraphQL APIs noch nicht existieren.

Manuelle Provisionierung

Zur manuellen Provisionierung der APIs (z. B. nach Änderungen am Projektmodell) können die zugehörigen Auftragseinträge Deploy FirstSpirit GraphQL API oder das Executable CaasConnectGraphqlSyncExecutable verwendet werden.

schedules graphql
Abbildung 9. GraphQL-Aufträge des CaaS-Moduls

Wenn nicht abwärtskompatible Änderungen am Datenmodell des Projekts vorgenommen wurden, provisionieren und aktualisieren die Aufträge und das Executable die FirstSpirit GraphQL APIs dennoch. Dies kann dazu führen, dass die Abfragen von Konsumenten der APIs wegen Breaking Changes im Schema nicht mehr funktionieren.

Eine manuelle Provisionierung wird empfohlen, wenn Änderungen an den FirstSpirit-Templates vorgenommen wurden oder ein GCAPage-Template erstmalig verwendet wird. Eine regelmäßige Ausführung ist nicht notwendig.

12.2. URL-Endpunkte

Das CaaS Connect-Modul stellt jeweils eine separate GraphQL API für die Vorschau- und Freigabe-Inhalte bereit. Die URL-Endpunkte der API setzen sich aus den folgenden Elementen zusammen:

  • Basis-URL der CaaS-Plattform + /graphql-Pfad

  • Tenant-ID

  • Projekt-GID plus Suffix für Vorschau -preview-documents oder Freigabe -release-documents

Daraus ergibt sich der URL-Endpunkt:
https://CAAS-BASE-URL/graphql/<tenant id>___<project gid>-preview-documents|release-documents

Beispiel:
Ein Mandant mit der ID my-caas-dev kann die FirstSpirit GraphQL API für die Vorschau-Inhalte des Projekts mit der GID 631e4786-0dc3-4db6-bad8-adaad685944a über die folgende URL abfragen:

https://CAAS-BASE-URL/graphql/my-caas-dev___631e4786-0dc3-4db6-bad8-adaad685944a-preview-documents

Weitere Informationen zur Abfrage von Daten über die GraphQL API finden Sie im Kapitel GraphQL API der CaaS-Plattform-Dokumentation.

Der Konfigurationsdialog der Projekt-Komponente zeigt eine Übersicht aller FirstSpirit GraphQL API-URLs des Projekts an.

Das Tutorial Quickstart-Tutorial: FirstSpirit GraphQL API dient als schneller Einstieg in die Nutzung der FirstSpirit GraphQL API.

12.3. Schema

Das Schema der FirstSpirit GraphQL API wird dynamisch auf Basis des Datenmodells des Projekts generiert und ist dem Datenformat der JSON-Dokumente sehr ähnlich (siehe Kapitel Datenformat von CaaS-Dokumenten).

12.3.1. Query Fields (Einstiegspunkte)

Das generierte Schema enthält für die folgenden Inhaltstypen jeweils mindestens ein Query Field zur Abfrage mehrerer Dokumente (Collection Field):

  • PageRef

  • Dataset

  • Media

  • ProjectProperties

  • GCAPages

Die Query Fields werden automatisch auf Basis der Templates des Projekts generiert. Es ist nicht erforderlich, dass für diese Templates bereits Daten existieren. GCAPages werden jedoch anders behandelt: Hier werden Abfragen nur für bereits verwendete Templates generiert.

Jedes Query Field erlaubt zudem das Filtern, Sortieren und Paginieren der Ergebnisse über die Argumente filter, sort, skip und limit.

Für die Argumente filter und sort werden ausschließlich JSON-Dokumente (über GraphQL-Variablen) akzeptiert.

Das Format des Wertes entspricht dem des filter- bzw. sort-Query-Parameters der CaaS-Plattform REST API (siehe Kapitel Einsatz von Filtern der CaaS-Plattform-Dokumentation).

12.3.2. Eindeutigkeit von Typnamen

GraphQL-Typnamen werden aus den UIDs der Templates abgeleitet. Enthält ein Projekt zwei Templates, deren UIDs sich nur in der Groß-/Kleinschreibung unterscheiden (z. B. myTemplate und MyTemplate), würden beide normalerweise auf denselben GraphQL-Typnamen abgebildet. CaaS Connect löst diesen Konflikt durch Anhängen eines stabilen numerischen Suffixes: Das Template mit der niedrigsten FirstSpirit-ID behält seinen Typnamen unverändert; jedes weitere kollidierende Template erhält ein Suffix _1, _2 usw. (z. B. MyTemplate_1). Die Suffix-Zuweisung ist stabil gegenüber Verschiebe- und Umbenennungsoperationen, da sie auf der FirstSpirit-ID und nicht auf der Baumposition der Templates basiert.

Das Löschen eines Templates, das Teil einer UID-Kollisionsgruppe ist, ändert die Suffix-Zuweisung der verbleibenden Templates (z. B. kann MyTemplate_1 zu MyTemplate werden, sobald das konkurrierende Template entfernt wird). Dies ist eine brechende Änderung am GraphQL-Schema und führt zu einer Inkompatibilität mit bestehenden Client-Anwendungen, die die betroffenen Typen abfragen — diese Anwendungen müssen aktualisiert und neu ausgerollt werden.

12.3.3. Automatische Auflösung von Referenzen

Für alle Formularfelder, die Referenzen auf andere Dokumente enthalten, gibt es einen wesentlichen Unterschied zum Format der JSON-Dokumente. Konkret betrifft dies die folgenden Formularfeld-Typen:

  • FS_REFERENCE (nur PageRef- und Media-Referenzen)

  • FS_DATASET

  • FS_INDEX (nur DatasetDataAccessPlugin)

Die folgenden Felder dieser Typen enthalten nicht die Rohdaten der Referenz, sondern die Daten der referenzierten Dokumente (durch Auflösung der Referenzen):

  • value bei FS_REFERENCE

  • value.target bei FS_DATASET

  • value[].value bei FS_INDEX (nur mit DatasetDataAccessPlugin)

Bei FS_INDEX-Feldern, die ein anderes DAP als das DatasetDataAccessPlugin verwenden, werden die Index-Einträge als generisches JSON (BsonDocument-Skalar) ohne automatische Referenzauflösung dargestellt.

13. Fehlerbehandlung

Es gibt einige bekannte Probleme und Einschränkungen des CaaS Connect-Moduls, denen Sie bei der Arbeit mit dem Modul begegnen können.

13.1. Fehler beim Übertragen der Dokumente der Projekteinstellungsseite im Vollabgleich-Auftrag

Der Fehler ReferenceNotFoundException: No template defined for project properties kann während eines Vollabgleich-Auftrags auftreten, wenn in der Projektkonfiguration keine Projekteinstellungsvorlage definiert ist.

Dieses Problem wurde mit FirstSpirit Version 2023-04 behoben und kann entweder durch ein Update des FirstSpirit-Servers oder durch das Setzen einer Projekteinstellungsvorlage in der Projektkonfiguration gelöst werden.

13.2. Fehlende GID bei externen Datenbanken

In FirstSpirit-Projekten können externe Datenbanken verwendet werden. Diese Datenbanken können nur lesend eingebunden werden. Bei einer solchen Verwendung ist FirstSpirit jedoch nicht in der Lage, GIDs für die Elemente zu generieren. Ohne GID kann CaaS Connect diese Elemente nicht mit der CaaS-Plattform synchronisieren. Dies kann auch zu Fehlern bei den Synchronisierungs-Aufträgen führen.

Daher wird die Nutzung von CaaS Connect mit externen, nur lesbaren Datenbanken nicht unterstützt.

13.3. Push-Benachrichtigungen (Change Streams) funktionieren nicht

Jede vom CaaS Connect-Modul angelegte Collection sollte eine Change Stream-Definition für Push-Benachrichtigungen besitzen. Sollten die Definitionen fehlen, können sie durch Ausführen eines Auftrags wiederhergestellt werden.

14. Quickstart-Tutorial: FirstSpirit GraphQL API

Diese Anleitung beschreibt, wie FirstSpirit-Inhalte über die FirstSpirit GraphQL API abgefragt werden können.

Sie zeigt, wie eine GraphQL-Query definiert und schrittweise erweitert wird, um die wichtigsten Funktionen der FirstSpirit GraphQL API zu demonstrieren.

Voraussetzung für diese Anleitung ist…​

  • Zugriff auf ein FirstSpirit-Projekt, in dem das CaaS Connect-Modul aktiviert ist,

  • vorhandene Inhalte, die bereits mit der CaaS-Plattform synchronisiert wurden

  • sowie ein Tool oder eine IDE, das/die GraphQL unterstützt.

Anleitung

  1. Provisionierung der FirstSpirit GraphQL API
    Zuerst muss die aktuellste Version der FirstSpirit GraphQL API provisioniert sein. Hierzu können die Aufträge Deploy FirstSpirit GraphQL API für den Vorschau- und Freigabestand ausgeführt werden.

  2. URL des API-Endpunkts und API-Key
    Für die folgenden Schritte werden sowohl die URL eines API-Endpunkts als auch ein API-Key mit Leserechten benötigt. Diese können aus der Projekt-Komponente kopiert werden.

  3. Basis-Attribute einer PageRef abfragen

    Die folgende GraphQL-Query muss mit einem Tool oder einer IDE, das/die GraphQL unterstützt, an die zuvor ermittelte URL eines API-Endpunkts der FirstSpirit GraphQL API gesendet werden.

    Zur Authentifizierung der Anfrage muss der API-Key aus dem vorherigen Schritt im Authorization-Header im Bearer-Authentifizierungsschema angegeben werden.

    Die folgende Query fragt Basis-Attribute der PageRef-Inhalte ab.

    GraphQL-Query
    {
  pageRefs {
    displayName
    locale {
      identifier
    }
  }
}
    JSON Response Body
    {
  "data": {
    "pageRefs": [
      {
        "displayName": "Produkt Landingpage",
        "locale": {
          "identifier": "DE"
        }
      },
      {
        "displayName": "Product Landingpage",
        "locale": {
          "identifier": "EN"
        }
      }
    ]
  }
}

  4. Redaktionelle Inhalte abfragen
    Zusätzlich zu den Basis-Attributen verschiedener Inhalte können auch redaktionelle Inhalte abgefragt werden.

    Die folgende Query ermittelt beispielhaft die Headline aller PageRef-Dokumente vom Typ LandingPage.

    GraphQL-Query
    {
  pageRefs {
    displayName
    locale {
      identifier
    }
    page {
      ... on LandingPage {
        formData {
          pt_headline {
            value
          }
        }
      }
    }
  }
}
    JSON Response Body
    {
  "data": {
    "pageRefs": [
      {
        "displayName": "Produkt Landingpage",
        "locale": {
          "identifier": "DE"
        },
        "page": {
          "formData": {
            "pt_headline": {
              "value": "Testsieger 2013"
            }
          }
        }
      },
      {
        "displayName": "Product Landingpage",
        "locale": {
          "identifier": "EN"
        },
        "page": {
          "formData": {
            "pt_headline": {
              "value": "Test winner 2013"
            }
          }
        }
      }
    ]
  }
}

  5. Inhalte filtern
    Alle Query Fields unterstützen zusätzlich die Übergabe eines beliebigen Filters über das filter-Argument.

    Im folgenden Query-Beispiel werden die Ergebnisse so gefiltert, dass nur englische Inhalte zurückgegeben werden.

    GraphQL-Query
    query ($filter: BsonDocument) {
  pageRefs(filter: $filter) {
    displayName
    locale {
      identifier
    }
    page {
      ... on LandingPage {
        formData {
          pt_headline {
            value
          }
        }
      }
    }
  }
}
    GraphQL-Query-Variablen
    {
  "filter": {
    "locale.identifier": "EN"
  }
}
    JSON Response Body
    {
  "data": {
    "pageRefs": [
      {
        "displayName": "Product Landingpage",
        "locale": {
          "identifier": "EN"
        },
        "page": {
          "formData": {
            "pt_headline": {
              "value": "Test winner 2013"
            }
          }
        }
      }
    ]
  }
}

  6. Inhalte sortieren und paginieren
    Abschließend werden die Ergebnisse über die Argumente sort, skip und limit sortiert und paginiert.

    Die Ergebnisse werden anhand des Attributs page.formData.pt_headline.value aufsteigend sortiert.

    GraphQL-Query
    query ($filter: BsonDocument, $sort: BsonDocument) {
  pageRefs(filter: $filter, sort: $sort, skip: 5, limit: 5) {
    displayName
    locale {
      identifier
    }
    page {
      ... on Product_specialPage {
        formData {
          pt_headline {
            value
          }
        }
      }
    }
  }
}
    GraphQL-Query-Variablen
    {
  "filter": {
    "locale.identifier": "EN"
  },
  "sort": {
    "page.formData.pt_headline.value": 1
  }
}

Weitere Informationen zum Format der filter- und sort-Argumente finden Sie im Kapitel FirstSpirit GraphQL API → Schema.

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

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