Allgemeines

Die HTTP-Schnittstelle stellt folgende Dienste bereit:

Anmeldevorgang (connect)

http://hostname/app-tunnel/connect?user=INETUSER&pwd=xxx&host=oxaion

<ID>13032933474483</ID> 

Aufruf eines oxaion-Programmes (call)

http://hostname/app-tunnel/call?user=13032933474483&pgmn=US10100J&akto=*READ&LALANR=003

<?xml version="1.0" encoding="UTF-8" ?> 
<PARM> 
	<DTA> 
		<LALCDA>HOL</LALCDA> 
		<LAASBZ>7</LAASBZ> 
		<TX_XSPR>Niederländisch</TX_XSPR> 
		<LAASBK>10</LAASBK> 
		<LAIBRL>E</LAIBRL> 
		<LAKPLZ>N</LAKPLZ> 
		<LAPLNM>N</LAPLNM> 
		<LAYLAE>2010-11-07</LAYLAE> 
		<LADCTZ>.</LADCTZ> 
		<LALNAM>Niederlande</LALNAM> 
	</DTA> 
	<ATR /> 
</PARM>

Anmeldung und Aufrufe mit BasicAuth

Für oxaion open ab Version 2021.5306.1 ist es alternativ möglich, die Anmeldung mit BasicAuth durchzuführen.

Dabei erfolgt das Login nicht separat durch /connect, sondern integriert mit /call.
Die Anmeldeinformationen werden dafür im Request-Header übergeben.
In der Anwort der HTTP-Schnittstelle wird ein Cookie mitgeliefert, worüber nach der Anmeldung weitere Aufrufe möglich sind.
Die Abmeldung erfolgt analog wie beschrieben für /disconnect.

http://hostname/app-tunnel/call?pgmn=US10100J&akto=*READ&LALANR=003

<?xml version="1.0" encoding="UTF-8" ?> 
<PARM> 
	<DTA> 
		<LALCDA>HOL</LALCDA> 
		<LAASBZ>7</LAASBZ> 
		<TX_XSPR>Niederländisch</TX_XSPR> 
		<LAASBK>10</LAASBK> 
		<LAIBRL>E</LAIBRL> 
		<LAKPLZ>N</LAKPLZ> 
		<LAPLNM>N</LAPLNM> 
		<LAYLAE>2010-11-07</LAYLAE> 
		<LADCTZ>.</LADCTZ> 
		<LALNAM>Niederlande</LALNAM> 
	</DTA> 
	<ATR /> 
</PARM>

Abruf eines oxaion Reports (report)

http://hostname/app-tunnel/report?user=13032933474483&id=25 

Abmelden (disconnect)

http://hostname/app-tunnel/disconnect?user=13032933474483 

<OK/>

Automatisches Abmelden beim nächsten Programmaufruf (setDisposable)

Durch Aufruf dieses Dienstes wird beim nächste Aufruf eines oxaion-Programmes (call) der User automatisch abgemeldet.

http://hostname/app-tunnel/setDisposable?user=13032933474483 

<OK/>

System-Fehler

Fachliche Fehler eines oxaion-Programmes (bspw. Preis nicht gefunden) werden wie im Abschnitt Fehler beschrieben zurück geliefert.

Technische Fehler werden wie folgt zurück geliefert:

<ERROR ID="TUN0001">
	<![CDATA[ 
		CODE: TUN0001INFO: 20.04.2016 12:23:47 csoxe01.cmd-intern.de
		SHORT: Authentifizierung fehlerhaft
		LONG: Authentifizierung fehlerhaftcom.oxaion.jet.server.jetty.tunnel.ConnectHandler.getUser(ConnectHandler.javacom.oxaion.jet.server.jetty.tunnel.CallHandler.handle(CallHandler.java:41)
		org.eclipse.jetty.server.handler.ContextHandler.doHandle(ContextHandler.java)]]/> 
</ERROR>

Auswahl des Rückgabeformats

Das Rückgabeformat ist normalerweise XML. Es besteht allerdings auch die Möglichkeit das Rückgabeformat zu beeinflussen.

JSON

Um die Daten als JSON anstatt XML zu erhalten, muss an den http-Request der Parameter

responseFormat=json

angehängt werden. Dieser Parameter muss an jeden Request angehängt werden, ansonsten wechselt das Rückgabeformat wieder auf XML.

Wenn das Rückgabeformat JSON ist, kann durch den zusätzlichen Parameter

prettyPrint=true

die JSON-Rückgabe mit Zeilenumbrüchen und Einrückungen versehen werden, damit sie besser gelesen werden kann. Dies ist vor allem zum Entwicklungszeitpunkt sinnvoll. Danach sollte man diese Funktion nicht nutzen, da sie nur zusätzliches Datenaufkommen produziert.

Javascript-Callback (JSONP)

Wenn die http-Schnittstelle direkt per Javascript aus einer Webseite aufgerufen werden soll, welche nicht unter dem gleichen Hostnamen läuft, blockiert der Webbrowser normalerweise sämtliche Ajax-Requests auf andere Hosts und dadurch auch auf die oxaion http-Schnittstelle. Um diese Problematik zu umgehen, kann eine Callback-Methode verwendet werden. Dazu sendet der Aufrufer der http-Schnittstelle den Namen einer Callback-Methode mit. Die http-Schnittstelle liefert dann eine Javascript-Datei zurück, welche nichts anderes macht, als die Methode mit diesem Namen aufzurufen und dort die Daten als Parameter zu übergeben.

Für die Angabe des Namens der Callback-Methode wird der Parameter

callback

verwendet.

Dieses Rückgabeformat funktioniert sowohl mit JSON, also auch mit XML-Daten. JSON-Daten werden als JSON-Objekt übergeben. XML-Daten werden als String übergeben.

Aufruf per HTTP-POST

Bei Aufrufen einiger Programme kann es vorkommen, dass aufgrund der Anzahl oder Länge der Parameter die maximal erlaubte Länge von URLs überschritte wird, wenn der Aufruf wie oben beschrieben per HTTP-GET durchgeführt wird. In diesem Fall wird die Anfrage mit dem Fehler "414 uri too long" abgelehnt. Dies kann vermieden werden, wenn die Anfrage stattdessen per HTTP-POST durchgeführt wird. Dies bedeutet, dass eine GET-Anfrage in der Form

http://hostname/app-tunnel/call?user=13032933474483&pgmn=US10100J&akto=*READ&LALANR=003

in eine POST-Anfrage an die URL

http://hostname/app-tunnel/call

mit folgenden Daten im Body ausgetauscht wird.

user=13032933474483&pgmn=US10100J&akto=*READ&LALANR=003

Hierbei muss dann im HTTP-Header der Parameter "Content-Type" mit dem Wert "application/x-www-form-urlencoded" mitgegeben werden.

Zentrale Schlüsselwerte

Bei Prozessen, die sich über mehrere call-Aufrufe der HTTP-Schnittstelle ziehen, werden beim ersten Aufruf auf Seiten des Servers ggf. Daten im Hauppeicher gehalten, die erst mit den nachfolgenden Aufrufen verarbeitet werden. Damit der Server diese Daten dem aktuellen Prozess zuordnen kann, gibt es mehrere IDs und Schlüsselwerte , die je nach Prozess relevant sein können.

Session-ID

Dies ist die von der login-Methode zurückgegebene ID. Sie wird in allen weiteren Aufrufen als Parameter "user" mitgegeben. Alle Daten, die im Hauptspeicher vorgehalten werden, werden mit dem Abmelden der Sitzung (sowohl direkt als auch über den Auto-Disconnect) entfernt. Es sollte generell sichergestellt werden, dass keine zwei Zugriffe mit der gleichen Session-ID über die HTTP-Schnittstelle erfolgen, da nicht alle Prozesse auf den Parallelbetrieb mit der selben Anmeldung ausgelegt sind.

Aktivierungsgruppe

Über den oxaion-Client können mehrere Programme parallel geöffnet werden, die dann in getrennten Laschen angezeigt werden. Diese Laschen haben jeweils eine sogenannte Aktivierungsgruppe, die bei Zugriffen als Schlüssel für die Daten im Haupspeicher genommen wird. Diese ID kann über die HTTP-Schnittstelle als Parameter actg mitgegeben, als Standard wird der Wert "DEFAULT_ACTG" genommen. Solange die Aktivierungsgruppe innerhalb einer Prozessausführung konsistent ist, können hier beliebige IDs vom Aufrufer mitgegeben werden.

SSID

Damit es möglich ist, eine Auflistung mit einem bestimmten Filter in einer neuen Lasche zu öffnen, sind die Daten der Listpgrogramme innerhalb einer Session nicht über die Aktivierungsgruppe gespeichert. Stattdessen gibt es eine sogenannte SSID, hinter der z.B. der aktuelle Filter oder der aktuell gelesene SQL gespeichert werden. Alle Transaktionen, die auf einem Listprogramm agieren, müssen somit eine SSID übergeben bekommen. Die SSID muss dabei von einem vorherigem Aufruf vom Server generiert und zurückgegeben werden.

Keytype

Bei Transaktionen, die aus einem Explorer heraus aufgerufen werden, wird im Feld KEYTYPE immer der Name des Knotens mitgegeben, auf dem die Transaktion aufgerufen wird. Z.B. ist das VAKOPF für den VKS-Auftragskopf und VAMPOS für die Auftragspositionen. Stößt man diese Prozesse über die HTTP-Schnittstelle an, müssen auch hier immer der jeweilige KEYTYPE mitgegeben werden. Der Keytype eines Explorerknoten lässt sich ermitteln, indem man mit gedrückter Alt-Taste einen Rechtsklick auf den jeweiligen Knoten macht und die Option "Feldinformationen anzeigen" auswählt.