1. Einleitung

CaaS stellt die redaktionellen Daten von FirstSpirit über ein einheitliches JSON-basiertes Datenformat beliebigen Endpunkten bereit. Die Daten werden dabei transparent bei Änderung beziehungsweise bei Freigabe im FirstSpirit Redaktionssystem 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 (für weitere Informationen siehe FSXA-Dokumentation).

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

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:

CaaS-Endpunkt: http://localhost:8080

CaaS-URL: defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB

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 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:

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 Refenzierung 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"
      }
   }
}

Datensatz-Routen: Das Attribut route beinhaltet die relative Route eines Datensatzes. Diese Route wird nur berechnet, wenn für die zugrundeliegende Tabellenvorlage eine Vorschauseite ausgewählt wurde. Die Vorschauseite sollte eine Content-Projektion für die dargestellte Tabelle sein und die Einstellung "Anzahl der Einträge pro Seite" sollte "1" sein (siehe Content Projektion). Nur so erhalten unterschiedliche Datensätze auch unterschiedliche Routen.

JSON-Ausschnitt Beispiel
{
    "route" : "/Unternehmen/Standorte/Standorte.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"
   }
}

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.

2.4. Manueller Vollabgleich

Für bestimmte Szenarien kann es notwendig sein, einen Vollabgleich zwischen den Datenbeständen auszuführen:

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

  • Abgleichen der Daten im Fehlerfall, um Datenkonsistenz zwischen den Systemen manuell wiederherzustellen

Dieser manuelle Vollabgleich der Datenbestände wird über Aufträge ermöglicht, die automatisch mit der Installation des CaaS Connect-Moduls angelegt werden. Dabei enthält das Projekt zwei Aufträge CaaS Connect Release Generation und CaaS Connect Preview Generation, die einen Vollabgleich für den Freigabe- oder Vorschaustand ausführen können. Die Aufträge werden bei einer Aktualisierung des CaaS Connect-Moduls aktualisiert.

schedules
Abbildung 1. Konfigurationsdialog der Projekt-Komponente des CaaS-Moduls

Änderungen an der Konfiguration dieser Aufträge sind nicht persistent, da die Aufträge durch die automatische Aktualisierung wieder auf den Ursprungszustand zurückgesetzt werden. Sind Änderungen an den Aufträgen notwendig, so können diese auf einer Kopie der Aufträge angewandt werden.

2.4.1. Überschreiben des kompletten Datenbestands

Sofern Änderungen im FirstSpirit Projekt keine Aktualisierung der Daten im CaaS auslösen, dies aber für alle Daten gewünscht ist, können die Aufträge zum Überschreiben des kompletten Datenbestands des CaaS genutzt werden. Hierzu ist es notwendig, den jeweiligen Auftrag zu kopieren und dessen Konfiguration anzupassen, sodass der Parameter replicationMode des Skript Tasks den Wert FULL enthält (im Gegensatz zum Standardwert DELTA). Ein Ausführen dieses Auftrags überschreibt dann den kompletten Datenbestand im CaaS.

full replication
Abbildung 2. Konfigurationsdialog des Auftrags

2.4.2. 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.5. 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. Dieser publiziert die sämtliche insert, replace, update und delete Events. 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.6. 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

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.

3. Bereitstellung der Mediendaten

Das CaaS Connect-Modul unterstützt verschiedene Optionen um die Daten 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 e-Spirit Cloud.

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

  • Übertragung der Binärdaten in File Buckets des CaaS 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 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).

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