Die Agent Schnittstelle des Systems Q Plant basiert auf dem Austausch von Dateien mit einer speziellen Agent-Applikation auf dem Rechner des Clients. Diese Applikation wird von Q Point zur Verfügung gestellt.

Bitte wenden Sie sich an den Q Point Support, um den PlantX Agent sowie den zum Einsatz benötigten access key zu erhalten.

Diese Seite informiert über die folgenden Themen:

1 Zweck einer Agent-Schnittstelle
2 Technische Grundlagen, Architektur und Datenfluss
3 Envelope einer Nachrichtendatei
- 3.1 Beispiel für Message Envelope
4 Regeln für den Austausch von Nachrichten
5 Einrichtung der Schnittstelle und Ping-Nachricht
- 5.1 Schnittstelle einrichten
- 5.2 Ping-Nachricht senden
6 PDF-Dokumente hochladen
- 6.1 Bezeichnung der PDF-Dateien
- 6.2 Rechnungs-Dokumente
- 6.3 Lieferschein-Dokumente

Zweck einer Agent-Schnittstelle

Die Agent Schnittstelle dient der Übermittlung von Informationen zwischen einer Applikation in der Cloud und einem externen Gerät. Sie wird immer dann benötigt, wenn diese Kommunikation nicht nach dem REST-Standard stattfinden soll, sondern unter Verwendung der IoT-Infrastruktur der Q Point Cloud. Dadurch können grössere Datenvolumen in kürzerer Zeit übertragen werden, und die Übertragung erfolgt im Gegensatz zu REST bidirektional.

Die Q Point Cloud bietet mit ihrem eigenen IoT-Hub externen Geräten die Möglichkeit zum ständigen Datenaustausch mit Cloud-Applikationen auf Basis unterschiedlicher Protokolle. Um diese Möglichkeit zu nutzen, muss auch das externe Gerät das Protokoll und die darauf aufsetzenden Kommunikationsschritte umsetzen. Dies muss der Kunde jedoch nicht selbst implementieren. Q Point bietet hier eine spezielle Applikation an, den sog. Agent, welcher diese Aufgabe übernimmt. Der Kunde kann den Agent von Q Point beziehen, ihn auf seinen Geräten installieren und so sehr einfach die Verbindung zur Q Point Cloud herstellen. Zuletzt muss nur noch innerhalb des Geräts des Kunden ein Datentransfer zwischen Agent und der eigentlichen, eigenen Applikation des Kunden etabliert werden. Dies geschieht durch den Austausch von Dateien, den sog. message files.

Das Verfahren hat zusätzlich den Vorteil, dass Nachrichten an die Cloud als message files gepuffert werden können. Setzt die Internetverbindung aus, dann könnte eine REST-Schnittstelle nicht mehr aufgerufen werden. Message files können weiterhin geschrieben und lokal gespeichert werden, um sie bei wieder hergestellter Verbindung nachträglich zu übermitteln.

Die folgenden Kapitel beschreiben Installation und Einrichtung des Agents sowie das Vorgehen beim Dateiaustausch:

Technische Grundlagen, Architektur und Datenfluss

Die Architektur der Agent-Schnittstelle ist in der folgenden Grafik dargestellt.

Der Kunde installiert auf seinem Rechner neben seiner schon vorhandenen Applikation den Q Plant Agent. Um die Kommunikation mit der Cloud muss er sich anschliessend nicht mehr kümmern. Dies übernimmt der Agent. Mit der Installation wird zugleich ein Verzeichnis zum Austausch von Nachrichten auf dem Rechner des Kunden erstellt. Auf dieses Verzeichnis können sowohl die eigenen Applikationen des Kunden als auch der Agent zugreifen. In diesem Verzeichnis schreiben oder lesen Applikation und Agent nun Nachrichten füreinander in Form von Dateien, sog. message files.

Will die lokale Applikation eine Nachricht an Q Plant senden, so legt sie eine entsprechende Datei im message directory ab. Der Agent konsumiert diese Datei und übermittelt selbständig ihren Inhalt an Q Plant.
Will Q Plant eine Nachricht an die lokale Applikation senden, nimmt der Nachrichteninhalt den umgekehrten Weg. Am Ende schreibt der Agent eine Nachrichtendatei in das message directory, wo die lokale Applikation diese findet und ausliest.

Envelope einer Nachrichtendatei

Beim message file bzw. der Nachrichtendatei handelt es sich um eine JSON-Datei mit folgendem Aufbau:

Agent message
type string(100) Required must be entity name	Der Typ einer Agent message muss dem Namen der Entität entsprechen, die im "content"-Objekt übergeben wird.
version string(10) Required must be existing version	Version der Schnittstelle. Diese muss zum gewählten Typ der Agent message passen.
sentDt datetime2 Required	Der Zeitpunkt der Erstellung der Nachricht.
messageId UUID Required	Universal eindeutige Identifikationsnummer der Nachricht. Damit kein anderer Client zufällig denselben Wert wählt, sollte keine Zufallsnummer verwendet, sondern mittels geeigneter Framework-Methode eine GUID generiert werden.
correlationId UUID	Optionale Identifikation einer eventuell vorhandenen Beziehung zu einer anderen Nachricht, z.B. einer Antwort-Nachricht auf die Anfrage.
properties [propertyList]	Dieses JSON-Objekt kann eine Liste von Key-Value-Paaren für weitere Eigenschaften oder Metadaten der Nachricht enthalten. Es wird bei Erstellung der Nachricht meist leer gelassen und erst während der Verarbeitung durch Agent, IoT Hub oder Cloud automatisch mit Daten gefüllt, die für Routing und Validierung benötigt werden.
content {type}	Ein JSON-Objekt mit der Nutzlast bzw. dem eigentlichen Inhalt der Nachricht. Dieser entspricht dem übermittelten Objekt, z.B. einem Lieferschein, einem Produktionsdatensatz, etc. Das Objekt muss dem "type" der Nachricht entsprechen. Es muss zudem so aufgebaut sein, wie es in der Version vorgesehen ist, welche die Nachricht im Feld "version" anspricht. Näheres dazu in der Dokumentation der Schnittstelle.

Beispiel für Message Envelope

{ 
    "type": "asphaltProduction" ,
    "version": "2.0" ,
    "sentDto": "2019-03-15T05:39:03+01:00",
    "messageId": "4f3fe94e-a9f3-4006-bde8-cccabee5e2e7",
    "correlationId": "",
    "properties": {""},
    "content":
    {
        //Hier der eigentliche Nachrichteninhalt.
    }
}

Regeln für den Austausch von Nachrichten

Struktur des Message Directory

Name und Unterverzeichnisse des Verzeichnisses für die Nachrichtendateien müssen dem folgenden Aufbau entsprechen:

AIP Agent Transfer → das Root-Verzeichnis des Nachrichtenaustauschs
- MessageInbox → für Nachrichten aus der Cloud an die lokale Applikation
- MessageOutbox → für Nachrichten der lokalen Applikation an die Cloud
- FileInbox → für Dateien, die z.B. als Anhang an eine Nachricht von der Cloud an die lokale Applikation übermittelt werden
- FileOutbox → Verzeichnis für alle ausgehenden Dateien, die keine message files sind

Innerhalb der FileOutbox kann es weitere Unterordner geben, deren Name die darin abgelegten Dateien für die weitere Verwendung in der Zielapplikation indexiert. Ein Beispiel ist der Unterordner DocumentArchive des PlantX Agents. Eine Datei, die dort gespeichert wird, wird automatisch in das Dokumentenarchiv von Q Plant aufgenommen und gemäss den Dokumentenregeln verarbeitet. Eine andere Datei, die ausserhalb dieses Unterordners in der FileOutbox gespeichert wird, wird zwar ebenfalls in die Cloud übertragen. Dort jedoch wird sie nur im Speicher abgelegt und nicht weiter verarbeitet.

Konsum der Nachrichtendateien

Nachrichtendateien im Verzeichnis MessageOutbox sowie der Inhalt in den Unterverzeichnissen von FileOutbox werden vom Agent konsumiert. D.h. sie werden gelesen, verarbeitet und schliesslich gelöscht. Ist eine dort abgelegte Datei noch vorhanden, dann bedeutet dies, dass sie noch nicht an die Cloud übermittelt wurde.

Verhalten des Agents bei Fehlern

Outbox-Nachrichten bzw. -Dateien werden nicht gelöscht, sondern bleiben in ihren Verzeichnissen liegen, wenn einer der folgenden Fehler vorliegt:

Der Rumpf einer Nachrichtendatei entspricht nicht dem oben definierten Muster
Die Werte von type oder version sind ungültig, oder beides passt nicht zueinander
Nachricht oder Datei liegen nicht im vorgesehenen Verzeichnis
Die Verbindung zwischen Agent und Cloud ist zurzeit unterbrochen

In allen anderen Fällen wird die Datei konsumiert und an den IoT-Hub übermittelt. Insbesondere der Inhalt des content-Objekts wird dabei nicht überprüft. Es ist also möglich, Nachrichten mit ungültigem Inhalt zu senden, welcher von der Zielapplikation in der Cloud nicht verarbeitet werden kann. Um dies auszuschliessen, muss die Implementierung sich streng nach den Vorgaben in der jeweiligen Dokumentation der Einzelschnittstelle richten.

Einrichtung der Schnittstelle und Ping-Nachricht

Schnittstelle einrichten

Ähnlich wie bei den REST-Schnittstellen müssen Sie sich auch für den Gebrauch einer Agent-Schnittstelle bei Q Point registrieren. Bitte wenden Sie sich hierfür an den Q Point Support.
Mit der Registrierung erhalten Sie neben der Agent-Software auch einen individuellen Zugangscode, den access key.
Installieren Sie den Agent auf Ihrem Gerät.
Starten Sie den Agent und klicken Sie den Button "Neue Verbindung einrichten" (siehe linken Screenshot unten).
In der Eingabemaske, die nun erscheint, geben Sie bitte den access key ein. Klicken Sie anschliessend auf Speichern. (siehe rechten Screenshot unten.) Falls ihr Gerät mit dem Internet verbunden ist, wird der Agent nun die Cloud-Verbindung aufbauen und ist einsatzbereit.
Vergewissern Sie sich, dass das oben beschriebene Verzeichnis für Nachrichtendateien und Anhänge existiert.

Ping-Nachricht senden

Ist die Agent-Schnittstelle eingerichtet, dann legen Sie im Verzeichnis .../AIP Agent Transfer/MessageOutbox eine Datei mit folgendem Inhalt ab:
Ping Message
{ "type": "ping" , "version": "2.0" , "sentDto": "2019-03-15T05:39:03+01:00", //Beispiel-Datum "messageId": "4f3fe94e-a9f3-4006-bde8-cccabee5e2e7", //Beispiel-ID "correlationId": "", "properties": {""}, //Die Ping-Nachricht hat kein 'content'-Objekt }
Prüfen Sie anschliessend das Verzeichnis .../AIP Agent Transfer/MessageInbox. Wenn Sie dort die folgende Ping-Reply-Nachricht finden, dann hat der Datenaustausch über die Cloud funktioniert.
Ping Reply Message
{ "type": "pingReply" , "version": "2.0" , "sentDto": "2019-03-15T05:39:40+01:00", "messageId": "97eea7b5-07d8-46e8-acb1-e71f0bdd3457", "correlationId": "4f3fe94e-a9f3-4006-bde8-cccabee5e2e7", //entspricht der 'messageId' der vorherigen Ping-Nachricht. "properties": { "originalSentDt": "2019-03-15T05:39:03+01:00" //entspricht dem Sendezeitpunkt der vorherigen Ping-Nachricht. }, //Die Ping-Reply-Nachricht hat kein 'content'-Objekt }

PDF-Dokumente hochladen

Im Ordner /FileOutbox/DocumentArchive können PDF-Dokumente abgelegt werden, die der Q Plant Agent dann ins Dokumentenarchiv von Q Plant überträgt. Voraussetzung ist neben dem Ablageort die richtige Kennzeichnung der Datei mit Metadaten. Diese Daten werden von Q Plant benötigt, um das Dokument innerhalb des Archivs zu verarbeiten und zu indexieren. Die PDF-Metadaten bestehen aus Key-Value-Paaren. Weitere Informationen zur Verwaltung von PDF-Metadaten finden Sie auf den Hilfe-Seiten von Adobe.

Bezeichnung der PDF-Dateien

Die Bezeichnung der einzelnen PDF-Dateien muss dem nachfolgenden Schema entsprechen:

[Dokumententyp][GUID Businessobjektes][Versionsindex].pdf

Dokumententyp	Kennung des jeweiligen Dokumententyps (z.B.: ‘LS’ für Lieferscheine)
GUID Businessobjekt	GUID des Businessobjektes, welches das Dokument beschreibt oder dokumentiert
Versionsindex	Fortlaufender Index (one based) der Dokumentenversion

Rechnungs-Dokumente

Bei Rechnungen sind die folgenden Metadaten-Felder vorgesehen:

PDF-Metadaten für Rechnungsdokumente
pdf.Info.Title String Required	Bezeichnung oder Alias eines Dokuments. Wird auf der Benutzeroberfläche dargestellt und muss nicht eindeutig sein.
pdf.Info.Author String Required	Name und optional die Version der Software, welche das Dokument erzeugt hat.
pdf.Info.Elements.ContentType String Required	Die Dokumentenart. Für Rechnungen ist dies die Konstante "RE".
pdf.Info.Elements.Description String	Optionale Beschreibung des Dokuments. Wird auf der Benutzeroberfläche dargestellt.
pdf.Info.Elements.ProcessId GUID Required	GUID des Datenobjektes, auf welches sich das Dokument bezieht. Q Plant benötigt diese ID, weil sich das selbe Dokument mehrfach in Form unterschiedlicher Versionen übermitteln lässt.
pdf.Info.Elements.InvoiceIdentifier String Required	Rechnungsnummer (gegeben vom Fremdsystem z.B. ERP's etc.).
pdf.Info.Elements.IssueDt datetime Required	Zeitpunkt, zu welchem die Rechnung erstellt wurde. Dieser Zeitpunkt liegt in der Regel vor dem Erstellungszeitpunkt des zu archivierenden Dokuments. Zeitwerte sind gemäss ISO8601 zu formatieren.
pdf.Info.Elements.DocketNumbers List of string values (semicolon-separated)	1 oder mehrere Semikolon getrennte Lieferschein-Nummern (Reihenfolge korreliert mit DeliveryNoteIds). Wird verwendet, wenn das PDF neben der Rechnung zusätzlich auch die Lieferscheine enthält.
pdf.Info.Elements.DeliveryNoteIds List of UUID values (semicolon-separated)	1 oder mehrere Semikolon getrennte Lieferschein-Id's (Reihenfolge korreliert mit DocketNumbers).
pdf.Info.Elements.MasterDataSetIdentifier String	Kennung des Stammdaten-Sets, aus welchem der Kunden- und Baustellen-Datensatz stammt. Diese Angabe entfällt, wenn das Q Plant Kundensystem keine segmentierte Stammdaten verwendet.
pdf.Info.Elements.Customer String Required	Kunde Semikolon getrennt : {KundeKennung};{KundeName};{KundeStrasse};{KundeOrt};{KundePLZ}.
pdf.Info.Elements.ConstructionSiteIdentifiers List of string values (semicolon-separated)	1 oder mehrere Semikolon getrennte Baustellen-Kennungen (Reihenfolge korreliert mit ConstructionSiteNames). Im Allgemeinen handelt es sich hierbei um die Baustellen-Nummer.
pdf.Info.Elements.ConstructionSiteNames List of string values (semicolon-separated)	1 oder mehrere Semikolon getrennte Baustellen-Namen (Reihenfolge korreliert mit ConstructionSiteIdentifiers).
pdf.Info.Elements.PlantIdentifiers String	1 oder mehrere Semikolon getrennte Mischwerks-Kennungen
pdf.Info.Elements.SchemaVersion integer Required	Version des Metadaten-Schemas (das hier dokumentierter Schema besitzt die Version '2'). Diese wird durch Q Point festgelegt.

Beispiel

Bezeichnung der PFD-Dateien

Die Bezeichnung der PDF-Dateien erfolgt nach dem Schema: RE_{GUID}_Versionsindex.pdf

Beispiel: RE_86ce30-e9b8-41b1-9e48-c86093049161_1.pdf

Lieferschein-Dokumente

Bei Lieferscheinen sind die folgenden Metadaten-Felder vorgesehen:

PDF-Metadatenfelder für Lieferscheindokumente
pdf.Info.Title String Required	Bezeichnung oder Alias eines Dokuments. Wird auf der Benutzeroberfläche dargestellt und muss nicht eindeutig sein. In der Regel werden hier Titel wie beispielsweise "Lieferschein: 3456877" eingesetzt.
pdf.Info.Author String Required	Name und optional die Version der Software, welche das Dokument erzeugt hat.
pdf.Info.Elements.ContentType String Required	Die Dokumentenart. Für Lieferscheine ist dies die Konstante "LS".
pdf.Info.Elements.Description String	Optionale Beschreibung des Dokuments. Wird auf der Benutzeroberfläche dargestellt.
pdf.Info.Elements.ProcessId GUID Required	GUID des Datenobjektes, auf welches sich das Dokument bezieht. Q Plant benötigt diese ID, weil sich das selbe Dokument mehrfach in Form unterschiedlicher Versionen übermitteln lässt. So werden unterschiedliche Versionen eines Lieferscheins jeweils mit derselben ProcessId übermittelt.
pdf.Info.Elements.DocketNumber String Required	Lieferscheinnummer. Sowohl der Wert als auch die Formatierung der Nummer wird durch dasjenige System bestimmt, welches den Lieferschein ausgibt. In der Regel handelt es sich hierbei um das Wiegesystem der Mischanlage.
pdf.Info.Elements.IssueDt datetime Required	Zeitpunkt, zu welchem der Lieferschein erzeugt wurde. In der Regel entspricht dies dem Zeitpunkt der Bruttowiegung auf der Mischanlage. Diese Zeitpunkt wird durch die Mischanlage bzw. durch dasjenige System bestimmt, welche den Lieferschein ausgibt. Zeitwerte sind gemäss ISO8601 zu formatieren.
pdf.Info.Elements.Customer String Required	Kunde Semikolon getrennt : {KundeKennung};{KundeName};{KundeStrasse};{KundeOrt};{KundePLZ}.
pdf.Info.Elements.ConstructionSite String Required	Baustelle Semikolon getrennt: {BaustelleKennung};{BaustellenName};{BaustellenStrasse};{BaustellenOrt};{BaustellenPLZ}.
pdf.Info.Elements.OperatingCompany String	Betreiberfirma Semikolongetrennt: {BetreiberfirmaKennung};{BetreiberfirmaName}.
pdf.Info.Elements.PlantIdentifier String Required	Kennung des Mischwerks.
pdf.Info.Elements.SchemaVersion integer Required	Version des Metadaten-Schemas (Das hier dokumentierter Schema besitzt die Version '2'). Diese wird durch Q Point festgelegt.