FirstSpirit Object Service - Dokumentation für Entwickler

Das Hinzufügen bzw. Ändern projektspezifischer Attribute erfolgt über die insert-Methode eines attributeHandlers. Diese Methode erwartet als Übergabeparameter eine HashMap.

Die Map muss zuvor mit den projektspezifischen Attributen und den zugehörigen Werten in Form von Key/Value-Paaren gefüllt werden. Eine Beschränkung auf eine bestimmte Anzahl von Attributen existiert dabei nicht.

Die insert-Methode des attributeHandlers sendet die HashMap an den FOS, in dessen interner Persistenzschicht die übertragenen Werte gespeichert werden. Die einzelnen Attribute stehen daraufhin dem Portal-Plugin zur Verfügung und lassen sich von diesem über die REST-Schnittstelle abfragen.

adding and changing project-specific attributes. 

import com.espirit.moddev.fos.AttributeHandler;
import java.util.HashMap;

// create attributeHandler
attributeHandler = new AttributeHandler(context);

// create map with attributes/values to add
attributeMap = new HashMap();
attributeMap.put(“eSpiritDefaultPluginMyKey”,“myValue”);
attributeMap.put(“eSpiritDefaultPluginMySecondKey”,“mySecondValue”);

// insert map
attributeHandler.insert(attributeMap);

Das Entfernen projektspezifischer Attribute erfolgt über die delete-Methode eines attributeHandlers. Diese Methode erwartet als Übergabeparameter ein HashSet.

Dem Set müssen lediglich die zu entfernenden Attribute hinzugefügt werden, während die den Attributen zugehörigen Werte an dieser Stelle nicht von Bedeutung sind. Sie werden durch das das Löschen der Attribute ebenfalls beseitigt und müssen daher nicht explizit angegeben werden.

Die delete-Methode des attributeHandlers überträgt das HashSet an den FOS, welcher die entsprechenden Attribute aus seiner internen Persistenzschicht entfernt.

deleting attributes. 

import com.espirit.moddev.fos.AttributeHandler;
import java.util.HashSet;
// create attributeHandler
attributeHandler = new AttributeHandler(context);
// create set with attributes to delete
attributeSet = new HashSet();
attributeSet.add(“eSpiritDefaulPluginMyKey”);
// delete set
attributeHandler.delete(attributeSet);

Jedes Attribut besteht aus einem Key/Value-Paar und einem Tag, welches dieses Paar umgibt. Das umgebende Tag besteht aus dem Typ und dem Referenznamen (UID) des gewünschten Elements, zu dem das neue Attribut hinzugefügt werden soll. Der Key ist – bis auf eine Ausnahme – beliebig wählbar und umschließt die zu übermittelnden Daten, die das Value zum gewählten Key bilden.

Für ein einzelnes Attribut ergibt sich somit folgende Struktur:

<OBJEKTTYP uid=”UID_OBJEKT”>
 <KEY>VALUE</KEY>
</OBJEKTTYP>

Die einzelnen Attribute, von denen innerhalb des Ausgabekanals beliebig viele angegeben werden können, müssen durch ein umschließendes <attributes/>-Tag zu einer Liste zusammengefasst werden.

Eingabe:

<attributes>
 <PageFolder uid="$CMS_VALUE(#global.node.uid)$">
  <portlettype>$CMS_VALUE(pt_portlettype)$</portlettype >
 </PageFolder>
 <Page uid="$CMS_VALUE(#global.page.uid)$">
  <pageportletname>$CMS_VALUE(pt_portletname)$</pageportletname>
 </Page>
</attributes>

Ausgabe:

<attributes>
 <PageFolder uid="umsetzungmitfirstspirit">
  <portlettype>WIDGET</portlettype>
 </PageFolder>
 <Page uid="firstspirit">
  <pageportletname>Blog</pageportletname>
 </Page>
</attributes>

Es ist darauf zu achten, dass Attribute nur für die jeweils generierten Elemente ergänzt werden können. Dies bedeutet, sie müssen in der an den FOS adressierten Nachricht enthalten sein.

Diese Nachricht besteht für ein generiertes Element immer aus:

Der Versuch, ein nicht existierendes Element durch ein Attribut zu erweitern, führt zu einer Warnung im Generierungsauftrag.

Mit dem Tag <medialist/> besteht die Möglichkeit, zusätzlich zur Attributliste eine Liste von Medien zu übergeben. Die einzelnen Einträge dieser Liste enthalten vier Angaben, von denen jeweils zwei paarweise zusammengehören:

Das erste Paar bezieht sich auf das Medium und enthält dessen Typ sowie Referenznamen.

Das zweite Paar verweist auf das Element, welches das Medium verwendet. Die Werte origin und originType geben den Referenznamen und den Typ dieses Elements an. Es kann sich dabei beispielsweise sowohl um Ordner als auch um einen Absatz innerhalb einer Seite handeln.

$CMS_VALUE(#global.page.name)$#$CMS_VALUE(#global.page.body("Content left").children.first.name)$

$CMS_VALUE(#global.page.name)$#$CMS_VALUE(#global.section.name)$

Beide Paare werden in einem Tag gebündelt und stellen zusammen einen Eintrag in der Liste der Medien dar.

Eine Medien-Liste mit nur einem Element besitzt somit den folgenden Aufbau:

<medialist>
 <Media uid=”UID_MEDIUM” origin=”UID_REFERENZELEMENT” originType=”TYPE_REFERENZELEMENT”/>
</medialist>

Mit diesen Informationen wird das Medium in der Persistenzschicht des FOS gespeichert und eine Referenz zu dem angegebenen Referenzelement erzeugt.

Die einzelnen Medien-Einträge enthalten keine Attribute, da diese über den Standardmechanismus FirstSpirits erfasst und an den FOS versandt werden (siehe auch Kapitel Ausgabekanal).

Sollen darüber hinaus weitere Daten übertragen werden, müssen diese in der Liste der Attribute erfasst werden.

Eine Medien-Liste mit nur einem Eintrag könnte wie folgt aussehen.

Eingabe:

<medialist>
 <Media uid="connector_cable" originType="$CMS_VALUE(#global.node.UidType)$" origin="$CMS_VALUE(#global.page.name)$"/>
</medialist>

Ausgabe:

<medialist>
 <Media uid="connector_cable" originType="Page" origin="mithras_home"/>
</medialist>

Um die durch die Attribut- und Medien-Liste bereitgestellten Informationen in der durch eine Generierung erzeugten Nachricht versenden zu können, müssen die beiden einzelnen Listen zu einer gemeinsamen Liste zusammengefasst werden.

Die geschieht über das umgebende <supplementary/>-Tag, welches die beiden Listen miteinander verbindet:

<supplementary>
 <attributes> […] </attributes>
 <medialist> […] </medialist>
</supplementary>

Eine einfache XML-Nachricht, die so, wie in den vorhergehenden Kapiteln beschrieben, erzeugt wurde, könnte beispielsweise folgendes Aussehen besitzen:

<supplementary>
 <attributes>
  <PageFolder uid="umsetzungmitfirstspirit">
   <portlettype>WIDGET</portlettype>
  </PageFolder>
  <Page uid="firstspirit">
   <pageportletname>Blog</pageportletname>
  </Page>
 </attributes>
 <medialist>
  <Media uid="connector_cable" originType="PageRefFolder" origin="firstspirit"/>
 </medialist>
</supplementary>

Wie im Kapitel Liste der Attribute erwähnt, können auch Content-Projektionen um zusätzliche Attribute ergänzt werden. In diesem Fall ist jedoch eine Erweiterung der Uid notwendig, wobei Detail- und Übersichtsseiten unterschieden werden müssen.

Der Uid von Detailseiten muss durch einen Hash (#) getrennt die Id des jeweiligen Datensatzes angehängt werden.

Die Uid von Übersichtsseiten wird ebenfalls durch einen Hash (#) getrennt der Index der jeweiligen Seite (0…n) hinzugefügt.

<supplementary>
 <attributes>
  // Detailpage
  <PageRefContentProjection uid="$CMS_VALUE(#global.node.uid)$#$CMS_VALUE(#global.dataset.entity.id)$">
   <myAttribute>myValue</myAttribute>
  </PageRefContentProjection>
  // Overviewpage
  <PageRefContentProjection uid="$CMS_VALUE(#global.node.uid)$#$CMS_VALUE(#global.pageParams.index)$">
   <myAttribute>myValue</myAttribute>
  </PageRefContentProjection>
 </attributes>
</supplementary>

Jede Ausführung einer Generierung wird dem Portal-Plugin über sogenannte Status-Nachrichten mitgeteilt, die jeweils den Anfang und das Ende des Auftrags kennzeichnen.

Des Weiteren enthalten die Status-Nachrichten eine Information über den Typ der auf dem FirstSpirit-Server ausgeführten Generierung. Eine Voll-Generierung aktiviert automatisch den Wartungsmodus für das entsprechende Projekt im FOS.

Das Portal-Plugin muss über diesen Zustand informiert werden, da der FOS seine Kommunikation während des Wartungsmodus für dieses Projekt einstellt. Auch auf alle Anfragen an die REST-Schnittstelle reagiert er mit einer „Retry later“-Antwort. Das Portal-Plugin erhält somit in dieser Zeit keine Informationen vom FOS zu dem entsprechenden Projekt.

Die übermittelten Informationen sowie die Struktur einer Status-Nachricht werden im Kapitel Struktur der Nachrichten erläutert.

Die vom FOS über den UX-Bus an das Portal-Plugin gesendeten Informationen über ermittelte Änderungen am Datenbestand werden als sogenannte Event-Nachrichten bezeichnet. In ihnen ist jeweils eine Liste einzelner Events enthalten.

Der automatische Versand einer Event-Nachricht durch den FOS erfolgt unter Berücksichtigung der Notwendigkeit. Dem vorausgehend muss in der Persistenzschicht des FOS zunächst ein Datenabgleich stattgefunden haben, der seinerseits durch eine Generierung auf dem FirstSpirit-Server ausgelöst wurde.

Werden durch den Datenabgleich keine Änderungen am Datenbestand ermittelt, ist der Versand von Event-Nachrichten an das Portal-Plugin überflüssig, da keine Notwendigkeit zur Aktualisierung des Livestandes auf dem Portal-Server besteht. Das Portal-Plugin wird in diesem Fall lediglich per Status-Nachricht über den Anfang und das Ende des Auftrags informiert. Ein Versand von Event-Nachrichten findet jedoch nicht statt.

Werden durch den Datenabgleich Änderungen am Datenbestand erfasst, übermittelt der FOS jede dieser Änderungen in Form von Event-Nachrichten an das Portal-Plugin. Änderungen an vererbten Attributen, wie beispielsweise Metadaten, stellen einen Sonderfall dar und werden daher besonders behandelt (siehe Kapitel Vererbung).

Der Versand der Event-Nachrichten erfolgt per Push. Es ist keine vorhergehende Aktion des Portal-Plugins notwendig. Im Optimalfall sollten die in den Event-Nachrichten enthaltenen Informationen für eine Aktualisierung des im Portal enthaltenen Datenbestands ausreichen. Andernfalls muss eine Anfrage an die REST-Schnittstelle durch das Portal-Plugin erfolgen.

Eine detaillierte Erläuterung der in den Event-Nachrichten übermittelten Informationen sowie ihrer Strukturierung ist in den folgenden Unterkapiteln enthalten.

Änderungen an Inhalten übermittelt der FOS über den UX-Bus an das Portal-Plugin mithilfe sogenannter ChangedContent-Nachrichten. Bei ihnen handelt es sich um spezielle Event-Nachrichten, die sich von diesen lediglich durch ihren Typ unterscheiden.

Der automatische Versand einer ChangedContent-Nachricht erfolgt so wie bei den Event-Nachrichten unter Berücksichtigung der Notwendigkeit.

Nur dann, wenn Änderungen an Inhalten existieren, übermittelt der FOS diese an das Portal-Plugin. Der Versand der Informationen erfolgt dabei im Gegensatz zu den Event-Nachrichten in genau einer ChangedContent-Nachricht, in der alle Änderungen zusammengefasst sind.

Wurden keine Änderungen ermittelt, wird das Portal-Plugin lediglich per Status-Nachricht über den Start und das Ende des Auftrags informiert.

Der Versand der ChangedContent-Nachricht erfolgt per Push. Es ist keine vorhergehende Aktion des Portal-Plugins notwendig.

Damit alle Informationen übermittelt werden, ist es notwendig, dass alle Projektinformationen dem FOS bekannt sind. Dazu ist es notwendig, dass der Haken Projekt-Informationsnachricht senden, wie in der FirstSpirit Object Service Dokumentation für Administratoren beschrieben, gesetzt ist.

Eine detaillierte Erläuterung der in den ChangedContent-Nachrichten übermittelten Informationen sowie ihrer Strukturierung ist in den folgenden Unterkapiteln enthalten.

Im Allgemeinen wird der Versand von Event-Nachrichten durch eine Generierung auf dem FirstSpirit-Server und eines daran anschließenden Datenabgleichs im FOS ausgelöst. Jede durch den FOS ermittelte Änderung erzeugt dabei eine Event-Nachricht, die über den UX-Bus an das Portal-Plugin gepushed wird.

Eine auf dem FirstSpirit-Server ausgeführte Voll-Generierung erzeugt jedoch einen Abgleich aller Daten in der Persistenzschicht des FOS für ein Projekt. Ein solcher Voll-Abgleich würde somit zum Versand unzähliger Event-Nachrichten führen.

Um dies zu vermeiden, wird das Projekt im FOS während eines Voll-Abgleichs automatisch in einen Wartungsmodus versetzt. Das Portal-Plugin wird über diesen Vorgang durch eine Status-Nachricht informiert.

Während des Wartungsmodus liefert der FOS für das entsprechende Projekt keinerlei Daten an das Portal-Plugin. Versucht das Portal-Plugin dennoch Daten über die REST-Schnittstelle anzufordern, erhält es eine „Retry later“-Antwort.

Nach der Beendigung des Voll-Abgleichs wird der Wartungsmodus in der Regel automatisch deaktiviert und das Portal-Plugin erneut mit einer entsprechenden Status-Nachricht darüber informiert. Es fordert daraufhin selbstständig den gesamten Datenstand des Projekts über die REST-Schnittstelle an und führt einen Austausch der Daten im Portal durch.

In FirstSpirit besteht die Möglichkeit, auf Ordnern der Struktur-, Inhalte- und Medien-Verwaltung Attribute zu definieren und sie – beispielsweise über die Verwendung von Metadaten – an alle untergeordneten Elemente zu vererben.

Besitzt ein Portal die Funktionalität der Vererbung, reicht eine auf solch einen Ordner beschränkte Berücksichtigung aus: In der zugehörigen Event-Nachricht wird lediglich die Änderung der Attribute des Vaterknotens festgehalten und an das Portal-Plugin übertragen. Dieses übernimmt die automatische Zuordnung der Attribute zu den untergeordneten Elementen.

Besitzt ein Portal die Funktionalität der Vererbung nicht, reicht die Übermittlung der Informationen des Vaterknotens nicht aus, da die vorgenommene Änderung nur ihm zugeschrieben werden würde. Die Auswirkung dieser Änderung auf die Attribute der ihm untergeordneten Elemente würde somit verloren gehen und es käme zu einem Informationsverlust. Aufgrund dessen werden in diesem Fall auch alle untergeordneten Elemente per Event-Nachricht an das Portal-Plugin übermittelt. Diese zusätzlich versandten Nachrichten dienen jedoch lediglich der Information, welche Elemente betroffen sind. Die geänderten Attribute sind in ihnen nicht enthalten, da sie ansonsten sowohl für den Vaterknoten als auch für alle untergeordneten Elemente übertragen würden. Es käme somit zu Redundanzen. Um dies zu vermeiden, müssen die geänderten Attribute selbst für jedes untergeordnete Element über die Rest-Schnittstelle des FOS ermittelt werden.

Bei der Modifikation eines Struktur-Ordners wird grundsätzlich nur er inklusive der Information über die vorgenommene Änderung in der Event-Nachricht erfasst. Diese Information reicht in diesem Fall aus, da jedes Portal eine Möglichkeit zur Abbildung der Struktur besitzt und somit im Allgemeinen auch die Zuordnung von Attributen eines Vaterknotens auf die ihm untergeordneten Struktur-Elemente beherrscht.

Wird ein Inhalte-Ordner verändert, enthält die Event-Nachricht neben dem entsprechenden Pagefolder-Event immer auch die Events für alle in dem Ordner enthaltenen Seiten und die auf ihnen basierenden Seitenreferenzen. Somit erhält das Portal-Plugin in jedem Fall alle benötigten Informationen: Beherrscht das verwendete Portal keine Vererbung erfolgt die Zuordnung der geänderten Attribute über eine Abfrage an die Rest-Schnittstelle des FOS. Andernfalls reichen die in der Event-Nachricht enthaltenen Informationen zum Inhalte-Ordner aus.

Da die Auswirkungen von Änderungen an Struktur- und Inhalte-Ordnern somit bereits über die generelle Struktur der Event-Nachrichten erfasst werden (vgl. auch Tabelle im Kapitel Struktur der Nachrichten), muss die Vererbung lediglich für die auf Medien-Ordnern definierten Attribute berücksichtigt werden.

Die Behandlung von Medien-Ordnern lässt sich manuell über einen Schalter im FirstSpirit Object Service Admin Interface explizit festlegen.

Abbildung 4. Media-Event mode für Medien-Ordner

Ist der MediaEvent-Modus SINGLE gesetzt, wird nur der Medien-Ordner in der zugehörigen Event-Nachricht inklusive der Informationen zu den vorgenommenen Änderungen erfasst. Die Zuordnung der geänderten Attribute auf die ihm untergeordneten Elemente erfolgt durch das Portal-Plugin.

Ist der MediaEvent-Modus MULTI aktiviert, werden in der zugehörigen Event-Nachricht nur die Events für alle in dem Ordner enthaltenen Elemente erfasst. Dies umfasst auch in dem Ordner enthaltene Unterordner. Der Ordner selbst wird nicht berücksichtigt. Aus diesem Grund erfolgt die Zuordnung der geänderten Attribute zu den Medien bereits an dieser Stelle und nicht erst im Anschluss über eine Anfrage an die Rest-Schnittstelle des FOS.

Das Portal-Plugin empfängt die Service-Nachrichten in Form von JSON-Dokumenten, welche die folgende, immer gleiche Struktur besitzen:

{
 "schedulerID":"ID",
 "projectName" : "PROJECTNAME",
 "createTime" : "A MESSAGE'S CREATE TIME",
 "startTime" : "A SCHEDULE'S START TIME",
 "type" : "A MESSAGE'S TYPE"
 //specific Parameter
 "status" : "A STATUS MESSAGE'S STATUS"
 "fullGeneration": TRUE OR FALSE
 "events" : [ {...} ]
}

Da der FOS potentiell mehrere Projekte verwaltet und diese alle dieselbe Schnittstelle verwenden, müssen die Service-Nachrichten immer eindeutig einem FirstSpirit-Projekt zuzuordnen sein. Jedes der vom FOS erstellten JSON-Dokumente enthält daher zunächst den eindeutigen Namen des Projekts sowie den Zeitpunkt der Erzeugung der Nachricht und den Startzeitpunkt des zugrundeliegenden Generierung-Auftrags:

"projectName" : "PROJECTNAME",
"createTime" : "AN EVENT MESSAGE'S CREATE TIME",
"startTime" : "THE SCHEDULE'S START TIME",

Die Unterscheidung, ob es sich um eine Status-, Event- oder ChangedContent-Nachricht handelt, erfolgt über den angegebenen Typ der Nachricht. Im Fall einer Status-Nachricht besitzt der Parameter den Wert StatusMessage. Eine Event-Nachricht besitzt den Wert EventMessage. Eine ChangedContent-Nachricht besitzt den Wert ChangedContentMessage.

"type" : "StatusMessage"
"type" : "EventMessage"
"type" : "ChangedContentMessage"

Das Kapitel Beispiele beschreibt die Nachrichten-Typen anhand von Beispielen.

Status-Nachricht

Im Fall einer Status-Nachricht wird das Dokument zusätzlich durch die Parameter status und fullGeneration ergänzt.

Der Parameter status kann nur die Werte start und end besitzen. Sie definieren, ob es sich um die Information für den Beginn oder das Ende einer Generierung handelt.

"status" : "start"	// Schedule Start
"status" : "end"	// Schedule End

Der Paramerter fullGeneration kennzeichnet den Typ der Generierung. Er kann nur die Werte true oder false annehmen. Im Fall einer Voll-Generierung besitzt der Parameter den Wert true.

"fullGeneration" : true		// Full-Generation
"fullGeneration" : false	// each other Generation

Der Parameter maintenanceModeStopped gibt Auskunft darüber, ob der Wartungsmodus nach dem Beenden der Voll-Generierung wieder ausgeschaltet wurde oder nicht. Er kann nur die Werte true oder false annehmen. Wurde der Wartungsmodus beendet besitzt der Parameter den Wert true. Der Wartungsmodus kann bestehen bleiben, wenn die Anzahl der erlaubten Fehler im FOS bei der Generierung überschritten wurden.

[...]
"type" : "StatusMessage"
"status" : "start" || "end"			// Start or End of the MaintenanceMode
"fullGeneration" : true
"maintenanceModeStopped" : "true" || "false“ 	// just when status:end

Event-Nachricht

Die weitere Struktur des Dokuments wird im Fall einer Event-Nachricht durch ein Array zusammengehörender Events gebildet:

"events" : [
 { [...] },
 { [...] }
]

Diese Events repräsentieren immer die an einem einzigen Element vorgenommene Änderung. Dabei wird – mit Ausnahme von Medien – grundsätzlich auch die Vaterkette des Elements berücksichtigt, weshalb die Events einander zum Teil bedingen.

Innerhalb der Vaterkette gibt es eine Besonderheit im Bezug auf die Startseiten. Wurden Änderungen an einer Startseite innerhalb der Vaterkette gemacht und hierfür noch kein Event verschickt, dann wird diese Startseite in der aktuellen Event-Nachricht mit raus geschrieben (inklusive Ordner). So kann garantiert werden, dass für jeden Ordner immer eine Startseite vorhanden ist, entweder weil die Information bereits in einer vorherigen Event-Nachricht verschickt wurde oder in der aktuellen Nachricht mitgeliefert wird.

Die nachfolgende Tabelle zeigt die im Fall einer Änderung erzeugten Events:

Wurden mehrere Elemente innerhalb des Projekts geändert, so wird für jedes Element eine eigene Event-Nachricht erstellt.

Der Aufbau eines Events wird im nachfolgenden Unterkapitel erläutert.

Grundsätzlich besitzen alle Events die folgenden Parameter:

Diese entsprechen dem Typ des Events sowie dem Referenznamen und dem Typ des Elements, das durch das Event repräsentiert wird. Des Weiteren werden die potentiell veränderten oder gelöschten Eigenschaften sowie die hinzugefügten oder gelöschten Referenzen des Elements angegeben.

Die möglichen Werte für die Parameter nodeType und type werden in den entsprechenden Unterkapiteln erklärt.

Der Parameter id entspricht einer fortlaufenden Nummer, mit der die Events innerhalb einer Event-Nachricht versehen werden. Sie dient der eindeutigen Identifizierung eines Events innerhalb einer Event-Nachricht.

Der Parameter origin kann nur die Werte true oder false besitzen. Er zeigt an, ob sich das durch das Event repräsentierte Element selbst oder nur ein referenziertes Element verändert hat. Wurde beispielsweise ein Absatz verändert, muss auch ein Page-Event erzeugt werden. Das Section-Event erhält in diesem Fall den Wert true für den Parameter origin. Da das Page-Event nur auf Basis des Section-Events erzeugt wurde, sich die Seite jedoch nicht geändert hat, nimmt der Parameter origin im Page-Event den Wert false an.

Änderungen an den Eigenschaften eines FirstSpirit-Elements werden in Form von removedProperties oder changedProperties übermittelt:

"events": [
{ "type":"...",
  "id":...,
  "origin":...,
  "refname":"...",
  "nodeType": "...",

  "removedProperties": [
   {"name":"headline", "language":"DE"},
   {"name":"headline", "language":"EN"} ],

  "changedProperties": [
   {"name":"title", "langugae":"DE", "value":"Startseite"},
   {"name":"title", "language":"EN", "value":"Startpage"},
   {"name":"description", "value":"The startpage!"} ]
}]

Die Properties werden alle jeweils über ihren Namen angegeben. Da der Wert einer Eigenschaft nur im Fall von Änderungen von Bedeutung ist, wird er bei den gelöschten Eigenschaften nicht mit aufgeführt.

Sprachabhängige Eigenschaften werden außerdem um den Parameter language und eine Sprachkennung erweitert, um die Verarbeitung der removed bzw. changedProperties für alle im Projekt vorhandenen Sprachen zu ermöglichen.

Die Referenzen eines FirstSpirit-Elements werden über die Angabe von addedReferences oder removedReferences erfasst:

{ "type":"...",
  "id":...,
  "origin":...,
  "refname":"...",
  "nodeType":"...",

  "addedReferences": [
   { "refType":"REFERENCE'S TYPE",
     "refname":"THE REFERENCED ELEMENT'S REFERENCENAME",
     "type":"THE REFERENCED ELEMENT'S TYPE",
     "direction":"The DIRECTION OF THE REFERENCE"} ],

  "removedReferences": [
   { "refType":" THE REFERENCE'S TYPE ",
     "refname":" THE REFERENCED ELEMENT'S REFERENCENAME",
     "type":"THE REFERENCED ELEMENT'S TYPE",
     "direction":"The DIRECTION OF THE REFERENCE"} ]
}

Jeder Eintrag enthält die Art der Referenz sowie den Referenznamen und den Typ des referenzierten Elements. Mögliche Werte für den refType sind:

Zusätzlich wird über das Attribut direction die Richtung der Verbindung angegeben. Mögliche Werte sind INCOMING für eingehende Verbindungen oder OUTGOING für ausgehende Verbindungen.

Änderungen an den Zugriffsrechten eines Benutzers oder einer Gruppe werden durch entsprechende User- oder Group-Events repräsentiert. Diese enthalten den nodeType User oder Group und besitzen zusätzlich zu den grundsätzlich vorhandenen Parametern die folgenden Parameter:

Es handelt sich dabei um die Angaben der Rechte, die einem Benutzer oder einer Gruppe zugewiesen oder entzogen wurden.

{ "type" : "MODIFIED",
  "id" : ...,
  "origin" : true,
  "refname" : "USER'S (OR GROUP'S) NAME",
  "nodeType" : "USER OR GROUP",

  "addedPermissions" : [
   { "access" : "ZUGRIFFSRECHT",
     "refname" : "NAME DES KNOTENS",
     "nodeType" : "TYP DES KNOTENS"
   } ],

   "removedPermissions" : [
    { "access" : "ZUGRIFFSRECHT",
      "refname" : "NAME DES KNOTENS",
      "nodeType" : "TYP DES KNOTENS"
    } ],
}

Jeder Eintrag innerhalb der beiden Listen enthält den Referenznamen und den Knotentyp des Elements, für das die Zugriffsrechte geändert wurden. Der Wert des Parameters access gibt an, welches Recht genau geändert wurde. Der Entzug des Rechts canChange auf der Seite mit dem Referenznamen homepage wird in der Event-Nachricht beispielsweise wie folgt dargestellt:

"removedPermissions" : [
 { "access" : "canChange",
   "refname" : "homepage",
   "nodeType" : "Page"
 } ]

Alle für den Parameter access möglichen Werte werden im Kapitel Access erläutert.

Existieren zu einem Event für die Parameter removedProperties, changedProperties, addedReferences, removedReferences, removedPermissions oder changedPermissions keine Werte, so sind sie in dem Event nicht enthalten.

Jedes Event repräsentiert eine Veränderung im verwendeten FirstSpirit-Projekt. Dabei kann es sich um die Veränderung einer Benutzergruppe, eines einzelnen Benutzers oder eines Elements aus der Inhalte-, der Struktur- oder der Medien-Verwaltung handeln.

Für den Parameter nodeType ergeben sich somit die folgenden möglichen Werte:

Dokumentengruppen werden in dieser Liste nicht aufgeführt, da sie aus mehreren Einzelseiten bestehen, die zu einem einzelnen Dokument zusammengefasst werden. Sie werden wie Seitenreferenzen behandelt und lösen daher Events mit dem Knotentyp PageRef aus.

Änderungen an Datensätzen in den Datenquellen werden ebenfalls nicht durch explizite Events berücksichtigt, da sie über Content-Projektionen erfasst werden. Diese werden im FOS über ein eigenes PageRefContentProjection-Objekt sowohl der zugehörigen Seite als auch der Seitenreferenz zugeordnet. Sie werden daher über die entsprechenden Events mit dem Knotentyp PageRefContentProjection repräsentiert.

Ein FirstSpirit-Element besitzt immer einen von vier möglichen Zuständen. Dieser hängt jeweils davon ab, ob das entsprechende Element erstellt, verändert, gelöscht oder gar nicht bearbeitet wurde.

Da ein unbearbeitetes Element für die Aktualisierung des Live-Standes nicht von Bedeutung ist, ergeben sich für den Parameter type eines Events (siehe Kapitel Event-Nachrichten) die folgenden möglichen Werte:

Da einzelne Events einander bedingen, enthält eine Event-Nachricht manchmal mehrere Events unterschiedlichen Knotentyps (siehe Kapitel NodeType) mit demselben Eventtyp.

Beispiel 1 – Löschen einer Seite

Das Löschen einer Seite erfordert beispielsweise zusätzlich das Entfernen der ausschließlich von ihr verwendeten Medien und der ihr zugehörigen Absätze sowie der auf ihr basierenden Seitenreferenzen. Vorausgesetzt, dass eine Seite nicht völlig isoliert innerhalb eines Projektes existiert, müsste eine entsprechende Event-Nachricht somit neben dem Page-Event potentiell auch noch ein Media- und ein Section- sowie ein Pageref-Event enthalten. Alle vier Events besäßen in diesem Fall den Eventtyp DELETE.

Beispiel 2 – Löschen eines Absatzes

Das Löschen eines Absatzes entfernt nur ihn selbst und die ausschließlich von ihm verwendeten Medien. Die zugehörige Seite und die auf der Seite basierende Seitenreferenz bleiben erhalten. Allerdings gelten diese als verändert. Die entsprechende Event-Nachricht müsste also neben dem Section- und dem Media-Event mit dem Eventtyp DELETED ein Page- und eine PageRef-Event mit dem Eventtyp MODIFIED besitzen.

Für die spätere Betrachtung der veröffentlichten Live-Seite sind die im FirstSpirit SiteArchitect konfigurierbaren Redaktionsrechte irrelevant (vgl. Abbildung im SiteArchitect konfigurierbare Redaktionsrechte).

Abbildung 5. im SiteArchitect konfigurierbare Redaktionsrechte

Es sind jedoch Anwendungsfälle denkbar, in denen Redakteure beispielsweise zur Bearbeitung von Inhalten über eine entsprechende Methodik aus dem Portal in die FirstSpirit-Umgebung umgeleitet werden. Diese Methodik sollte sinnvollerweise nur im Portal eingeloggten Redakteuren mit den notwendigen FirstSpirit-Rechten zur Verfügung stehen und ansonsten ausgeblendet werden.

Änderungen an den Redaktionsrechten werden aus diesem Grund ebenfalls mit den Event-Nachrichten an das Portal-Plugin übertragen (siehe Kapitel Aufbau eines Events). Die Angabe des jeweiligen Rechts erfolgt dabei in einem User- oder Group-Event über den Parameter access, der somit jeweils einen der folgenden Werte annimmt:

Da die Rechte zwischen Benutzer/Benutzergruppe und Knoten vererbt werden, ist das „Recht“ canNothing notwendig. Das canNothing-Recht dient der Unterscheidung, ob ein Recht vom Vaterknoten geerbt wird oder nicht vorhanden ist. Hat beispielsweise ein User das canRead-Recht auf einen PageRefFolder, hat er somit auch auf alle PageRefs in diesem Ordner lesenden Zugriff, wenn für diese PageRefs keine speziellen Zugriffsrechte gesetzt sind. Soll der lesende Zugriff (und alle weiteren Rechte) für eine PageRef verweigert werden, bekommt diese das canNothing-Recht für diesen Benutzer oder diese Benutzergruppe. Ohne das canNothing-Recht wäre dies nicht händelbar und keine Vererbung möglich. Zum Einsatz kommt das canNothing-Recht, wenn in FirstSpirit die Vererbungshierachie unterbrochen wurde und alle Rechte für einen Benutzer oder eine Benutzergruppe entzogen wurden.

Informationen zu den einzelnen Redaktionsrechten sind im FirstSpirit Handbuch für Redakteure zu finden.

An dieser Stelle wird für jeden der drei Nachrichten-Typen ein Beispiel bereitgestellt.

Status-Nachricht

Eine durch den FOS erstellte Status-Nachricht könnte beispielsweise das folgende Aussehen besitzen:

{ "schedulerId":"139292",
  "projectName":"FOS-Project",
  "createTime":"1369404090435",
  "startTime":"1369404090509",
  "type":"StatusMessage",
  "status":"start",
  "fullGeneration":false
}

Die Status-Nachricht ist in diesem Beispiel durch ihren Typ identifizierbar. Ihr Status kennzeichnet sie als Start-Nachricht, mit der das Portal-Plugin über den Beginn eines Auftrags informiert wird. Es handelt sich bei diesem Auftrag nicht um eine Voll-Generierung, wie der Parameter fullGeneration zeigt.

Event-Nachricht

Eine durch den FOS für den Versand an das Portal-Plugin erstellte Event-Nachricht könnte beispielsweise den folgenden Inhalt besitzen:

{ "schedulerID":"3141592", "projectName":"Mithras Energy",
  "createTime":"1369404090435", "startTime":"1369404090509",
  "type":"EventMessage",
  "events":[
   { “type”:“MODIFIED”, “id”:1, “origin”:true,
     “refname”:“startpageref”, “nodeType”:“PageRef”
   },
   { “type”:“ MODIFIED”, “id”:2, “origin”:true,
     “refname”:“startpage”, “nodeType”:“Page”
   },
   { “type”:“CREATED”, “id”:3, “origin”:true,
     “refname”:“newstartpagetext”, “nodeType”:“Section”
   },
   { “type”:“DELETED”, “id”:4, “origin”:true,
     “refname”:“startpagetext”, “nodeType”:“Section”
   },
   { “type”:“DELETED”, “id”:5, “origin”:“true”,
     “refname”:“startpageimage1”, “nodeType”:“Media”
   },
   { “type”:“DELETED”, “id”:6, “origin”:“true”,
     “refname”:“startpageimage2”, “nodeType”:“Media”
   },
   { “type”:“MODIFIED”, “id”:7, “origin”:“true”,
     “refname”:“everybody”, “nodeType”:“Group”,
     “removedPermission”:[
      {	“refname”:“ startpageref”, “type”:“PageRef”,
        “access”:“canChange” },
      {	“refname”:“ startpage”, “type”:“Page”,
        “access”:“canChange” }
] } ] }

In diesem Beispiel wurde der Absatz startpagetext gelöscht (vgl. id:4). Da auf den von ihm verwendeten Medien startpageimage1 und startpageimage2 keine weiteren Referenzen anderer Elemente bestanden, wurden sie ebenfalls entfernt (vgl. id:5 und id:6). Die drei Events besitzen daher den Eventtyp DELETED.

Anstelle des gelöschten Absatzes wurde für dieselbe Seite der Absatz newstartpagetext erzeugt (vgl. id:3). Der zugehörige Eventtyp ist somit CREATED.

Durch die beschriebenen Änderungen gelten auch die dem Absatz zugehörige Seite startpage und die auf der Seite basierende Seitenreferenz startpageref als verändert (vgl. id:1 und id:2). Des Weiteren wurde der Gruppe everybody auf der Seite startpage und der Seitenreferenz startpageref das Recht canChange entzogen (vgl. id:7). Die drei Events sind daher vom Typ MODIFIED.

ChangedContent-Nachricht

Eine durch den FOS für den Versand an das Portal-Plugin erstellte ChangedContent-Nachricht könnte beispielsweise den folgenden Inhalt besitzen:

{ "schedulerId":"5887",
  "projectName":"FOS-Project”,
  "createTime":"1375169338642",
  "startTime":"1375169338781",
  "type":"ChangedContentMessage",
  "events":[
    { "type":"MODIFIED",
      "id":3,
      "origin":true,
      "refname":"startpageref",
      "nodeType":"PageRef"
    }
  ]
}

In diesem Beispiel wurde der Absatz startpageref inhaltlich verändert.

Es lässt sich nicht ermitteln, inwiefern der Inhalt der Seite geändert wurde. Zur Übernahme des neuen Inhalts muss die Seite daher erneut aus dem Generierungsverzeichnis des FirstSpirit-Servers in das Portal importiert werden.

Je nach Portal kann es möglich sein, dass für diesen Import zunächst weitere Informationen zur Seite über die Rest-Schnittstelle vom FOS abgefragt werden müssen.

Mit den Nachrichten, die bei den auf dem FirstSpirit-Server durchgeführten Generierungen erzeugt werden, lassen sich Daten an den FOS übertragen und in dessen Persistenzschicht speichern.

Die Nachrichten umfassen sowohl die über den zusätzlich angelegten Ausgabekanal bereitgestellten Informationen als auch die Standard-FirstSpirit-Daten.

Da die über den Ausgabekanal übermittelten Daten projektspezifisch und somit immer individuell sind, kann auf sie nicht näher eingegangen werden.

Für den standardmäßig von FirstSpirit erstellten Anteil der Nachricht werden die im Projekt verwendeten Sprachen und Auflösungen erfasst sowie die Freigabestände der Inhalte-, der Struktur- und der Medien-Verwaltung berücksichtigt.

Eine Auflistung der in diesem Nachrichtenanteil enthaltenen Informationen ist im Kapitel Ausgabekanal enthalten.

Alle Informationen werden in der Persistenzschicht des FOS gespeichert. Sie lassen sich über die REST-Schnittstelle abrufen und stehen somit bei Bedarf auch dem Portal-Plugin zur Verfügung.

Die REST-Schnittstelle besitzt eine URL, an welche alle Anfragen gerichtet werden müssen:
http://<Servername>:<Port>/<Webbapp-Name>/rest/v1

Jede Anfrage an die REST-Schnittstelle muss einen HTTP-Header namens apikey enthalten. Der Wert dieses Headers muss eine UUID sein, die dem FOS als API-Key bekannt ist.

Mit den API-Keys werden Zugriffsrechte auf Projekte über die REST-Schnittstelle durchgesetzt. Eine Anfrage ohne diesen Header wird mit dem Status 401 Unauthorized beantwortet. Neben dem Lesen von Projekt-Daten kann ein API-Key auch administrative Rechte für ein Projekt besitzen, die ihm gestatten Anfragen zu senden, die das Projekt manipulieren.

Nähere Informationen über die Verwaltung der API-Keys finden Sie in der FirstSpirit Object Service Dokumentation für Administratoren.

Der FOS-Client ermöglicht die Durchführung von Abfragen an die REST-Schnittstelle des FOS aus einer Anwendung heraus, bei der es sich in der Regel um das zu implementierende Portal-Plugin handeln wird. Er muss in diese Anwendung eingebunden werden und wird daher in Form einer jar-Datei bereitgestellt, welche zusammen mit allen anderen Abhängigkeiten im ausgelieferten fos-client-<Versionsnummer>-distribution.tar.gz enthalten ist.

An dieser Stelle werden zwei Beispiele für Anfragen an die REST-Schnittstelle des FOS dargestellt. Alle Anfragen lassen sich sowohl per http-Request als auch über die Verwendung der Java-Api durchführen. Pro Beispiel werden jeweils beide Varianten sowie das Ergebnis der Anfrage bereitgestellt.

Liste aller vom FOS verwalteter Projekte

Da der FOS nicht an ein einziges Projekt auf dem FirstSpirit-Server gebunden ist, wird er in der Regel mehrere Projekte verwalten, die ihn als Schnittstelle nutzen. Dieses Beispiel zeigt, wie sich eine Übersicht all dieser Projekte abrufen lässt.

http-Request

Die Abfrage per http-Request erfolgt über eine Erweiterung der URL:

http://<Servername>:<Port>/<Webapp-Name>/rest/v1/projects

Java-Api

Bei der Abfrage über die Java-Api muss zunächst ein ApiClient mit Zugriff auf die REST-Schnittstelle des FOS gebaut werden. Wichtig dabei ist, dass ein http-Header namens apikey definiert wird. Mit dem Client lassen sich die Ressourcen des FOS abrufen und die von ihm verwalteten Projekte ermitteln.

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import org.junit.Test;
import com.espirit.moddev.fos.api.project.Project;
import com.espirit.moddev.fos.api.result.ResultListProjects;
public class ClientExample {
 public void createClient() {
  // get a client builder for the REST-Service
  ApiClient.Builder apiClientBuilder = ApiClient.builder("http://<SERVERNAME>:<PORT>/<WEBAPP-NAME>/rest/v1/");

  // set the apikey to be used
  apiClientBuilder.header("apikey", "<APIKEY>");

  // build a Client
  ApiClient client = apiClientBuilder.build();

  // get the ProjectsResources
  ProjectsResources projectResources = client.getResources();

  // get all Projects
  ResultListProjects projects = projectResources.projects();

  // iterate over the Projects
  for (Project project : projects.getItems()) {
   System.out.println(project.getName());
  }
  client.close();
 }
}

Ergebnis

In diesem Beispiel liefert die REST-Schnittstelle die zwei Projekte FOS und FS Object Service zurück. Wie in den weiteren Informationen ersichtlich ist, handelt es sich bei dem Projekt FOS um ein einsprachiges Projekt, während im Projekt FS Object Service die Sprachen Deutsch und Englisch verwendet werden. Des Weiteren befindet sich nur eines der beiden Projekte im Wartungsmodus, der in diesem Fall automatisch aktiviert wurde.

{ "view":list,"items":[
  { "name":"FOS",
    "attributes":[{}],
    "languages":["DE"],
    "maintenanceMode":false,
    "automaticMaintenanceMode":false
  },
  { "name":"FS Object Service",
    "attributes":[{}],
    "languages":["DE","EN"],
    "maintenanceMode":true,
    "automaticMaintenanceMode":true
  }
] }

Beim Senden der Anfrage wurde ein API-Key übermittelt, der Einfluss auf den Inhalt des Ergebnisses hatte. Bei der Auflistung der einzelnen Projekte wurden die Rechte des API-Keys beachtet und ein Ergebnis erzeugt, dass diesen Rechten entspricht. In diesem Beispiel kann deshalb davon ausgegangen werden, dass der API-Key lesende Rechte auf die Projekte FOS und FS Object Service hat. Es kann allerdings sein, dass weitere Projekte existieren, für die der verwendete API-Key keine Rechte besitzt und die deshalb nicht in die Ergebnismenge aufgenommen wurden. Genauso ist es möglich, dass bei Verwendung eines anderen API-Keys weder FOS noch FS Object Service in der Ergebnismenge enthalten wären.

Ermittlung einer bestimmten Seite aus einem bestimmten Projekt

Im Gegensatz zum vorhergehenden Beispiel ist es ebenso möglich, nur ein einzelnes Element über die REST-Schnittstelle des FOS zu ermitteln. Dieses Beispiel zeigt die Abfrage, mit der die Seitenreferenz Mithras Startseite aus dem Projekt FS Object Service zurückgeliefert wird.

http-Request

Auch in diesem Fall erfolgt die Anfrage an die REST-Schnittstelle des FOS über eine Erweiterung der URL. Allerdings werden zusätzlich noch der Name des Projektes, der Typ des zu ermittelnden Elements und dessen Referenzname mit angegeben:

http://<Servername>:<Port>/<Webbapp-Name>/rest/v1/projects/FS%20Object%20Service/pageref/mithras_home

Java-Api

Für die Abfrage über die Java-Api muss zunächst ein ApiClient mit Zugriff auf die REST-Schnittstelle des FOS gebaut werden. Wie für jede andere Anfrage bedeutet dies vor allem auch, dass im http-Header ein API-Key definiert wird. Mit dem erzeugten ApiClient lassen sich alle Projekt-Ressourcen abrufen, aus welchen die gewünschte Seitenreferenz ermittelt werden kann.

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import org.junit.Test;
import com.espirit.moddev.fos.api.project.Project;
import com.espirit.moddev.fos.api.result.ResultListProjects;

public class ClientExample {
 public void createClient() {
  // get a client builder for the REST-Service
  ApiClient.Builder apiClientBuilder = ApiClient.builder("http://<SERVERNAME>:<PORT>/<WEBAPP-NAME>/rest/v1/");

  // set the apikey to be used
  apiClientBuilder.header("apikey", "<APIKEY>");

  // build a Client
  ApiClient client = apiClientBuilder.build();

  // get the ProjectsResources
  ProjectsResources projectResources = client.getResources();

  try {
   // get the pageref "mithras_home"
   Result result = projectResources.detail("FS Object Service", "pageref", "mithras_home", "list", null, null, null, null);
   System.out.println(result);
  } catch (NotFoundException e)
   e.printStackTrace();
  } catch (ProjectNotFoundException e)
   e.printStackTrace();
  } catch (BadRequestException e) {
   e.printStackTrace();
  } catch (MaintenanceException e) {
   e.printStackTrace();
  }
  client.close();
 }
}

Ergebnis

In diesem Beispiel liefert die REST-Schnittstelle wie gewünscht die Seitenreferenz Mithras Startseite zurück. Zu der Seite werden ihre standardmäßig von FirstSpirit übermittelten Informationen mit ausgegeben.

{ "view": "list",
  "item": {
   "pageRef": {
    "refname": "mithras_home",
    "type": "PageRef",
    "attributes": [
     { "name": "fsId",
       "value": "325146"},
     { "name": "refname",
       "value": "mithras_home"},
     { "name": "type",
       "value": "PageRef"},
     { "name": "modifiedby",
       "value": "Admin"},
     { "name": "releasedate",
       "value": "1370595424313"},
     { "name": "displayName",
       "language": "DE",
       "value": "Mithras Startseite"},
     { "name": "displayName",
       "language": "EN",
       "value": "Mithras Homepage"},
     { "name": "url",
       "language": "DE",
       "value": "http://<LifeserverName>:<Port>/mithras/content/de/startpage/mithras_home.html"},
     { "name": "url",
       "language": "EN",
       "value": "http://<LifeserverName>:<Port>/mithras/content/en/startpage/mithras_home.html"}
    ],
    "groupPermissions": [],
    "userPermissions": [],
    "nodeReferences": {}
   }
 }
}

Auch in diesem Beispiel ist zu beachten, dass das Ergebnis abhängig vom verwendeten API-Key ist. Um das gezeigte Ergebnis zu erhalten, muss der API-Key lesende Rechte auf das Projekt FS Object Service besitzen. Andernfalls hätte die Anfrage mit dem http-Status 401 Unauthorized geendet.

Die Werte einer CMS_INPUT_PERMISSION-Eingabekomponente werden in JSON ausgegeben, das wiederum in einen String geschrieben wird, z.B.:

{\"activities\":[{\"name\":\"myActivity\",\"allowed\":[\"Management\",\"Marketing\"],\"forbidden\":[\"Customer\"]}]}

Dies ist notwendig, um ein statisches JSON-Schema zu erzeugen. Würden die Werte nicht als String, sondern direkt als JSON ausgeliefert, würde ein dynamisches Schema erzeugt.

Im Falle der INPUT_PERMISSION-Komponente sind sowohl die Activities als auch die Gruppen „dynamisch“. Sie hängen also nicht nur vom Projekt ab, sondern können sich dort auch noch ändern.

Mit einer JSON-Library ist es problemlos möglich, den Wert erst als String einzulesen und dann ein jsonFromString aufzurufen. Hierbei ist zu beachten, dass es beliebige Activities und Gruppen geben kann. 

Darüber hinaus ist zu beachten, dass der Name der INPUT_PERMISSION-Eingabekomponente auch vom Projekt abhängt. Es sollte daher konfigurierbar sein, welchen Namen die Eingabekomponente hat, die die Berechtigungen enthält.

Das Format, in dem Werte der INPUT_DATE-Eingabekomponente ausgegeben werden, unterscheidet sich primär nicht von dem Format anderer Eingabekomponenten (String). Das Format des Datums im ausgegebenen Text hängt jedoch von der Konfiguration der Eingabekomponente (mode) in FirstSpirit ab.

Ist als mode DATE gesetzt, so wird nur das gesetzte Datum ausgegeben: 2014-07-02

Ist als mode TIME gesetzt, so wird die gewählte Zeit ausgegeben: 05:11:51

Ist als mode DATETIME gesetzt, so werden Zeit und Datum inkl. der Zeitzone ausgegeben. Hierbei ist zu beachten, dass es sich um den Zeitstempel in der Zeitzone des Servers handelt: 2014-07-02T05:11:45+01:00