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 kleinste adressierbare Element in einem CaaS-Projekt ist eine Seite. Das Modul erzeugt für jede Seite und jede Sprache in Vorschau- und Freigabestand ein Element in der CaaS-Plattform. Neben Seiten werden auch Medien abgeglichen. Bilder werden mit allen Projektsprachen und Auflösungen ausmultipliziert, während sonstige Medien für alle Sprachen übertragen werden. Jedes dieser Elemente kann mit einer eindeutigen URL identifiziert und referenziert werden.

2.1.1. URL-Schema

Die CaaS-URL für ein Element 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. Für Seitendokumente und Metadatendokumente von Medien ist er entweder release.content oder preview.content. Der Dokumentbezeichner setzt sich zusammen aus der FirstSpirit-GID der Seite, sowie Sprache und Auflösung. Gemeinsam mit der Basis-URL des CaaS-Endpunkts ergibt sich die vollqualifizierte URL eines Elements.

Das URL-Schema für Binärdaten von Medien unterscheidet sich minimal zu dem aufgeführten URL-Schema und ist deshalb separat im Kapitel Medien-URLs beschrieben.

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

Zur besseren Orientierung werden im Konfigurationsdialog der Projekt-Komponente alle Collection-URLs des Projektes angezeigt.

2.1.2. Medien-URLs

Für jedes Medium werden zwei Arten von Dokumenten erzeugt, die in der CaaS-Plattform abgefragt werden können: Metadaten und Binärdaten.

Metadatendokument
Für ein gegebenes Medium wird genau ein Metadatendokument für jede Projektsprache erzeugt (unabhängig davon, ob das Medium sprachabhängig ist oder nicht). Dieses wird immer in der CaaS-Plattform mit einer CaaS-URL abgelegt. Es beinhaltet die FirstSpirit-Metadaten des Mediums, sowie eine Auflistung der Auflösungen und zugehörige auflösungsspezifische URLs. Die URL für die Binärdaten eines bestimmten Mediums für eine bestimmte Sprache, und eventuell eine bestimmte Auflösung, ist zwingend aus diesem Metadatendokument zu entnehmen.

Für den Fall, dass die CaaS-Plattform zur Bereitstellung der Medienbinärdaten genutzt wird, wird das gleiche URL-Schema wie für Seiten- oder Metadatendokumente benutzt. Lediglich der Collection-Bezeichner unterscheidet sich und für den Freigabe- oder Vorschaustand wird entweder release.files oder preview.files benutzt.

{
    "_id": "f6910b22-6ae8-4ce1-af45-c7b364b3117a.de_DE",
    "fsType": "Media",
    "name": "audio_video_connector",
    "displayName": "Anschlusskabel für Audio und Video",
    "identifier": "f6910b22-6ae8-4ce1-af45-c7b364b3117a",
    "uid": "audio_video_connector",
    "uidType": "MEDIASTORE_LEAF",
    "fileName": "audio-video-connector",
    "languageDependent": false,
    "mediaType": "PICTURE",
    "description": "Innerhalb dieses Demoprojektes \"Mithras Energy\" werden ...",
    "resolutionsMetaData": {
        "110x73": {
            "fileSize": 3885,
            "extension": "jpg",
            "mimeType": "image/jpeg",
            "width": 110,
            "height": 73,
            "url": "http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.110x73/binary"
        },
        "ORIGINAL": {
            "fileSize": 69597,
            "extension": "jpg",
            "mimeType": "image/jpeg",
            "width": 693,
            "height": 462,
            "url": "http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.ORIGINAL/binary"
        }
    },
    "metaFormData": {},
    "locale": {
        "identifier": "DE",
        "country": "DE",
        "language": "de"
    },
    "_etag": {
        "$oid": "5f23f63dc9977b5e90c25dc1"
    }
}

Der Administrierende kann das Mediendeployment anpassen, sodass Binärdaten von Medien URLs nicht mit CaaS-URLs abgefragt werden können. Es ist daher sehr wichtig, dass die Binärdaten-URLs für Medien immer über das Metadatendokument erfragt und keinesfalls durch String-Konkatenation selbst erzeugt werden.

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

Medien-URL-Attribute in Medienmetadaten: Die von FirstSpirit bereitgestellten Medienmetadaten (siehe Medien-URLs) beinhalten normalerweise für jede Auflösung die von einer URL-Factory generierte URL auf das Medium, nicht aber auf die Binärdaten.

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

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.

3. Rechtliche Hinweise

CaaS ist ein Produkt der e-Spirit AG, Dortmund, Germany.

Für die Verwendung des Produkts gilt gegenüber dem Anwender nur die mit der e-Spirit AG vereinbarte Lizenz.

4. Hilfe

Der Technical Support der e-Spirit AG 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.