XML Server

Vertec ist mit einer XML Schnittstelle ausgerüstet. Damit können Anfragen in XML formuliert und via http an den Vertec Dienst geschickt werden. Die Antwort kommt ebenfalls in XML formatiert.

Damit lassen sich alle Daten aus Vertec abfragen, ändern, erzeugen oder löschen. Die Schnittstelle kann dazu verwendet werden, alternative Clientapplikationen zu implementieren, welche die Applikationslogik und Datenspeicherung von Vertec verwenden.

Der XML Server kann über den Vertec Service oder ab Vertec 6.1.0.10 auch über den Cloud Server betrieben werden.

Bei Neuinstallationen von Vertec werden ab Version 6.1.0.10 die Einstellungen automatisch so gesetzt, dass der XML Server über den Cloud Server betrieben wird. Bei bestehenden Installationen muss die Umstellung manuell erfolgen. Nach dem Setzen der entsprechenden Einstellungen im Vertec.ini File müssen der Vertec Service sowie der Cloud Server neu gestartet werden.

XML Server über den Cloud Server

Mit Vertec Version 6.1.0.10 wurde der XML Server in den Cloud Server integriert. Das deckt folgende Anforderungen ab:

  1. Die Authentisierung erfolgt via Cloudserver Authentication System. Damit ist der XML Server nun ebenfalls LDAP fähig.
  2. Pro XML Session kann so ein eigener Vertec.Session Prozess gestartet werden. Damit können Probleme mit langlaufenden Sessions vermieden werden.

Damit der XML Server aktiviert wird, muss im Vertec.ini folgende Einstellung gesetzt sein:

[CloudServer]
XML Server = true

Authentisierung

Wird der XML Server über den Cloud Server betrieben, muss der Client einen Authentisierungs-Request mit Angabe von Username/Password an den Cloud Server senden. Als Antwort erhält er ein Authentisierungs-Token, welches bei jedem Request im XML Request eingesetzt werden muss. Die genaue Beschreibung finden Sie in der XML Schnittstellen Beschreibung.

Beim Token handelt es sich um ein signiertes Token gemäss dem JWT (java web token) Standard. Es enthält folgende Angaben, die vom Server ausgewertet werden:

  • SessionId: eine XML Session-ID (siehe Session Handling unten)
  • UserId: die interne ID des eingeloggten Bearbeiters
  • Expiration-Date: 1 Tag ab Ausgabe-Datum

Alle ausgegebenen Tokens sind nach einem Neustart des Cloud-Servers nicht mehr gültig (der private Key für die Signatur wird beim Starten des Cloud-Servers gewürfelt).

Session Handling

  • Bei einem XML Request auf /xml wird zuerst das Token auf Gültigkeit und Ablaufdatum geprüft.
  • Anschliessend wird geprüft, ob für die XML Session-ID bereits eine Vertec-Session läuft. Falls ja, wird der Request dieser Session übergeben.
  • Falls noch keine Session für die angegebene XML Session-ID existiert, wird eine angelegt (bzw. aus dem Idle Pool genommen).
  • Das erlaubt ein kontrolliertes Session Management aufgrund des übergebenen Tokens. Wenn der Client in einem XML Request ein neues Token angibt, startet der Cloud Server dafür eine neue Session.
  • Eine XML Session hat einen Session Timeout. Wenn für die Zeit des Timeout kein neuer Request für die Session empfangen wird, dann wird die Session beendet. Das ist sinnvoll, damit vom Client in kurzer Folge abgesetzte Requests auf dieselbe Session kommen. Der Session Timeout beträgt standardmässig 5 Minuten, kann aber im Vertec.ini gesetzt werden:

    [CloudServer]
    XML Session Timeout = 10
  • Das Token kann während seiner Gültigkeit (1 Tag) weiterverwendet werden. Wenn die Session aufgrund des Timeouts beendet wurde, wird einfach eine neue Session gestartet. Dank den Idle Sessions ist die Verzögerung auch bei einer neuen Session minimal.

Testen der XML Schnittstelle via Cloud Server

Zum Testen von XML Request steht eine einfache Web-Oberfläche unter /xml/query zur Verfügung.

  1. Zuerst stehen 2 Felder für Username und Passwort zum Generieren eines Tokens zur Verfügung.
  2. Dann öffnet sich die Testing-Oberfläche. Im oberen Bereich kann ein XML Request (nur Body Element) angegeben werden. Envelope und Header mit eingesetztem Token werden beim Absenden automatisch zusammengestellt.
  3. Das Ergebnis-XML wird unterhalb dargestellt.

 

Beachten Sie bitte, dass Sie damit unter Umständen auf Ihre reale Datenbank zugreifen und sich Datenänderungen auf Ihre realen Daten auswirken können, sofern Sie nicht eine unabhängige Testinstallation eingerichtet haben.

XML Server über den Vertec Service

Damit Sie den XML Server über den Vertec Service verwenden können, muss auf dem Server der Vertec Service installiert sein. Die Konfigurations-Angaben werden im Abschnitt [XMLServer] im Vertec.ini vorgenommen.

[XMLServer]
Server Port = 8090
Session Timeout = 60

Der XML Server ist so erreichbar über http://server:8090/.

Integration von XML Server in Webserver

Mit Vertec Version 5.7 wurde der XML Server umgestellt und wurde Teil des Classic Webservers. Das bedeutet, dass der XML Server in der Konfigurationsdatei Vertec.ini in eine bestehende Webserver Section eingebunden werden kann, via entsprechende Applikationsangabe. Beispiel:

[Webserver]
Server Port=8095
Apps=/ webserver.webgui.WebGui, /xml webserver.XmlServer.XmlServer

macht einen Webserver auf Port 8095, mit Classic Weberfassung auf / und einem XML Server auf /xml.

Der XML Server ist damit erreichbar über http://server:8095/xml.

Die bisherige [XMLServer] Section im Vertec.ini wird wie bisher behandelt.

Testen der XML Schnittstelle

Zum Testen der XML Schnittstelle via Vertec Service gibt es eine Testapplikation namens HttpTest.exe. Diese nehmen Sie wie folgt in Betrieb:

  • Kopieren Sie die Datei HttpTest.exe in Ihr Vertec Installationsverzeichnis
  • Der Vertec Service muss laufen
  • Doppelklicken Sie auf HttpTest.exe. Es öffnet sich folgendes Fenster:

  • Über den Button Load können Sie eine XML Message auswählen. Sie können aber auch im 'Request'-Feld eine Message zusammenstellen (und diese über den Button Save in eine Datei sichern).
  • Klicken Sie dann auf den Button POST. So senden Sie den Request ab. Die Response (Antwort-Meldung) erhalten Sie im 'Reponse'-Feld im rechten Teil des Fensters.

Beachten Sie bitte, dass die Testapplikation auf das gleiche Vertec.ini und damit auf die gleiche Standard-Datenbank zugreift wie das Vertec. Datenänderungen können sich also unter Umständen auf die realen Daten auswirken, sofern für das Testsystem nicht eine unabhängige Vertec Testinstallation mit separatem Vertec Service eingerichtet wird.


23.01.2004 | 25.04.2017: Betrieb des XML Servers via Cloud Server beschrieben. HTTP Tester integriert (separater Artikel gelöscht).