1. Einleitung

Content as a Service stellt die redaktionellen Daten von FirstSpirit über ein einheitliches JSON-basiertes Datenformat beliebigen Endpunkten bereit. Dabei werden die Daten bei Änderung beziehungsweise Freigabe im FirstSpirit-Redaktionssystem transparent in der CaaS-Plattform aktualisiert. Bei einer Cloud-Installation der CaaS-Plattform sind die Daten damit effizient weltweit abrufbar. In FirstSpirit wird dabei ausschließlich auf die Formularkonfigurationen und die von der Redaktion gepflegten Daten zugegriffen. Das Templating in FirstSpirit entfällt völlig und wird auf das Front-End bzw. Front-End-Services verlagert (siehe Crownpeak PWA Template für eine Referenzimplementierung einer Progressive Web App).

Der FirstSpirit Entwickler kann sich somit vollständig auf das Modellieren der fachlichen Objekte und das Erstellen der zugehörigen Eingabekomponenten konzentrieren. Im Folgenden werden die Konventionen zu Datenformat und URLs beschrieben, als auch die optimale Aussteuerung von Inhalten für verschiedene Konsumenten.

Content as a Service wird im Folgenden als CaaS abgekürzt.

2. Einleitung FirstSpirit-Modul

Das CaaS Connect-Modul ist das Bindeglied zwischen FirstSpirit-Redaktionsumgebung und der ausliefernden CaaS-Plattform. Diese Verbindung ist für die Redaktion weitestgehend unsichtbar und bedarf nur im Falle eines technischen Problems der Beachtung. Den aktuellen Datenbestand kann die Redaktion immer direkt über die CaaS-Plattform einsehen. Sobald eine Änderung in FirstSpirit durchgeführt wurde, wird im Hintergrund der Abgleich ausgelöst, und der Datenbestand spiegelt umgehend die Änderung wider.

In FirstSpirit gibt es klassische Projekte und Fragmenteprojekte. Fachliche Seiten - und damit auch die Elemente, die in die CaaS-Plattform übertragen werden - entsprechen in klassischen Projekten den Seitenreferenzen und in Fragmenteprojekten den Fragmenten. Der Einfachheit halber sprechen wir in beiden Fällen von Seiten. Die Unterscheidung zwischen klassischem und Fragmenteprojekt nimmt das CaaS Connect-Modul automatisch vor.

2.1. CaaS-URLs

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

  • Seitenreferenzen

  • Medien

  • Globale Inhaltsseiten

  • Projekteinstellungsseite

  • Datensätze

Dabei wird für jede aktivierte Sprache des FirstSpirit Projekts und jeweils für den Vorschau- und Freigabestand ein Dokument für ein Element erzeugt. Jedes dieser Dokumente kann mit einer eindeutigen URL identifiziert und referenziert werden.

Sprachen gelten als aktiviert, sofern die Option Sprache generieren in der Konfiguration der Projektsprache aktiviert ist.

2.1.1. URL-Schema

Die CaaS-URL für ein Dokument setzt sich aus vier Teilen zusammen: Tenant-ID, Projektbezeichner, Collection-Bezeichner und Dokumentbezeichner. Die Tenant-ID ist der gepflegte Name oder Kürzel des Mandanten. Sie wird vom Serveradministrator im CaaS Connect Service eingepflegt. Der Projektbezeichner ist die GID des FirstSpirit-Projektes. Der Collection-Bezeichner ermöglicht die Unterscheidung von Freigabe- und Vorschaustand. Er enthält entweder den Wert release.content oder preview.content. Der Dokumentbezeichner setzt sich aus der FirstSpirit-GID des FirstSpirit-Elements und der Sprache zusammen. Gemeinsam mit der Basis-URL des CaaS-Endpunkts ergibt sich die vollqualifizierte URL eines Dokumentes.

CaaS-URLs für Projekteinstellungen verwenden als Dokumentenbezeichner nicht ihre FirstSpirit-GID, sondern den Bezeichner projectsettings.

Beispiel:

Die ID des Mandanten lautet defaultTenant.

Die FirstSpirit-Projekt-GID lautet e54cb80e-1f9c-4e8d-84b8-022f473202eb.

Die vollqualifizierte CaaS-URL einer Beispielseite mit der GID f6910b22-6ae8-4ce1-af45-c7b364b3117a in der Vorschau und für die Sprache Englisch sieht wie folgt aus:

http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.content/f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB

Die von CaaS Connect erzeugten Collections enthalten lediglich Dokumente in einem Standardformat (siehe Abschnitt Datenformat). Sowohl einige Features des CaaS Connect Moduls, als auch andere Nutzer der CaaS-Plattform API erwarten Dokumente mit diesem Format in diesen Collections. Um etwaige Probleme bei den Features des CaaS Connect Moduls und bei API Nutzern zu vermeiden wird von dem Anlegen eigener Dokumente in diesen Collections abgeraten.

Der Konfigurationsdialog der Projekt-Komponente zeigt eine Übersicht aller Collection-URLs des Projektes an.

2.2. Datenformat

Anders als klassische FirstSpirit-Projekte und frühere Modulversionen unterstützt CaaS Connect ab Version 3 keine Ausgabekanäle und somit kein FirstSpirit-Templating. Stattdessen wird für jede Seite des Projektes ein JSON-Dokument erzeugt, das auf dem toJson-Standard von FirstSpirit basiert. Eine Anpassung des Formats ist nicht möglich. Diese Einschränkung ermöglicht es, über die CaaS-Plattform ein vollständiges, standardisiertes Datenformat auszuliefern, sodass alle konsumierenden Endpunkte auf einer gemeinsamen Basis entstehen können. Da das Standarddatenformat sehr umfassend ist, bietet die Plattform Filter- und Aggregationsmöglichkeiten, um beispielsweise Datenaufkommen für mobile Endpunkte zu reduzieren. Weitere Informationen zur CaaS-Plattform finden Sie in der Produktdokumentation zur Plattform.

Da die CaaS-URLs den Dokumentbezeichner unter anderem aus einer eindeutigen FirstSpirit-ID ableiten, muss die Abfrage eines Dokumentes über dessen Namen mit einer Filterabfrage an die CaaS-Plattform passieren. Um eine CaaS-Seite (eine FirstSpirit-Seitenreferenz) mit dem Namen services abzufragen, wird mit folgender URL ein GET-Request ausgeführt:

http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.content?filter={'name': "services"}

Weitere Information zu Abfragen mit der CaaS-Plattform finden Sie in der Plattform-Dokumentation.

2.2.1. CaaS-JSON-Format

Das Standard-JSON-Format von FirstSpirit dient als Basis für das CaaS-JSON-Format und wird vom CaaS Connect-Modul sowohl mit CaaS spezifischer JSON-Format-Konfiguration als auch um einige Attribute erweitert, die dessen Verwendung vereinfachen. Die CaaS spezifischen Format-Konfigurationen beinhalten die Beschränkung der Ausgabe von Datensätzen auf Referenzen, die indirekte Referenzierung von Datensätzen einer Contentprojektionen sowie die Aktivierung der Ausgabe der FirstSpirit Metadaten.

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 sind einzelne Datensätze durch eine eindeutige URL identifiziert und können damit abgefragt werden. Seiten betten Datensätze deshalb nicht ein, sondern beinhalten Referenzen auf die gespeicherten Datensätze in der CaaS-Plattform.

JSON-Ausschnitt Beispiel 
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "entityType" : "product",
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products"
      }
   }
}

Das Attribut route wurde durch das neue routes-Array ersetzt, wird aber aus Kompatibilitätsgründen noch berechnet.

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

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

JSON-Ausschnitt Beispiel 
{
    "routes": [
          {
            "pageRef": "39332e1e-0a42-4fb9-934a-dd3efe58cbc8",
            "route": "/Unternehmen/Presse/Solaranlage-im-Old-Trafford-Stadion-eingeweiht.html"
          },
          {
            "pageRef": "78dc7762-657b-4524-ab00-debbfd5e6d62",
            "route": "/Unternehmen/Solarneuigkeiten/Solaranlage-im-Old-Trafford-Stadion-eingeweiht.html"
          }
    ]
}

Neue Datensatz-Routen werden im Vorschaufall immer von der UrlFactory erzeugt. Bereits existierende stored custom URLs werden im Vorschaufall berücksichtigt.

Seitenreferenz-Routen:
Das Attribut route enthält die mit der konfigurierten projektspezifischen URL Factory gerenderte URL einer Seitenreferenz.

JSON-Ausschnitt Beispiel 
{
  "fsType": "PageRef",
  "name": "news_overview",
  "route": "/Unternehmen/Presse/Presse-Übersicht.html"
}

Fragment-Metadaten:
Das Attribut fragmentMetaData beinhaltet die Attribute id (Fragmente-ID) und type (Fragmente-Typ).

JSON-Ausschnitt Beispiel 
{
    "fragmentMetaData": {
        "id": "378d5ec9_58f1_4dec_83bc_724dc93de5c2",
        "type": "news"
    }
}

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 
{
    "locale": {
        "identifier": "EN",
        "country": "GB",
        "language": "en"
    }
}

Medienreferenzen:
Referenzen auf Medien verweisen auf das zugehörige Dokument des Mediums. Die URLs zu den tatsächlichen Binärdaten des Mediums befinden sich innerhalb des referenzierten Dokuments.

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://some-caas-api/some-tenant/631e4786-0dc3-4db6-bad8-adaad685944a.preview.content/b7fd2e2c-a022-44d6-ae2d-f0b9fd48f9a2.de_DE"
        }
    }
}

Content2Section:
Die JSON-Daten von Contentprojektionen bzw. dessen Absätze enthalten in der Standard-JSON-Konfiguration von FirstSpirit Referenzen auf dessen Datensätze. Das CaaS Connect-Modul benutzt jedoch eine spezifische Konfiguration für das JSON-Format, sodass die Datensätze nicht direkt, sondern indirekt über ein Query-Objekt referenziert werden. Das Query-Objekt beinhaltet hierzu identifizierbare Attribute der Contentprojektion.

JSON-Ausschnitt Beispiel 
{
   "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"
   }
}

Projekt-Mastersprache:
Das Projekteinstellungsdokument hat das Attribut projectConfiguration mit dem Unterattribut masterLocale, in dem die Projekt-Mastersprache enthalten ist.

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

Die Veränderung der Projekt-Mastersprache bewirkt keine automatische Aktualisierung des Dokuments in der CaaS-Plattform. Um das Dokument zu aktualisieren, kann ein manueller Vollabgleich mit den Total Sync Aufträgen ausgeführt werden (siehe Kapitel Total Sync).

2.3. Vorschau- und Freigabestand

Eine wesentliche Unterscheidung zwischen Freigabe- und Vorschaudatenständen macht sowohl FirstSpirit als auch das CaaS Connect-Modul. Die Plattform führt beide Datenbestände, die durch unterschiedliche CaaS-URLs unterscheidbar sind (siehe URL-Schema). Ein Abgleich beider Bestände erfolgt immer auf bestimmte Aktionen, die die Redaktion in FirstSpirit vornimmt. Freigabeaktionen sind dabei die einzigen Aktionen, die eine Aktualisierung des Freigabestandes bewirken, alle anderen Änderungen haben nur Einfluss auf den Vorschaustand.

Projekt ohne "Freigabe nutzen"

Falls im FirstSpirit-Projekt die Freigabe ausgeschaltet wurde (siehe FirstSpirit Dokumentation zu Projekteigenschaften), werden nur Vorschaudatenstände in den CaaS übertragen. Um den Freigabestand zu aktualisieren, muss ein manueller Vollabgleich mit den CaaS Connect Aufträgen ausgeführt werden. Weiter Informationen können dem Kapitel Manueller Vollabgleich entnommen werden.

2.4. Manueller Vollabgleich

Inhaltsänderungen werden umgehend automatisch im Hintergrund zur CaaS-Plattform übertragen. Für bestimmte Szenarien kann es jedoch notwendig sein, einen Vollabgleich zwischen den Datenbeständen auszuführen:

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

  • Aktualisierung der Daten nach Änderung der Projektkonfigurationen oder Vorlagen- bzw. Formulardefinitionen

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

Der manuelle Vollabgleich der Datenbestände wird über folgende Aufträge ermöglicht, die automatisch mit der Installation der CaaS Connect Projekt-App angelegt werden. Alle CaaS Connect Aufträge stellen zusätzlich nach dem Anlegen/Aktualisieren der Dokumente sicher, dass veraltete Dokumente aus der CaaS-Plattform gelöscht werden.

schedules
Abbildung 1. Aufträge des CaaS-Moduls

Die Total Sync Aufträge löschen lediglich veraltete Dokumente, die mit der Version 3.38.0 (oder neuer) angelegt oder aktualisiert wurden. Um veraltete Dokumente zu löschen, die mit einer älteren Modulversion angelegt oder aktualisiert wurden, müssen einmalig die Smart Sync Aufträge ausgeführt 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.

2.4.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 CaaS-Plattform durch. Dabei werden ausschließlich alle fehlenden oder veralteten Dokumente angelegt bzw. aktualisiert. Zur Identifikation veralteter Dokumente werden die Revisionsinformationen der zugehörigen FirstSpirit-Elemente herangezogen.

In bestimmten Fällen kann es vorkommen, dass Dokumente nicht aktualisiert werden, obwohl Änderungen in FirstSpirit vorgenommen wurden. In solchen Fällen ist es notwendig, die CaaS Connect - Total Sync …​ Aufträge auszuführen (siehe unten).

2.4.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 CaaS-Plattform durch. Dabei werden (im Gegensatz zu den Smart Sync Aufträgen) die Dokumente aller FirstSpirit Elemente angelegt oder überschrieben (unabhängig der FirstSpirit-Revisionsinformationen).

2.5. Ausgeblendete Absätze

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 nie im Freigabestand enthalten. Die Vorschaudaten enthalten zusätzlich pro Absatz ein weiteres JSON-Attribut mit dem Namen displayed. Dieses zeigt an, ob der Absatz ein- oder ausgeblendet ist und demnach auch, ob dieser als Teil des Freigabestandes 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 und daher wird dieses Attribut dort nicht verwendet.

2.6. Push-Benachrichtigungen (Change Streams)

Es ist oft gewünscht, ü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, worüber Events zu den verschiedenen Änderungen publiziert werden.

Standardmäßig wird für jede von CaaS Connect angelegte Collection ein crud Change Stream angeboten. Der Change Stream benachrichtigt verbundene Clients über alle Change Events der Typen insert, replace, update und delete. Er ist unter <collectionUrl>/_streams/crud erreichbar. Die genaue Definition des Change Streams lässt sich jederzeit in den Metadaten der Collection abfragen.

Weitere Informationen zur Nutzung von Change Streams sind in der CaaS-Plattform Dokumentation verfügbar.

2.7. Indizes

Zur Abfrage von Dokumenten aus der CaaS-Plattform können Filter genutzt werden, in denen Kriterien für die zurückzugebenden Dokumente festgelegt sind. Um Filterabfragen auf häufig genutzte Dokument-Attribute zu beschleunigen, werden auf einigen von CaaS Connect angelegten Collections diverse Indizes erstellt. Informationen zu vorhandenen Indizes können unter <collectionUrl>/_indexes/ abgerufen werden.

Folgende Indizes werden in den Collections preview.content und release.content 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

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

Weitere Informationen zu Indizes sind in der CaaS-Plattform Dokumentation verfügbar.

2.8. FirstSpirit GraphQL API (EAP)

Das CaaS Connect Modul unterstützt seit Version 3.25.10 die Erzeugung und Provisionierung der FirstSpirit GraphQL API.

Die FirstSpirit GraphQL API ermöglicht es die FirstSpirit Inhalte mit GraphQL abzufragen (inklusive Filterung, Sortierung und Paginierung). Die Möglichkeiten zur Abfrage von Inhalten unterscheiden sich somit kaum von den Collection Endpunkten der REST API der CaaS-Plattform eines FirstSpirit Projekts.

2.8.1. URL-Endpunkte

Das CaaS Connect Modul provisioniert jeweils für den Vorschau- und Freigabestand eine GraphQL API. Die URL-Endpunkte der APIs setzen sich aus den folgenden Elementen zusammen:

  • Basis URL der CaaS-Plattform + /graphql Pfad
    z.B. https://my-caas-dev.e-spirit.cloud/graphql/..

  • Tenant-ID
    z.B. ../my-caas-dev/..

  • Projekt-GID + Vorschau-/Freigabestand-Suffix -preview-documents oder -release-documents
    z.B. ../631e4786-0dc3-4db6-bad8-adaad685944a-preview-documents

Folgende URL zeigt beispielhaft die vollständige URL einer FirstSpirit GraphQL API für die Vorschau-Inhalte eines Projektes:

https://my-caas-dev.e-spirit.cloud/graphql/my-caas-dev/631e4786-0dc3-4db6-bad8-adaad685944a-preview-content

Weitere Informationen zur Abfrage von Daten über die GraphQL API können dem Kapitel GraphQL API der CaaS-Plattform Dokumentation entnommen werden.

Der Konfigurationsdialog der Projekt-Komponente zeigt eine Übersicht aller FirstSpirit GraphQL API URLs des Projektes an (siehe Kapitel Projekt-Komponente der Administrator Dokumentation).

Das Tutorial Quickstart: FirstSpirit GraphQL API dient als schneller Einstieg für die Benutzung der FirstSpirit GraphQL API.

2.8.2. Schema

Das Schema der FirstSpirit GraphQL API wird dynamisch auf Basis des Datenmodells des Projektes generiert und entspricht dem Datenformat der JSON-Dokumente (siehe Kapitel Datenformat).

Query Fields (Einstiegspunkte)

Das generierte Schema enthält jeweils für die Inhaltstypen

  • PageRef

  • Dataset

  • Media

  • ProjectProperties

  • GCAPages

mindestens ein Query Field zur Abfrage mehrerer Dokumente (Collection Field) des Inhaltstyps.

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

Für die Argumente filter und sort wird ausschließlich ein JSON-Dokument (per GraphQL Variable) akzeptiert.

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

Automatisches Auflösen von Referenzen

Ein wesentlicher Unterschied zum Format der JSON-Dokumente existiert jedoch bei allen Formularfeldern, die Referenzen zu anderen Dokumenten beinhalten. Konkret betrifft das folgende Formularfelder-Typen:

  • FS_REFERENCE (nur PageRef- und Media-Referenzen)

  • FS_DATASET

  • FS_INDEX (nur DatasetDataAccessPlugin)

Formularfelder dieser Typen enthalten im jeweils relevanten Feld

  • value bei FS_REFERENCE

  • value.target bei FS_DATASET

  • value[].value bei FS_INDEX

nicht die Rohdaten der Referenzen, sondern die Daten der referenzierten Dokumente (durch die Auflösung der Referenzen).

2.8.3. API Deployment/Provisionierung

Im Gegensatz zur REST API der CaaS-Plattform, die unabhängig vom CaaS Connect Modul provisioniert wird, wird die FirstSpirit GraphQL API dynamisch vom Modul provisioniert.

Das CaaS Connect Modul nutzt zur Provisionierung der GraphQL API die Management-API zur Verwaltung von GraphQL-Applikationen der CaaS-Plattform.

Automatische Provisionierung

Die FirstSpirit GraphQL APIs werden bei jedem Service-Start und nach Installation/Aktualisierung der Projekt-Komponente provisioniert, sofern die FirstSpirit GraphQL APIs noch nicht existieren.

Manuelle Provisionierung

Zur manuellen Provisionierung der APIs können entweder die zugehörigen vorinstallierten Aufträge Deploy FirstSpirit GraphQL API oder das Executable CaasConnectGraphqlSyncExecutable genutzt werden.

Wenn nicht abwärtskompatibele Änderungen im Datenmodell des Projektes gemacht wurden, führen die Aufträge und die Executable trotzdem eine Provisionierung aus und aktualisieren die FirstSpirit GraphQL APIs. Dies kann dazu führen, dass die Abfragen von Konsumenten der APIs durch Breaking Changes im Schema nicht mehr funktionieren.

Die Query Fields, die automatisch angelegt werden, basieren auf den Templates. Es ist nicht notwendig, dass bereits Daten für diese Templates hinterlegt sind. Hierbei gibt es allerding eine Ausnahme bei den GCAPages. Hier werden die Abfragen nur für verwendete Templates erzeugt. Sollten also bereits Templates für GCAPages existieren, die aber noch nicht verwendet werden, ist es notwendig das Schema zu aktualisieren, wenn diese Templates zum ersten mal verwendet werden.

3. Bereitstellung der Medienbinärdaten

Das CaaS Connect-Modul unterstützt verschiedene Optionen, um die Binärdaten von Medien bereitzustellen.

  • Übertragung der Binärdaten in einen S3-Bucket und Bereitstellung über eine CloudFront-Distribution (CloudFront CDN).

    • Dies ist der Standard in der Crownpeak-Cloud.

  • Übertragung der Binärdaten in einen S3-Bucket und Bereitstellung über eine S3 REST API.

  • Übertragung der Binärdaten in File Buckets der CaaS-Plattform und Bereitstellung über die CaaS REST API.

    • Dies ist der Standard, wenn keine S3 Konfiguration existiert.

Die Optionen haben unterschiedliche Verwendungen und werden deshalb im Folgenden einzeln erläutert.

Die Anzahl der Mediendateien, die in das Zielsystem übertragen werden, ist jedoch bei allen Bereitstellungsoptionen identisch. Für sprachunabhängige Medien wird genau eine Binärdatei übertragen. Für sprachabhängige Medien wird für jede aktivierte Sprache eine Binärdatei übertragen. Außerdem werden für Bilder die Binärdaten jeder Auflösung übertragen, falls kein CaaS-Tag gepflegt worden ist (Siehe Exklusion bestimmter Auflösungen).

Sprachen gelten als aktiviert, sofern die Option Sprache generieren in der Konfiguration der Projektsprache aktiviert ist.

3.1. Übertragung in S3-Bucket

Diese Option beinhaltet das Übertragen der Mediendateien in einen S3-Bucket. Dabei werden die Binärdateien innerhalb des Buckets unter dem konfigurierten Pfad-Präfix abgelegt (Standard ist Präfix /). Anschließend folgt dem Pfad die GID des Projekts und das Pfad-Segment /preview, abhängig davon, ob sich das Medium im Freigabe- oder Vorschaustand befindet. Der restliche Pfad und der Dateiname einer Mediendatei ergeben sich aus der Advanced URL des Mediums.

Beispiel eines S3-Pfades: /631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png

Bei der Verwendung eines S3-Buckets können die Mediendateien entweder über eine CloudFront-Distribution oder direkt über den zugehörigen Endpunkt der S3 REST API bereitgestellt werden. Die folgenden Kapitel beschreiben diese zwei Bereitstellungsmöglichkeiten.

3.1.1. Bereitstellung über CloudFront-Distribution

Bei der Bereitstellung über eine CloudFront-Distribution setzt sich die URL zu einer Mediendatei aus der Domain der CloudFront-Distribution und dem oben beschriebenen Pfad des S3-Objekts zusammen.

Die folgende URL zeigt beispielsweise auf die Originalauflösung eines Bilds des Vorschaustands, welches über eine CloudFront-Distribution erreichbar ist, die für Domain my-cloudfront-domain.tld den S3-Bucket nutzt.

https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png

Der folgende Codeausschnitt zeigt beispielhaft den Inhalt eines Mediendokuments inklusive der URLs, die auf die Binärdaten der einzelnen Auflösungen des Bilds verweisen.

Wird in den Projekteinstellungen das CaaS-Tag in den Auflösungen gesetzt, werden auch nur diese im resolutionsMetaData-Objekt aufgeführt.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem 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"
    }
}

Neue Mediendatei-URLs werden im Vorschaufall immer von der UrlFactory erzeugt. Bereits vorhandene stored custom URLs werden daher nicht im Vorschaufall berücksichtigt!

CloudFront Caching

Bei Änderungen an den Binärdaten von Medien werden dessen Dateien nicht instantan in dem 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.

Genauere Informationen zu dem Cache-Control Header sind dem Abschnitt S3-Objekt-Metadaten zu entnehmen.

3.1.2. Bereitstellung über S3 REST API

Bei der Bereitstellung über die S3 REST API setzt sich die URL zu einer Mediendatei aus (dem virtuell gehosteten Endpunkt des Buckets) der S3 REST API und dem oben beschriebenen Pfad des S3-Objekts zusammen.

Die folgende URL zeigt beispielsweise auf die Originalauflösung eines Bilds des Vorschaustands im S3-Bucket my-bucket, der sich in der Region eu-central-1 befindet.

https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png

Der folgende Codeausschnitt zeigt beispielhaft den Inhalt eines Mediendokuments inklusive der URLs, die auf die Mediendaten der einzelnen Auflösungen des Bildes verweisen.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem Vorschaustand 
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png"
        },
        "Teaser": {
            ...
            "url": "https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest_Teaser.png"
        }
    },
    ...
}

3.1.3. S3-Objekt-Metadaten

Beim Upload der Mediendateien in den S3-Bucket werden unterschiedliche Metadaten-Attribute für das S3-Objekt gesetzt:

  • Content-Type

    • Dieses Attribut wird für den Response Header Content-Type für Requests an das S3-Objekt genutzt.

    • Es beinhaltet den MIME-Type der Mediendatei (z.B. image/png).

  • Cache-Control

    • Dieses Attribut wird für den Response Header Cache-Control für Requests an das S3-Objekt genutzt.

    • Für den Freigabestand beinhaltet es im Standard den Wert public, max-age=300, s-maxage=900.

    • Für den Vorschaustand beinhaltet es den Wert private, no-cache.

3.2. Übertragung in CaaS File Bucket und Bereitstellung über CaaS REST API

In diesem Modus werden die Binärdaten von Medien in den CaaS übertragen. Dabei werden die Binärdateien der Medien in das CaaS File Bucket

  • [Projekt-GID].release.files oder

  • [Projekt-GID].preview.files

übertragen, abhängig davon, ob diese sich im Freigabe- oder Vorschaustand befinden. Die File Buckets befinden sich dabei in der Datenbank, die der Tenant-ID entspricht. Der restliche Pfad und der Dateiname einer Mediendatei ergibt aus der FirstSpirit-GID des Mediums sowie Sprache und/oder Auflösung (sofern das Medium abhängig von Sprache und/oder Auflösung ist).

Die Bereitstellung der Mediendaten erfolgt über die CaaS REST API. Die URL zu einer Mediendatei setzt sich aus der Basis-URL der CaaS REST API, dem (oben beschriebenen) Pfad und dem Suffix /binary zusammen.

Der folgende Codeausschnitt zeigt beispielhaft den Inhalt eines Mediendokuments inklusive der URLs, die auf die Mediendaten der einzelnen Auflösungen des Bilds verweisen.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem Vorschaustand 
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-caas-url.tld/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.ORIGINAL/binary"
        },
        "Teaser": {
            ...
            "url": "https://my-caas-url.tld/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.Teaser/binary"
        }
    },
    ...
}

3.3. Steuerung der zu übertragenden Auflösungen mittels CaaS-Tag

Durch die optionale Vergabe des CaaS-Tags lässt sich steuern, welche Auflösungen bei einer Generierung in einen File Bucket bzw. S3-Bucket übertragen werden.

add resolution tag
Abbildung 2. Konfigurationsdialog eines neuen Tags

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

resolution list
Abbildung 3. Auflistung der Projektauflösungen

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

Mehr Informationen über das Taggen von Auflösungen können der FirstSpirit-Dokumentation für Administratoren entnommen werden.

Bitte beachten Sie, dass übertragene Binärdaten durch Änderungen an dem CaaS-Tag nicht aus dem CaaS entfernt werden.

Bei einer Änderung der CaaS-Tags werden die CaaS-Daten nicht automatisch aktualisiert; Eine Synchronisierung muss manuell durchgeführt werden.

3.4. URL Anpassungen (CaaS Connect SaaS)

In dem CaaS Connect SaaS Angebot werden Mediendateien durch eine CloudFront Domain (*-media.e-spirit.cloud) in einem standardisierten Format (siehe Bereitstellung über CloudFront-Distribution) bereitgestellt. Wenn dieses Format der URLs nicht gewünscht ist, können die API Consumer des CaaS URLs im gewünschten Format erzeugen und weiterverarbeiten. Zusätzlich muss eine serverseitige Komponente die Um- bzw. Weiterleitung der Requests übernehmen. In dem folgenden Abschnitt wird das Erzeugen eigener URLs Schritt für Schritt anhand von Beispielen erklärt.

API Consumer

API Consumer, die Daten von der CaaS API auslesen und weiterverarbeiten, können das Attribut seoRoute aus CaaS Mediendokumenten nutzen, um die gewünschte URL zusammenzustellen.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem Vorschaustand 
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-customer-name-media.e-spirit.cloud/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png",
            "seoRoute": "/FirstSpirit/Bilder/thisisatest.png"
        },
        ...
    },
    ...
}

Dieser Pfad kann einer gewünschten Domain (und ggf. Pfad-Präfix) angehangen werden. Im folgenden Beispiel wird der Pfad ohne Präfix an die gewünschte Domain angehangen:

https://de-de.my-custom-domain.tld + /FirstSpirit/Bilder/thisisatest.png

Server

Damit diese URLs aufrufbar sind, kann eine Serverkomponente genutzt werden, die entweder Umleitungen z.B. per Reverse Proxying oder Weiterleitungen per URL Redirect anwendet.

In dem folgenden Konfigurationsbeispiel wird ein NGINX Server genutzt und konfiguriert, sodass Requests auf Basis des angefragten Hostnames umgeleitet werden (Name-based virtual hosting und URL Rewrite). Dabei werden alle eingehenden Requests für den Hostname de-de.my-custom-domain.tld auf die Vorschaudaten eines FirstSpirit Projekts mit der UUID 631e4786-0dc3-4db6-bad8-adaad685944a umgeleitet (was dem Pfad /631e4786-0dc3-4db6-bad8-adaad685944a/preview entspricht).

Beispiel: Teilinhalt einer NGINX Konfiguration de-de.my-custom-domain.tld.conf 
server {
    listen              443 ssl http2;
    listen              [::]:443 ssl http2;
    server_name         de-de.my-custom-domain.tld;

    # SSL
    ssl_certificate     /etc/nginx/ssl/de-de.my-custom-domain.tld.crt;
    ssl_certificate_key /etc/nginx/ssl/de-de.my-custom-domain.tld.key;

    # security
    include             nginxconfig.io/security.conf;

    location / {
        proxy_pass https://my-customer-name-media.e-spirit.cloud/631e4786-0dc3-4db6-bad8-adaad685944a/preview/;
        include    nginxconfig.io/proxy.conf;
    }

    # additional config
    include nginxconfig.io/general.conf;
}

# HTTP redirect
server {
    listen      80;
    listen      [::]:80;
    server_name .de-de.my-custom-domain.tld;
    return      301 https://de-de.my-custom-domain.tld$request_uri;
}

Dieses Beispiel ist NICHT VOLLSTÄNDIG und dient lediglich zur Erläuterung des Name-based virtual hostings mit URL Rewrite. Zusätzliche NGINX Konfigurationen (z.B. Security Header, Proxykonfigurationen, …​), dessen Nutzung für den Produktionsbetrieb empfohlen ist, sind NICHT in diesem Beispiel vorhanden.

Dieses Beispiel nutzt einen NGINX als Reverse Proxy zur Umleitung der Requests. Dabei ist zu beachten, dass die Vorteile wie Caching und Edge Locations des Crownpeak Technology GmbH CloudFront CDNs nur genutzt werden können, wenn der NGINX Server in einem Edge-Computing Netzwerk betrieben wird. Alternativ sollte der Server so nah wie möglich zu der CloudFront Edge Location betrieben werden, die für den Usertraffic infrage kommt.

Zusätzlich muss beachtet werden, dass sogar bei der Verwendung einer Edge-Computing Lösung die genannten Vorteile des CloudFront CDNs nicht vollständig genutzt werden, sofern sich die Lösung in einem anderen CDN Netzwerk befindet. Wenn diese Einschränkungen umgangen werden sollen, muss eine Lösung im CloudFront CDN gewählt werden (z.B. CloudFront Distribution oder Lambda@Edge).

4. Fehlerbehandlung: Bekannte Fehler

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

Der Fehler ReferenceNotFoundException: No template defined for project properties kann während eines Vollabgleich-Auftrags auftauchen, sofern im Projekt keine Vorlage als Projekteinstellungsseite ausgewählt ist.

Dieser Fehler ist ab FirstSpirit Version 2023-04 behoben und kann somit durch ein Update des FirstSpirit Servers oder das Setzen einer Vorlage als Projekteinstellungsseite gelöst werden.

5. Tutorials

5.1. Quickstart: FirstSpirit GraphQL API

Diese Anleitung beschreibt das Abfragen von FirstSpirit Inhalten über die FirstSpirit GraphQL API.

In den folgenden Schritten wird beispielhaft eine GraphQL Query definiert und schrittweise erweitert, um die wichtigsten Features der FirstSpirit GraphQL API zu demonstrieren.

Voraussetzung für die Anleitung ist..

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

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

  • und ein Tool oder IDE die GraphQL unterstützt.

Anleitung

  1. Provisionierung der FirstSpirit GraphQL API
    Zuerst muss sichergestellt sein, dass die aktuellste Version der FirstSpirit GraphQL API provisioniert ist. Dazu müssen die Aufträge Deploy FirstSpirit GraphQL API jeweils für den Vorschau- und Freigabestand ausgeführt werden.

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

  3. Basis-Attribute einer PageRef abfragen

    Die folgende GraphQL Query kann mit einem Tool oder IDE die GraphQL unterstützt an die zuvor kopierte URL eines API Endpunkts der FirstSpirit GraphQL API gesendet werden.

    Zur Authentifizierung muss der zuvor kopierte API Key im Authorization Header in dem 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. Redaktionalle Inhalte abfragen
    Zusätzlich zu den Basis-Attributen verschiedener Inhalte können auch redaktionelle Inhalte abgefragt werden.

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

    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 Angabe eines arbiträren Filter ü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
    Im letzten Schritt werden die Ergebnisse beispielhaft sortiert und paginiert mit den Argumenten sort, skip und limit.

    Die Ergebnisse werden dabei aufsteigend anhand des Attributs page.formData.pt_headline.value 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
  }
}

Genauere Informationen zum Format der filter und sort Argumente können dem Kapitel FirstSpirit GraphQL API → Schema entnommen 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.

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.