Vorgangsraum-API

Für die Kommunikation mit dem Vorgangsraum kann ein SOAP Webservice genutzt werden. Dieser dient als Transportmedium für eine Vielzahl von Dateiformaten. Unterstützt werden XÖV Nachrichtenformate wie XBau oder XMeld, aber auch individuell vereinbarte XML Schema zur automatischen Validierung ein- und ausgehender Nachrichten.

Der Vorgangsraum-Webservice bietet drei Methoden

• transmitMessage = Anliefern einer Nachricht inkl. Anlagen
• getMessage = Abholen einer Nachricht inkl. Anlagen
• queryMessages = Abfrage aller noch nicht durch das Fachverfahren abgeholten Nachrichten, bzw. seit dem letzten Abholen neu eingegangen Nachrichten

Zugriff

Ein üblicher Webservice Endpunkt ist wie folgt aufgebaut:

https://domain/ws/vgv/soap/v2.0/?wsdl

Der Zugriff auf den Webservice erfolgt Kanal verschlüsselt via Https. Die Methoden des Webservices können nur mit gültigen Anmeldedaten genutzt werden. Die Zugangsdaten sind als als WS-Security Header (Verfahren basicAuth, Username, PasswordText) mitzusenden.

Um eine performante Übertragung größerer Dateien zu ermöglichen unterstützt der Webservice die SOAP Message Transmission Optimization Mechanism (MTOM) Technologie.

Anlieferung von Nachrichten „transmitMessage“

Das Erzeugen von Nachrichten im Vorgangsraum erfolgt über die SOAP Webservice Methode „transmitMessage“. Diese Methode erwartet als einzige Pflichtparameter die eindeutige ID des Antrags und die Nachricht als XML Datei. Weitere Anlagen können als Anlagen hinzugefügt werden. Darüber hinaus können zusätzliche Parameter wie eine DVDV Kennung für die eindeutige Adressierung übergeben werden (für XÖV Nachrichten nicht notwendig).

Abfrage neuer Nachrichten „queryMessages“

Um eine Liste aller aus Sicht des Fachverfahrens neuen Nachrichten zu ermitteln, ist die Methode „queryMessages“ aufzurufen. Das Ergebnis dieses Aufrufs ist eine Liste aller noch nicht abgeholten Nachrichten (ID‘s). Die Ergebnisliste ist auf maximal 1000 Einträge begrenzt. Mit Hilfe eines Paginierung-Mechanismus können weitere 1000er Blöcke abgefragt werden. Zusätzlich lässt sich die Suche mit Hilfe von Datumsfiltern eingrenzen.

Eine Nachricht abrufen „getMessage“

Das Abrufen von Nachrichten erfolgt mit Hilfe der Methode „getMessage“. Für das Abrufen der Nachricht muss die eindeutige Nachricht ID übergeben werden. Als Ergebnis erhalten Sie die  Nachricht als XML-Datei inklusive aller Dateianlagen. Die Dateianlagen werden ebenfalls mit der MTOM Technologie übertragen. Im gewünschten Ausgabe-Nachrichtenformat sollte  ein eindeutiger Bezug zwischen den übertragenen Anlagen in der Nachricht hergestellt werden können (Beispiel: XBau „referenzPrimaerdokument“). Außerdem können individuelle Anpassungen (z. B. an Dateinamen oder anderen Kennzeichen) im Nachrichten Format vereinbart werden.

Interne Funktion: Quittierung der Abholung

Das Abrufen einer Nachricht via „getMessage“ wird im System vermerkt (quittiert). Wird die Methode „queryMessage“ anschließend aufgerufen, ist die gerade abgeholte Nachricht ID nicht mehr im Ergebnis enthalten.

Kennt das Fachverfahren die Nachrichten ID bereits, kann es die Nachricht jedoch jederzeit via „getMessage“ abholen.