Nutzung des Webdiensts

Der AE Internal Webservice war die frühere Methode für die Kommunikation mit einem AE-System. Sie wird nur für Partner unterstützt, die noch alte Installationen und Integrationen verwalten müssen. Für neue Installationen und Integrationen ist die REST-API die neuere und bevorzugte Kommunikationstechnologie. Weitere Informationen finden Sie unter REST-API

Das AE Internal Webservice ist das Bindeglied zwischen Webclient und dem AE-System. Der Webclient ruft Operationen des Webdiensts. Dieser verwendet einen AE-Benutzer, um sich am AE-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 den Webdienst auf das AE-System zuzugreifen.

Das AE Internal Webservice ist das Bindeglied zwischen Webclient und dem AE-System. Der Webclient ruft Operationen des Webdiensts. Dieser verwendet einen AE-Benutzer, um sich am AE-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 den Webdienst auf das AE-System zuzugreifen.

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

Diese Seite beinhaltet Folgendes:

Methode 1: Standardbenutzer

Geben Sie den AE-Benutzer an, der für den Zugriff auf das AE-System bei der Konfigurations-Webschnittstelle für den Internal Webservice verwendet werden soll. Der Webdienst verwendet den Standard-Benutzer immer dann, wenn der Webclient keine Session-ID (siehe zweite Methode) mitliefert.

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

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

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

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

Methode 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 Webdienst 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 Webdiensts aufrufen und z. B. Datenbank-Informationen aus der Administration-Perspektive auslesen:

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

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

port.logoff(sessionID);

Hinweis: Der Webdienst 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.

:READ-Masken füllen

Der Webdienst 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 MM.DAY enthält die folgende :READ-Maske:

:BEGINREAD "Druckparameter"
:READ &TITLE#,"00","Bitte geben Sie einen Titel ein"
:READ &NUMBER#,"0-5","Bitte geben Sie eine Zahl ein",,"N"
:ENDREAD

Weitere Informationen finden Sie unter: :BEGINREAD... :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 &TITLE# definiert. Beschriften Sie sie mit Bitte geben Sie einen Titel ein. Sie soll den Wert Endabrechung erhalten Jetzt definieren Sie die Script-Variable &NUMBER#. Zum Schluss werden die Operation executeObject aufgerufen und die Werteliste übergeben.

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

InputParameter p1 = new InputParameter();
p1.setName("Bitte geben Sie einen Titel ein");
p1.setValue("Final account");
read.add(p1);

InputParameter p2 = new InputParameter();
p2.setName("Bitte geben Sie eine Zahl ein");
p2.setValue(2);
read.add(p2);

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

Hinweise:

  • Auch wenn das Objekt mehrere :READ-Masken besitzt, benötigen Sie nur eine Werteliste.
  • Da die Zuweisung des Wertes über die Beschriftung der Eingabefelder erfolgt, empfiehlt CA Automic, eindeutige Beschriftungen zu erstellen, um Verwechslungen zu vermeiden.
  • Aus Leistungsgründen empfiehlt CA Automic, eine größere :READ-Maske zu verwenden, statt mehrerer einzelner.

Fehlerbehandlung

Es können drei Arten von Fehlern auftreten:

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

Der Webdienst stellt eine Ausnahme 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 Ausnahmen) können auf Englisch angezeigt werden.
  • SOAP-Fehler enthalten üblicherweise englische Texte.

Siehe auch:

Operationen des Webdiensts