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

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 f3628468-ee53-453f-a26f-a12edcd1f1f0 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 Datenfragmenten 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-Fragment 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-Fragment Beispiel
{
    "route" : "/Unternehmen/Standorte/Standorte.html"
}

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

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

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

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

Zusätzlich zum automatischen Abgleich nach redaktionellen Aktionen ist ein manueller Vollabgleich der Datenbestände über Aufträge möglich. Nach der Installation des CaaS Connect-Moduls 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.

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.