Plattform Kommunikationsrichtlinie

Anforderungen

Für den Datenaustausch innerhalb der oK-Plattform gelten die folgenden Regeln:

• Für die Kommunikation werden ausschließlich CIM-Nachrichten verwendet (der Payload ist hiervon nicht betroffen, muss also nicht zwangsläufig einem CIM-Modell entsprechen).
• Für den Datenaustausch wird das REST-Paradigma eingesetzt.
• Die Kommunikation (innerhalb der oK-Plattform) darf nicht abhängig von einer speziellen Messaging-Middleware (z.B. ESB) sein (kein Vendor-Lock-In).
  Daraus folgt, dass im der Messaging-Middleware, außer der Nachrichtenweiterleitung, des Routings und einer "Service Disvcovery" keinerlei Funktionalität implementiert sein darf. Insbesondere darf hier kein Mapping zwischen verschiedenen Nachrichtenformaten oder Versionen stattfinden.
• oK-Komponenten müssen so konzipiert sein, dass der Anwendungskern klar von der Kommunikationsschnittstelle getrennt ist und diese somit relativ einfach ausgetauscht werden kann.
• Zentrale oK-Komponenten (z. B. Domänen-Module) sind prinzipiell so zu gestalten, dass sie mit mehreren unterschiedlichen Nachrichtenformaten und Versionen umgehen können.

Informationsaustausch

Der Informationsaustausch zwischen den oK-Modulen und der Quellsystem-API basiert auf CIM-Nachrichten. Diese werden gemäß dem REST-Paradigma über das http://-Protokoll versendet.

Aufgrund der unterschiedlichen Entwicklung von CIM und REST bzw. http, lassen sich die Kommunikationsmuster beider Standards nicht ohne Weiteres automatisch nutzen. Das neuere REST-Paradigma wird zwar bereits als mögliche Kommunikationsform im CIM-Standard erwähnt, allerdings finden sich hier noch keine Definitionen zur Nutzung oder Anwendungsbeispiele.

Um beim Datenaustausch auf ein etabliertes Verfahren mit CIM-Nachrichten zurückgreifen zu können und das REST-Paradigma als modernes Kommunikationmittel einsetzen zu können, werden für oK die folgenden Festlegungen getroffen:

Anfragen

Für Anfragen in oK kommt das Request–Reply-Entwurfsmuster zum Einsatz.

Bei Anfragen handelt es sich nicht nur um die Abfrage eines bestimmten Werts oder eines bestimmten Objekts. Vielmehr wird eine Vielzahl an Anwendungsfällen mit Hilfe einer Anfrage ermöglicht.

Abfrage (get)

Mithilfe der Abfrage können bestimme Informationen, sofern der Abfrager hierzu zugelassen ist, bei einem Server angefordert werden. Informationen können sowohl Einzelwerte, komplexe Objektbeschreibungen aber auch Auflistungen von Informationen sein.

Da bei der REST-konformen Abfrage kein http-Message-Body zugelassen ist, ist es nicht möglich, gemäß des CIM-Standards eine entsprechende Abfragenachricht (CIM-RequestMessage) an den Server zu übertragen. Sämtliche Abfrageparameter werden daher in der URL des REST-Services (Server) kodiert. Die Parameter orientieren sich hierbei an den Attributen einer CIM-Abfragenachricht.

Der Kommunikationsverlauf ist im Folgenden dargestellt:

Abfrage-Attribute in der URL

Die für die Abfrage relevanten Query-Parameter orientieren sich an den Attributen einer CIM-RequestMessage. Die CIM-Header-Angaben „verb“ und „noun“ sind nicht erforderlich, da sich diese automatisch aus dem Kontext der http-Abfrage ergeben.

Attribut	CIM-Attribut	Beschreibung	Definition
revision	Revision	Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.	integer
timestamp	Timestamp	Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDTHH:mm:ss.SSSZ).	string
source	Source	Eindeutige Bezeichnung des Senders der Nachricht.	string
user-id	UserID	Eindeutige Kennung des angemeldeten Nutzers (Sender).	UUID
message-id	MessageID	Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.	UUID

Erstellen (create)

Ändern (change)

Löschen (delete)

Ereignisse

Ereignisse werden in der oK-Kommunikation als Observer-Entwurfsmuster realisiert.

Das Kommunikationsmuster für die Ereignisbehandlung besteht aus den folgenden drei Schritten:

Beobachter registrieren (subscribe)

Um über Ereignisse informiert werden zu können, muss sich das beobachtende bzw. interessierte oK-Modul (Subscriber-Module) beim Veröffentlicher (Publisher) registrieren. Beim Veröffentlicher von Ereignissen kann es sich um ein anderes oK-Modul oder ein Quellsystem-Dienst, der die oK Quellsystem-API (Source System API) implementiert, handeln.

Die Registrierung erfolgt gemäß des folgenden Prozesses:

Ereignis veröffentlichen (publish)

Hinweis: Während Ereignisse generell asynchron veröffentlicht werden, geschieht die konkrete Ereignisübermittlung an das jeweilige beobachtende bzw. interessierte oK-Modul synchron.

Registrierung aufheben

Heartbeat

Als sogenannter Heartbeat wird ein Mechanismus bei der Ereignisbehandlung bezeichnet, der es einem Veröffentlicher (Publisher) ermöglicht zu prüfen, ob ein registrierter Beobachter (Subscriber) noch aktiv ist. Ist diese nicht der Fall, hat der Veröffentlicher (Publisher) die Möglichkeit diesen selbständig abzumelden.

Kommandos

Um einen Dienst zu steuern, werden in der oK-Kommunikation Kommandos mit Parametern verwendet.

Die Kommandos werden per http-POST an den jeweiligen Dienst versendet und dort ausgeführt. Welche Kommandos und Parameter zur Verfügung stehen, ist abhängig vom jeweiligen Dienst.

CIM-Nachricht

Jede CIM-Nachricht besteht aus einem Nachrichtenkopf (Header), der Informationen zur Nachricht an sich enthält, und einem Nachrichteninhalt (Payload), der die zu übertragenden, fachlichen Informationen darstellt.

Header

Der Nachrichtenkopf (Header) enthält Informationen (Meta-Daten), die für die Weiterleitung und Verarbeitung der jeweiligen Nachricht notwendig sind. Der Aufbau erfolgt gemäß des CIM-Header-Aufbaus (siehe DIN EN 61968-100), unabhängig vom konkreten Format des Nachrichteninhalts (Payload).

verwendete Felder in oK:

Attribut	CIM-Attribut	Beschreibung	Definition
verb	Verb		get, create, change, cancel, close, delete, execute, reply
noun	Noun	Der Anwendungsfall.
revision	Revision	Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.	integer
timestamp	Timestamp	Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDTHH:mm:ss.SSSZ).	string
source	Source	Eindeutige Bezeichnung des Senders der Nachricht.	string
user-id	UserID	Eindeutige Kennung des angemeldeten Nutzers (Sender).	UUID
message-id	MessageID	Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.	UUID
correlation-id	CorrelationID	Eindeutige Kennung der Prozess auslösenden Abfragenachricht. Generiert vom Empfänger dieser Nachricht. (nur bei asynchroner Kommunikation)	UUID