Einführung

Internal Webservices

Operationen des Webservices

---

Verwendung des Webservices

Das Internal Webservice ist das Bindeglied zwischen Webclient und Automation Engine System. Der Webclient ruft Operationen des Webservices auf. Dieses verwendet einen AE-Benutzer, um sich am Automation Engine System anzumelden und die Operationen durchzuführen. Das Ergebnis wird anschließend an den Webclient geschickt.

Es stehen zwei Methoden zur Verfügung, um über das Webservice auf das Automation Engine System zuzugreifen.

Sie können beliebige Programmiersprachen für die Erstellung des Webclients verwenden. Die folgenden Beispiele sind in Java geschrieben.

Variante 1: Standard-Benutzer

Geben Sie auf der Konfigurations-Weboberfläche einen AE-Benutzer an, den Sie für den Zugriff auf das Automation Engine System nutzen möchten. Das Webservice verwendet den Standard-Benutzer immer dann, wenn der Webclient keine Session-ID (siehe zweite Methode) mitliefert.

Für die Kommunikation mit dem Webservice wird zunächst ein Port vom Typ "Uc4PortType" benötigt:

Uc4PortType port = new UC4Service().getUc4Port();

Sie können über diesen Port die Operationen des Webservices aufrufen und z.B: eine Liste aller Agenten des Mandanten holen:

List<AgentListItem> list = port.getAgentList();

Variante 2: Session mit beliebigem Benutzer

Der Standard-Benutzer ist auf einen Mandanten beschränkt. Möchten Sie auf verschiedene Mandanten zugreifen oder verschiedene Benutzer für die Anmeldung verwenden, müssen Sie eine Session anlegen.

Für die Kommunikation mit dem Webservice wird zunächst wieder ein Port vom Typ "Uc4PortType" benötigt:

Uc4PortType port = new UC4Service().getUc4Port();

Melden Sie sich anschließend mit Hilfe der Operation logon an. Der AE-Benutzer wird mit Hilfe der Parameter übergeben. Sie erhalten als Rückgabewert eine Session-ID, die Sie im HTTP-Header setzen können. So wird sie bei jedem Operationsaufruf automatisch mitgegeben.

try{
String sessionID = port.logon(100, "SMITH", "UC4", "top-secret password", (bytes) 'D');

Map<String, List<String>> requestHeaders = (Map<String, List<String>>) context.get(MessageContext.HTTP_REQUEST_HEADERS);

if(requestHeaders == null) {
requestHeaders = new HashMap<String, List<String>>();
context.put(MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);
}

requestHeaders.put("id", Arrays.asList(sessionID));

} catch(UC4WSException e){
System.out.println("ERROR: " + e.toString());
}

Sie können über den Port die Operationen des Webservices aufrufen und z.B: Datenbank-Informationen aus der Systemübersicht auslesen:

DatabaseInformation dbInfos = port.getDatabaseInfo();
String dbName = dbInfos.getDbName();

Beenden Sie die Session mit Hilfe der Operation "logoff":

port.logoff(sessionID);

Das Webservice schließt automatisch Verbindungen, die über einen gewissen Zeitraum nicht genutzt werden. Die Länge für dieses Timeout stellen Sie auf der Konfigurations-Weboberfläche ein.

Befüllen von :READ-Masken

Das Webservice enthält unter anderem eine Operation namens executeObject, mit der Sie Objekte starten können. Einer der Parameter bietet die Möglichkeit Werte für Script-Variablen in :READ-Masken zu übergeben. Sehen wir uns folgendes Beispiel an:

Der Workflow MAWI.TAG enthält die folgende :READ-Maske:

:BEGINREAD "Print parameters"
:READ &TITLE#,"00","Please enter a title"
:READ &NUMBER#,"0-5","Please enter a number",,"N"
:ENDREAD

Die Zuweisung Wert zu Script-Variable erfolgt nicht über den Variablennamen, sondern über die Beschriftung des Eingabefeldes. Sehen wir uns dazu folgenden Auszug an. Zuerst wird eine Liste angelegt, welche die Werte speichern soll. Anschließend wird der Wert für die Script-Variable &UEBERSCHRIFT# definiert. Ihre Beschriftung lautet "Bitte Überschrift eingeben". Sie soll den Wert "Endabrechnung" erhalten. Dasselbe erfolgt für die Script-Variable &ANZAHL#. Zum Schluss wird die Operation "executeObject" aufgerufen und die Werteliste übergeben.

List<InputParameter> read = new ArrayList<InputParameter>();

InputParameter p1 = new InputParameter();
p1.setName("Please enter a title");
p1.setValue("Final account");
read.add(p1);

InputParameter p2 = new InputParameter();
p2.setName("Please enter a number");
p2.setValue(2);
read.add(p2);

int runID = port.executeObject("MAWI.TAG", "", read, null, false);

Auch wenn das Objekt mehrere :READ-Masken besitzt, benötigen Sie nur eine Werteliste.

Da die Zuweisung des Wertes über die Beschriftung erfolgt, sollte diese nicht mehrfach vorkommen.

Aus Performancegründen empfehlen wir eine größere :READ-Maske zur verwenden anstatt viele einzelne.

Fehlerbehandlung

Es können drei Arten von Fehlern auftreten:

1. Das Webservice kann keine Verbindung mit der Automation Engine aufbauen (z.B: Kommunikationsprozess nicht erreichbar, ungültige Anmeldedaten etc.)
2. Laufzeitfehler beim Ausführen der Operation (z.B: das zu startende Objekt existiert nicht)
3. Die SOAP-Nachricht, die der Webclient an den Webservice schickt, ist ungültig.

Das Webservice stellt eine Exception namens UC4WSException zur Verfügung. Sie enthält ein Info-Feld mit dem Sie auf die Meldungsnummer und den -text zugreifen können. Auch der Typ lässt sich auf diese Weise abfragen. Er ist entweder "CONNECT", wenn der Fehler beim Verbindungsaufbau aufgetreten ist, oder "REQUEST", wenn das Ausführen der Operation fehlerhaft war.

try{

String priority = port.getHighestNotificationPriority();

} catch(UC4WSException e){
System.out.println("Error number: " + e.getFaultInfo().getId();
System.out.println("Error text: " + e.getFaultInfo().getMessage);
}

Die Sprache in der die Meldungstexte an den Webclient übertragen werden, ist abhängig vom Zeitpunkt des Fehlers:

• Tritt der Fehler bei der Anmeldung auf, so ist der Text immer englisch.
• Tritt der Fehler nach einer erfolgreichen Anmeldung auf, so ist der Text in der Sprache mit der die Anmeldung durchgeführt worden ist. Ausnahme: Variable Teile der Fehlermeldung z.B: für Exceptions können auf englisch sein.
• SOAP-Faults enthalten üblicherweise englische Texte.

Siehe auch:

Operationen des Webservices