Web-Services-Schnittstelle

Web-Services sind Schnittstellen für den entfernten Aufruf von Funktionen. Damit fallen Sie in dieselbe Kategorie von Schnittstellen wie CORBA.

Comarch ERP Enterprise enthält eine Web-Services-Schnittstelle mit einer Anbindung an den Business Integration Service (BIS) für die Funktion des Datenexports und -imports. Damit können Business Entitys über Web-Services in eine Client-Anwendung exportiert bzw. von dort importiert werden. Darüber hinaus können Hintergrund-Anwendungen über die Web-Services-Schnittstelle aufgerufen werden. Die Web-Services sind in diesem Dokument beschrieben.

Sie können eigene Web-Services programmieren, die entweder das Protokoll SOAP für entfernte Aufrufe verwenden bzw. REST-Prinzipien umsetzen. Nähere Informationen hierzu finden Sie im Dokument „Schnittstelle für programmierbare Web-Services“.

Im Gegensatz zur CORBA-Schnittstelle ist die Web-Services-Schnittstelle nicht auf den Transfer großer Datenmengen oder schnelle Antwortzeiten, sondern auf möglichst einfache Verwendbarkeit durch Clients ausgelegt, die keine komplexen Logiken oder Protokolle beherrschen.

Die Web-Services-Schnittstelle verwendet für die nicht programmierbaren Web-Services die frei erhältliche Web-Services-Bibliothek Apache Axis. Axis kann ebenfalls zur Implementierung von Clients in Java verwendet werden. Mehr Informationen über Axis erhalten Sie auf der Website von Axis:

http://ws.apache.org/axis/

Mit Comarch ERP Enterprise werden Beispiel-Clients sowohl für Java als auch für „Microsoft.Net“ ausgeliefert. Die Java-Clients basieren auf Axis, die „Microsoft.Net“-Clients sind in Form einer Microsoft-Excel-Arbeitsmappe mit dazugehörigem C#-Code realisiert. Die Beschreibung der Beispiel-Clients find Sie im Kapitel 6.

Hinweis:

Die Web-Service-Schnittstelle ist nicht geeignet große Datenmengen zu transportieren. Die empfangenen bzw. gesendeten Daten müssen unter Umständen vollständig im Hauptspeicher des Application-Servers aufbereitet werden. Dies kann den Application-Server stark belasten und erhebliche Leistungseinbussen verursachen.

1                     Zielgruppe

  • Anwendungsentwickler
  • Technische Berater

2                     Begriffsbestimmung

WSDL

Abkürzung für Web-Services Description Language. Die Beschreibungssprache für die Schnittstelle zu einem Web-Service.

SOAP

Abkürzung für „Simple Object Access Protocol“. Ein XML-basiertes Protokoll für den Austausch von Nachrichten in verteilten Systemen. SOAP wird zur Kommunikation zwischen Web-Services-Clients und –Servern verwendet.

3                     Beschreibung

3.1               Nicht programmierbare Web-Services

Comarch ERP Enterprise stellt vier nicht programmierbare Web-Services zur Verfügung, die das Protokoll SOAP für entfernte Aufrufe verwenden. Das sind zum einen der Datenexport, der Datenimport und die entfernte Suche als spezialisierte Web-Services. Zum anderen gibt es die Möglichkeit beliebige Hintergrund-Anwendungen aufzurufen.

3.1.1          Aufruf von Hintergrund-Anwendungen

Jede Hintergrund-Anwendung kann über diesen Web-Service aufgerufen werden. Die Hintergrund-Anwendungen können jedoch nur zustandslos aufgerufen werden („CallApplication“). Ein zustandsbehafteter Aufruf („RunApplication“), wie er in mit CORBA möglich ist, ist mit den Web-Services nicht möglich.

3.1.2          Datenexport

Dieser Web-Service kann zum Export der Daten eines Business Entitys genutzt werden. Durch einen in Comarch ERP Enterprise erfassten Filter wird die Anzahl der zu exportierenden Attribute und Datensätze festgelegt. Ein externer Client kann dann den Export aufrufen und erhält als Antwort die im Filter ausgewählten Attribute.

3.1.3          Datenimport

Dieser Web-Service kann zum Import der Daten für ein Business Entity genutzt werden. Durch einen in Comarch ERP Enterprise erfassten Filter wird die Anzahl der zu importierenden Attribute festgelegt. Ein externer Client kann dann den Import aufrufen und erhält das Ergebnis des Importvorganges und eventuell fehlerhafte Datensätze zurück.

3.1.4          Entfernte Suche

Dieser Web-Service kann zum Suchen von einzelnen Datensätzen eines Business Entitys genutzt werden. Abhängig von einer in Comarch ERP Enterprise hinterlegten OQL-Suche werden Parameter an den Server gesendet, der dann gegebenenfalls die gefundenen Datensätze zurückgeliefert.

3.2               Aufruf eines Web-Service

Der Aufruf der Web-Service findet über eine API statt, die spezifisch für den gewünschten Web-Service erzeugt werden muss. Um diese API erzeugen zu können stellt jeder Web-Service eine Beschreibung seiner Parameter und Rückgabewerte in Form einer WSDL zur Verfügung. Diese WSDL muss dann in die dazu passende API transformiert werden. Dazu stellt Comarch ERP Enterprise ein Werkzeug zur Verfügung. Ein Client benutzt dann diese API um den Web-Service aufzurufen.

Prinzipiell können Web-Services durch einen beliebigen Client, insbesondere durch einen in einer beliebigen Programmiersprache erstellten Client, aufgerufen werden. Explizit unterstützt von Comarch ERP Enterprise werden nur Clients in Java und .NET. Alle anderen Formen von Clients benötigen eventuell zusätzliche Hilfsmittel und werden hier nicht weiter beschrieben. Im Folgenden wird als Beispiel die Client-API von Axis 1 für Java verwendet.

3.3               Client-API

Jeder der Webservices besteht aus zwei Schnittstellen, der Locator-Schnittstelle und der Web-Service-Schnittstelle. Die Locator-Schnittstelle entspricht dabei in einer Factory, die Web-Service-Schnittstelle in einem Proxy.

Die Locator-Schnittstelle wird im Client in Form einer implementierenden Klasse benutzt. Diese Klasse trägt den Namen des Web-Services plus den Zusatz „Locator“. Die wichtigsten Methoden der Locator-Schnittstelle sind drei Get-Methoden, mit denen die Adresse des Web-Services und der Proxy für den Web-Service zugegriffen werden können.

Das Proxy Objekt enthält für die Operationen des Web-Services je eine Methode. Als Parameter enthält jede Methode ein Objekt der des Typs „Request“. Dieses ist spezifisch für den ausgewählten Web-Service, die gewählte Operation und gegebenenfalls die ausgewählte OLTP-Datenbank und den gewählten Filter. Sinngemäß gilt dasselbe für den Rückgabewert vom Typ „Response“. Dieses Objekt vom Typ „Response“ enthält dann die von der Hintergrund-Anwendung erzeugten Daten.

Folgende Tabelle gibt einen Überblick über die Methoden:

Schnittstelle Methode Beschreibung
<service>Locator get<Service>Address() Liefert die Adresse unter der der Web-Service erreichbar ist.
<service>Locator get<service>() Liefert ein <service>Service Objekt (proxy) unter Benutzung der in der WSDL registrierten URL
<service>Locator get<service>(URL) Liefert ein <service>Service Objekt (proxy) unter Benutzung der angegebenen URL
<service>Service <operation>
(<service>Request)		 Liefert ein <service>Response Objekt in Abhängigkeit von den Daten des Request-Objektes.

 

3.4               Fehlerbehandlung bei Web-Service-Aufrufen

Beim Aufruf eines Web-Services benötigt man eine abgestufte Fehlerbehandlung. Ein typischer Aufruf eines Web-Services sieht wie folgt aus:

try {

Response response= service.process(request);

Result result = response.getResult();

if(result != null) {

// application specific interpretation of results.

}

MessageQueue mQueue = response.getMessageQueue();

// interpret or print messages from queue

}

catch (RemoteException ex) {

// technical problem with the service

}

Wird beim Aufruf eines Web-Services eine Exception geworfen hat dies eine technische Ursache. Die möglichen Ursachen umfassen Fehler beim Übertragen der Daten oder Fehler in der Syntax der XML-Daten generell. Sind keine technischen Fehler aufgetreten so erhält man immer ein Response-Objekt. Dieses Response-Objekt enthält im Falle das Fehler im aufgerufenen Web-Service aufgetreten sind kein Result-Objekt. Liefert also „response.getResult()“ den Wert „null“ zurück, so ist der Fehler im aufgerufenen Web-Service aufgetreten. Ist ein Result-Objekt vorhanden so ist eine weitere Interpretation der Ergebnisse notwendig um eventuelle Fehler bei der Bearbeitung der Daten festzustellen. Zum Beispiel liefert ein Import-Service-Aufruf unter Umständen Datensätze zurück, die den Business-Entity-spezifischen Prüfungen nicht genügen. In jedem Falle enthält das Response-Objekt ein MessageQueue-Objekt. Der Aufruf der Methode „response.getMessageQueue()“ liefert also nie den Wert „null“ zurück. Allerdings kann die MessageQueue selbst leer sein, also keine Message-Objekte enthalten. Im Falle dass das Response-Objekt „null“ ist, ist immer mindestens ein Message-Objekt im MessageQueue-Objekt enhalten.

Hinweis:

Die WSDL für die Web-Services „Import“ und „Export“ ist von dem bei der Erzeugung der WSDL angegebenen Filter abhängig. Sie können die daraus generierten Clients somit nicht für einen anderen Filter verwenden. Anderenfalls erhalten Sie u.U. eine Fehlermeldung oder auch ein unerwartetes Verhalten, das nicht auf diesen Umstand hinweist.

3.5               API-Parameter der Web-Services

In diesem Abschnitt werden die Parameter der Web-Services beschrieben, die mittels des API angegeben werden. Weitere Parameter werden nicht durch das API, sondern durch die Anfrage-URI angegeben, die im Abschnitt „Anfrage-URI der Web-Services“ beschrieben ist.

3.5.1          CallApplication

Der Web-Service „CallApplication“ ruft die „run“-Methode einer Hintergrund-Anwendung auf. Dabei können die Parameter der „run“-Methode beim Aufruf des Web-Services durch den Client mitgegeben werden. Auf der Clientseite wird dafür der voll qualifizierte Name der Hintergrund-Anwendung, die aufzurufende Action und ein Array von ParameterListEntry-Objekten übergeben. Die ParameterListEntry-Objekte entsprechen dabei den Parametern der Hintergrund-Anwendungen.

Das Ergebnis der aufgerufenen Hintergrund-Anwendung wird an den CallApplication-Webservice zurückgeliefert. Dies erfolgt ebenfalls als ein Array von ParameterListEntry-Objekten.

 

 

Beachten Sie, dass im CallApplication-Webservice nur die unten aufgeführten Datentypen unterstützt werden. Dies gilt für Aufrufparameter und Ergebniswerte. Hintergrund-Anwendungen, die andere Datentypen verwenden, können über den CallApplication-Webservice nicht sinnvoll aufgerufen werden.

Die Klasse ParameterListEntry

Jeder ParameterListEntry hat einen Namen, einen Typ und einen Wert. Der Wert muss dabei dem Typ entsprechen. Der Typ wird als Konstante aus der Klasse ParameterListEntryType angegeben.

Beim Erzeugen eines ParameterListEntry-Objektes müssen immer Name, Typ und Wert angegeben werden. Es gibt zwei Konstruktoren die alternativ benutzt werden können. Am einfachsten ist die Benutzung des Standard-Konstruktors (ohne Parameter), danach müssen allerdings Name, Typ und Wert mit den entsprechenden „set“-Methoden gesetzt werden.

Die Klasse ParameterListEntryType

Es gibt die folgenden Konstanten für diesen Datentyp:

Konstante Java-Datentyp (Client) XML-Datentyp
STRING String xsd:string
PARAMETER_LIST ParameterListEntry [] ParameterList
BOOLEAN Boolean xsd:boolean
BYTE Byte xsd:byte
SHORT Short xsd:short
INT Int xsd:int
LONG Long xsd:long
BYTE_ARRAY_STRING String xsd:string

 

BYTE_ARRAY_STRING kann für GUID- und Binary-Parameter der Hintergrund-Anwendung verwendet werden. Als Wert wird im Webservice-Client der Hexadezimal-String der GUID bzw. byte[] angegeben.

Im Abschnitt „CallApplication“ finden Sie ein Beispiel zur Benutzung der unterschiedlichen Datentypen.

3.5.2          Import

Für den Import existieren zwei spezielle Parameter-Klassen. Diese werden basierend auf der WSDL generiert. Um einen Importvorgang zu starten muss ein ImportRequest-Objekt erzeugt werden, die Antwort des Imports ist in einem ImportResponse-Objekt enthalten.

3.5.2.1      Filter

Für den Import muss ein auf dem Comarch_ERP-Enterprise-System erfasster Filter verwendet werden. Dieser wird in der Anfrage-URI des Services angegeben.

Die WSDL des Services ist vom verwendeten Filter abhängig. Daher muss der Filter auch beim WSDL-Abruf angegeben werden. Bei jeder Veränderung des Filters muss die WSDL erneut abgerufen werden und ggf. Klassen auf der Client-Seite neu erzeugt werden.

Hinweis: Im Filter dürfen keine Attribute bzw. Beziehungen aktiviert sein, bei denen sich ein Part und eine Beziehung nur in Groß-/Kleinschreibung unterscheiden und das Part und die Beziehung sich im selben Objekt des BIS-Datenmodells befinden. Verwenden Sie bei komplexen Business Entities daher  keinen Filter auf Basis der Filterauswahl „Alle Attribute“.

Beispiel aus dem Import von Artikeln: „warehouse“ ist ein Attribut im Part „storageArea“, „code“ ist ein Attribut in der Beziehung „StorageArea“.

InventoryItems.ItemStorageData.storageArea.warehouse

InventoryItems.ItemStorageData.StorageArea.code

Diese beiden Attribute dürfen nicht gleichzeitig verwendet werden. Bei vielen Web-Services-Client-Bibliotheken würden damit Java-Klassen erzeugt werden, deren Namen sich nur in Groß-/Kleinschreibung unterscheiden.

3.5.2.2      Aufrufstruktur für den Import

Beim Erzeugen eines Request-Objektes müssen sämtliche Parameter des Imports angegeben werden.

Konstruktor ImportRequest(…)

Erzeugt ein ImportRequest-Objekt mit den entsprechenden Parametern.

Parameter Beschreibung
WarningsMode warningsMode Gibt an, wie mit Warnungen, die beim Import auftreten, umgegangen wird.

Mit dem Wert „CONFIRM_NONE“ führen Warnungen zu Importfehlern und werden in die Fehler-Datei geschrieben.

Mit dem Wert „CONFIRM_ALL“ werden alle Warnungen, die bei diesem Importvorgang auftreten, ignoriert.
CorrectionMode correctionMode Gibt an, ob eine Korrektur fehlerhafter Daten in Comarch ERP Enterprise erfolgen soll.

Mit dem Wert „NONE“ geben Sie an, dass keine Korrektur in Comarch ERP Enterprise erfolgen soll. Die fehlerhaften Daten werden im Response-Object zum Client zurück übermittelt.

Mit dem Wert „WORKFLOW“ geben Sie an, dass eine Korrektur in Comarch ERP Enterprise nach der Benachrichtigung durch den Workflow erfolgen kann. Dabei werden die fehlerhaften Daten nicht an den Client übertragen, sondern als Fehler-Datei im Knowledge Store in den Ordner
„kstore://<Arbeitsbereich>/Import/
RemoteErrorFiles“ erzeugt. Als Arbeitsbereich wird der Standard-Arbeitsbereich der Datenbank, in die die Daten importiert wurden, verwendet.

Beachten Sie, dass die Benachrichtigung durch den Workflow unabhängig von diesem Parameter erfolgen kann.
EntityWrapper importData Ein Wrapper-Objekt das die zu importierenden Daten enthält.
Konstruktor EntityWrapper( … )
Parameter Beschreibung
Title[] title Ein Array der zu importierenden Datensätze.
Message[] _message Wird nicht genutzt. Es wird empfohlen „null“ zu übergeben.

3.5.2.3      Rückgabestruktur für den Import

Nach dem erfolgreichen Aufruf des Imports erhält man ein ImportResponse-Objekt zurück an dem die entsprechenden Werte mittels „get“-Methoden abgefragt werden können.

Klasse ImportResponse
Methode Beschreibung
ImportResult getResult() Liefert das Result-Objekt, kann „null“ sein.
MessageQueue getMessageQueue() Liefert die MessageQueue.
Klasse ImportResult
Methode Beschreibung
int getImportedObjectCount() Liefert die Anzahl der erfolgreich importierten Datensätze.
int getInvalidObjectCount() Liefert die Anzahl der korrigierbaren, nicht importierten Datensätze.
int getNotCorrigibleObjectCount() Liefert die Anzahl der nicht korrigierbaren, nicht importierten Datensätze.
boolean isHasErrorFile() Wenn diese Methode „true“ liefert, werden Fehlerdatensätze zurückgeliefert.
EntityWrapper getErrorData() Liefert das EntityWrapper-Objekt.
Klasse EntityWrapper
Methode Beschreibung
Title[] getTitle() Liefert die fehlerhaften, nicht importierbaren Datensätze zurück. Sind keine fehlerhaften Datensätze vorhanden liefert die Methode den Wert „null“.
MessageQueue getMessageQueue() Liefert die MessageQueue zurück, in der sich gegebenenfalls Meldungen befinden.

3.5.3          Export

Für den Export existieren zwei spezielle Parameter-Klassen. Diese werden basierend auf der WSDL generiert. Um einen Export zu starten muss ein Request-Objekt erzeugt werden, die Antwort des Exports enthält ein Response-Objekt.

3.5.3.1      Filter

Für den Export muss ein auf dem Comarch-ERP-Enterprise-System erfasster Filter verwendet werden. Dieser wird in der Anfrage-URI des Services angegeben.

Die Hinweise für Filter im Abschnitt für den Import gelten auch für den Export. .

3.5.3.2      Aufrufstruktur für den Export

Beim Erzeugen eines ExportRequest-Objektes müssen sämtliche Parameter des Exports angegeben werden.

Konstruktor ExportRequest(…)

Erzeugt ein ExportRequest-Objekt mit den entsprechenden Parametern.

Parameter Beschreibung
String dynamicOQLSearch OQL-Anweisung zur Eingrenzung der zu exportierenden Datensätze. Nähere Informationen zur Struktur der OQL-Anwendung finden Sie in der Dokumentation „Daten exportieren“. Wenn sie keine OQL-Anweisung sondern eine OQL-Suche verwenden, geben sie hier einen leeren String an.
String searchName Vollständiger Name einer OQL-Suche.

Wenn Sie keine OQL-Suche, sondern eine OQL-Anweisung verwenden, geben Sie hier einen leeren String an.
ParameterListEntry[] searchParameters Suchparameter für die Eingrenzung mit einer OQL-Suche. Der Wert ist ein Array von Einträgen, die jeweils einen Suchparameter enthalten. Parametername ist jeweils der Name des Suchfeldes aus der OQL-Suche, Parameterwert ist jeweils der Selection-String. Geben Sie diejenigen Suchparameter an, die Sie für die Eingrenzung verwenden möchten.

Für eine Eingrenzung mit einer OQL-Anweisung wird dieser Parameter nicht verwendet.
String searchSortOrder Sortierung der exportierten Instanzen für die Eingrenzung mit OQL-Suche. Optional. Vorgabewert ist die in der OQL-Suche eingetragene Standardsortierung.

Die Syntax der Sortierung ist im Dokument „Datenaustausch-Programmierschnittstellen“, Abschnitt „Format für die Sortierung“ beschrieben.

Für eine Eingrenzung mit einer OQL-Anweisung wird dieser Parameter nicht verwendet.

3.5.3.3      Rückgabestruktur für den Export

Nach dem erfolgreichen Aufruf des Exports erhält man ein ExportResponse-Objekt zurück, an dem die entsprechenden Werte mithilfe „get“-Methoden abgefragt werden können.

Klasse ExportResponse
Methode Beschreibung
int getExportedObjectCount() Liefert die Anzahl der exportierten Datensätze.
Title[] getExportData() Liefert ein Array aller exportierten Datensätze.
MessageQueue getMessageQueue() Liefert die MessageQueue, in der sich gegebenenfalls Meldungen befinden.

Der Web-Service „Search“ besitzt die beiden Operationen „Suchen“ und „Existenz überprüfen“. Während beim Suchen eine Reihe von Datensätzen in der Ergebnismenge zu finden sein können, wird die Operation „Existenz überprüfen“ höchstens den zu überprüfenden Datensatz enthalten. Sollten den bei der „Existenz überprüfen“ Operation angegebenen Parametern mehrere Datensätze in der Datenbank entsprechen, so wird dennoch nur ein Datensatz zurückgegeben.

Für den Web-Service „Search“ existieren drei spezielle Parameter-Klassen. Diese werden basierend auf der WSDL generiert. Um eine Suche zu starten muss ein SearchRequest-Objekt oder ein SearchExist-Objekt erzeugt werden, die Antwort des Web-Service ist in einem SearchResponse-Objekt enthalten.

3.5.4.1      Aufrufstrukturen für die Suche

Beim Erzeugen eines SearchRequest-Objektes oder eines SearchExistRequest-Objektes müssen sämtliche Parameter der Suche angegeben werden.

Klasse SearchRequest(…)

Erzeugt ein SearchRequest-Objekt mit den entsprechenden Parametern.

Parameter Beschreibung
String searchName Der vollqualifizierende Name der OQL-Suche, die auf der angegebenen Datenbank ausgeführt werden soll.
ParameterListEntry[] searchParameters Die Parameter-Werte für die angegebene OQL-Suche (Optional).
String searchSortOrder Sortierung der exportierten Instanzen für die Eingrenzung mit OQL-Suche. Optional. Vorgabewert ist die in der OQL-Suche eingetragene Standardsortierung.

Die Syntax der Sortierung ist im Dokument „Datenaustausch-Programmierschnittstellen“, Abschnitt „Format für die Sortierung“ beschrieben.
String database Datenbank-Alias. Verwenden sie die Werte aus der generierten Klasse „Database“.
pageSize Bestimmt die maximale Anzahl der Datensätze die zum Client übertragen werden soll.
SearchFormat searchParametersFormat Gibt an, in welchem Format Suchparameter angegeben sind. Verwenden sie die Werte aus der generierten Klasse „SearchFormat“.
SearchFormat searchResultFormat Gibt an, in welchem Format Attribute in den Suchergebnissen zurückgegeben werden. Verwenden sie die Werte aus der generierten Klasse „SearchFormat“.

 
Klasse SearchExistRequest(…)
Parameter Beschreibung
String searchName Der vollqualifizierende Name der OQL-Suche, die auf der angegebenen Datenbank ausgeführt werden soll.
ParameterListEntry[] searchParameters Die Parameter-Werte für die angegebene OQL-Suche (Optional).
String database Datenbank-Alias. Verwenden sie die Werte aus der generierten Klasse „Database“.
SearchFormat searchParametersFormat Gibt an, in welchem Format Suchparameter angegeben sind. Verwenden sie die Werte aus der generierten Klasse „SearchFormat“.

3.5.4.2      Rückgabestruktur für die Suche

Nach dem erfolgreichen Aufruf der Suche erhält man ein SearchResponse-Objekt zurück, an dem die entsprechenden Werte mithilfe „get“-Methoden abgefragt werden können.

Klasse SearchResponse
Methode Beschreibung
SearchResult getResult() Liefert ein SearchResult-Objekt, das gegebenenfalls die Suchergebnisse enthält. Kann „null“ sein.
MessageQueue getMessageQueue() Liefert die MessageQueue, die gegebenenfalls Meldungen enthält.
Klasse SearchResult
Methode Beschreibung
int getCurrentObjectCount() Liefert die Anzahl der zurückgelieferten Datensätze.
String getContent() Liefert die Datensätze in Form Strings, welcher eine UTF8-kodierte XML-Datei enthält.

3.6               Meldungen in der Rückgabe

Der Web-Services-Client bekommt vom Web-Services-Server nicht nur die Ergebnisse des Aufrufes, sondern gegebenenfalls auch eine Menge von Meldungen, z. B. für Fehlerzustände. Diese erhält der Client in Form einer speziellen Datenstruktur bestehend aus den Klassen „MessageQueue“ und „Message“.

Alle Message-Objekte die der Server an den Client zurückschickt, sind in einem MessageQueue-Objekt zusammengefasst. Jedes Message-Objekt enthält wiederum ein MessageSeverity-Objekt, das den Typ der Meldung (Fehler, Warnung, Information etc.) beschreibt.

Klasse Methode Beschreibung
MessageQueue isRequiresAttention() „true“, falls die MessageQueue Fehlermeldungen oder unbestätigte Warnungen enthält.
getMessage() Liefert ein Array von Message-Objekten.
Message getSeverityLevel() Liefert ein MessageServerity-Objekt, das den Meldungstyp beschreibt.
getIdentifier() Liefert die Identifikation der Meldung als Kombination von Meldungsklasse und Meldungsnummer.
getMessageClass() Liefert die Meldungsklasse der Meldung.
getMessageNumber() Liefert die Meldungsnummer der Meldung.
getMessageText() Liefert den Meldungstext.
getMessageLongText() Liefert den Meldungslangtext.
MessageSeverity getValue() Liefert eine textuelle Repräsentation des Meltungstyps.

3.7               Authentifizierung

Sowohl der Web-Services-Client muss sich gegenüber dem Web-Services-Server authentifizieren als auch der Web-Services-Server gegenüber dem Web-Services-Client.

Axis unterstützt nur „BASIC“-Authentifizierung und Authentifizierung mittels Zertifikaten. Comarch ERP Enterprise unterstützt nur „DIGEST“-Authentifizierung und Authentifizierung mittels Zertifikaten. Aus diesem Grund kann ein Web-Service-Client nur mittels Authentifizierung über Zertifikate mit einem Comarch-ERP-Enterprise-Web-Services-Server kommunizieren.

Der Web-Services-Client benötigt ein Server-Zertifikat zur Verifizierung des Web-Services-Servers und ein Benutzer-Zertifikat zu seiner eigenen Identifikation. Das Benutzerzertifikat muss den privaten Schlüssel beinhaltet und wird daher meist in Form einer „.pfx“- oder „.jks“-Datei gespeichert, die über ein Kennwort geschützt ist[1].

Beispiele für die Programmierung eines Web-Services-Clients finden Sie im Abschnitt „Programmierung eines Web-Services-Clients“.

3.8               XML-Namensräume

Basis für die Erstellung eines Web-Services-Clients ist die WSDL des angesprochenen Web-Services. Diese WSDL definiert einen oder mehrere XML-Namensräume. Mindestens wird der XML-Namensraum für den Web-Service-Aufruf selbst inklusive der Standard-Parameter definiert. Werden noch zusätzliche Daten benötigt, z.B. bei dem entfernten Export-Service, so wird noch der Namensraum der Datentypen dieser zusätzlichen Daten und der XML-Namensraum der Daten selbst definiert.

Diese XML-Namensräume spiegeln sich auch in den aus der WSDL erzeugten Java-Klassen wieder. Im Allgemeinen werden die XML-Namensräume der WSDL zu Namensräumen der Java-Klassen führen, die so nicht erwünscht sind. Es besteht deshalb die Möglichkeit diese Namensräume bei der Erzeugung der Java-Klassen auf beliebige Java-Namensräume abzubilden. Die genauen Parameter dieser Abbildung sind im Abschnitt „Erzeugen von Java-Source-Dateien aus WSDL“ zu finden.

Im Einzelnen enthalten die XML-Namensräume folgende Klassen:

  • XML-Namensraum „common“

Die im XML-Namensraum „common“ liegenden Klassen werden vom „CallApplication“-Web-Service benutzt oder werden von allen Web-Services gemeinsam genutzt. Die zu diesem XML-Namensraum erzeugten Klassen sind:

CallApplication

CallApplicationLocator

CallApplicationRequest

CallApplicationResponse

CallApplicationService

CallApplicationSoapBindingStub

Message

MessageQueue

MessageSeverity

ParameterListEntry

ParameterListEntryType

 

  • XML-Namenräume „Export/<Datenbank>/<Filter>“, „Import/<Datenbank>/<Filter>“, „Search“

Alle Beschreibungen der Klassen für die die Nutzung der „Export“-, „Import“- und „Search“-Web-Services benötigt werden, finden sich in jeweils einem eigenen XML-Namensraum.

  • XML-Namensräume „Export/<Datenbank>/<Filter>/data“ und „Import/<Datenbank>/<Filter>/data“.

Alle Beschreibungen der Klassen für die Nutzdaten des „Export“ bzw. „Import„-Web-Services finden sich jeweils in einem eigenen XML-Namensraum. Welche Klassen erzeugt werden hängt unter anderem vom gewählten Business Entity, der OLTP-Datenbank und den Einstellungen des Filters ab.

4                     Vorgehensweisen

In diesem Abschnitt ist die Erstellung eines Web-Services-Clients in Java mit der Client-Bibliothek Axis 1 beschrieben. Verwendet wird der Export-Service.

4.1               Erzeugen der WSDL

Für jeden der Web-Services kann die zugehörige WSDL abgefragt werden. Dazu muss lediglich in einem Browser eine URI folgender Form eingegeben werden:

https://<server>:<port>/webservices/<service>?wsdl;oltp=<oltp>;filter=<filter>;oltpMode=<oltpMode>

Dabei sind folgende Parameter einzusetzen:

Parameter Beschreibung
server Die Adresse des ERP-System-Application-Servers der werden soll.
port Der Port des Web-Services der angesprochen werden soll. Vorschlagswert ist 443.
service Die Identifikation des Web-Services der angesprochen werden soll. Die möglichen Werte sind:

·         „CallApplication“

·         „Import“

·         „Export“

·         „Search“.
oltp Die Identifikation der OLTP-Datenbank, auf der sich der Client (Browser) anmelden soll, um die WSDL abzufragen.
filter Die Identifikation des Filters, der benutzt werden soll um die WSDL zu bestimmen.
oltpMode Der OLTP-Modus. Dieser bedingt ob der Name der OLTP-Datenbank in dem Namensraum des Web-Services mit aufgenommen werden soll oder nicht. Die möglichen Werte sind:

·         „oltp“
Mit der Angabe „oltp“ enthält der XML-Namensraum die OLTP-Datenbank, und die erzeugte WSDL kann nur auf dem aktuellen System und der angegebenen OLTP-Datenbank verwendet werden.

·         „extended“
Mit der Angabe „extended“ kann die WSDL auf beliebigen Systemen bzw. OLTP-Datenbanken verwendet werden. Sie müssen dann jedoch sicherstellen, dass der verwendete Filter auf den jeweiligen OLTP-Datenbanken existiert und gleiche Einstellungen besitzt.

Vorschlagswert: „oltp“.

Beispiel:

https://rXYZ.semiramis.com/webservices/Export?wsdl;oltp= OLTPDB00;filter=TITLE

4.2               Erzeugen der Java-Klassen

Im nächsten Schritt muss diese WSDL in Java-Klassen übersetzt werden. Dieses kann mit Werkzeugen aus dem AXIS Paket getan werden, einfacher ist dies jedoch mit dem Befehl „CreateWSDLJavaSources“.

Dieser Befehl übersetzt nicht nur die WSDL in Java-Klassen, sondern kann die WSDL automatisch vom Web-Services-Server abfragen. Die genaue Beschreibung aller Parameter ist im Abschnitt „Erzeugen von Java-Source-Dateien aus WSDL“ zu finden.

Beispiel:

CreateWSDLJavaSources

-server:rXYZ.semiramis.com

-service:Export

-oltp:DATABASE00

-filter:TITLE

-userCertificateFileName:C:\temp\XYZ.jks

-userCertificateFilePassword:1234567

-serverCertificateFileName:C:\temp\XYZ.jks

-outputDirectory:C:\semiramis\work\job0xxxx\usrXYZ\source

-outputNameSpace:http://webservices.semiramis.com/2006-01/Export/extended/TITLE

=com.cisag.app.system.webservices.log.export.generated

-outputNameSpace:http://cisag.com/pgm/external/webservices/2006-01

-outputNameSpace:http://webservices.semiramis.com/2006-01/common

=com.cisag.app.system.webservices.log.export.generated

-outputNameSpace:http://webservices.semiramis.com/2006-01/Export/extended/TITLE/data

=com.cisag.app.system.webservices.log.export.generated

Die entstandenen Java-Klassen müssen nun übersetzt werden.

4.3               Programmierung eines Web-Services-Clients

Ein Java-Client kann die erzeugten Klassen benutzen um den gewünschten Web-Service aufzurufen. Dabei sind folgende Schritte durchzuführen:

  1. Setzen des Pfades der Zertifikats-Datei, die das Benutzerzertifikat enthält, und des Kennworts zum Öffnen dieser Zertifikats-Datei.
  2. Setzen des Pfades der Zertifikats-Datei, die das Serverzertifikat enthält. Dieses kann über das Setzen der entsprechenden Properties erfolgen. Beispiel:

System.setProperty(“javax.net.ssl.keyStore”, userCertificate);

System.setProperty(“javax.net.ssl.keyStorePassword”,password);

System.setProperty(“javax.net.ssl.trustStore”, serverCertificate);

 

  1. Erzeugen des Locator-Objektes und Abfragen des service-Objektes:

ExportLocator loc= new ExportLocator();

URL url= new URL(“https://<server>:<port>/webservices/<service>? oltp=<oltp>;filter=<filter>“);

service = loc.getExport( url );

 

  1. Erzeugen eines Request-Objektes und setzen der Request-Parameter:

ExportRequest request= new ExportRequest();

request.setSearchName(“com.cisag.app.general.obj.Title”);

// weitere Parameter setzen …

 

  1. Aufruf des Web-Services:

ExportResponse response= service.export(request);

 

  1. Auswerten der Rückgabedaten:

ExportResult result = response.getResult();

if (result != null) {

Title[] instances = result.getExportData();

}

4.4               Benötigte Bibliotheken

Um den Java-Client zu starten werden die folgenden Bibliotheken benötigt:

Bibliothek Version (mindestens)
axis.jar 1.3
saaj.jar 1.2
jaxrpc.jar 1.1
commons-logging.jar 1.0.4
commons-discovery.jar 0.2-dev
wsdl4j.jar 1.5.1
log4j.jar
(in Comarch ERP Enterprise: log4j-core.jar)		 1.2.8
activation.jar 1.0.2
mail.jar 1.3

Die Bibliotheken können Sie entweder direkt aus dem Ordner „semiramis/lib“ kopieren oder von der Website des Apache-Projektes beziehen.

4.5               Anfrage-URI der Web-Services

Um die Web-Services aufzurufen muss eine eigene, für den jeweiligen Web-Service spezifische, URI aufgerufen werden.

  • CallApplication
    https://<server>:<port>/webservices/CallApplication?oltp=<oltp>
  • Export
    https://<server>:<port>/webservices/Export?oltp=<oltp>;filter=<filter>;oltpMode=<mode>
  • Import
    https://<server>:<port>/webservices/Import?oltp=<oltp>;filter=<filter>;oltpMode=<mode>
  • Search
    https://<server>:<port>/webservices/Search?oltp=<oltp>
Parameter Beschreibung
server Adresse des ERP-System-Application-Servers.
port Port des ERP-System-Application-Servers.
oltp Die Identifikation der OLTP-Datenbank auf der sich der Web-Service zum Beantworten der Anfrage anmelden soll.
filter Die Identifikation des auf der angegebenen OLTP-Datenbank vorhandene Filters, der die Attribute des Business Entitys und weitere Einstellungen wie beispielsweise das Zeitformat bestimmt.

Dieser Parameter ist nur für die Web-Services „Import“ und „Export“ erforderlich.
oltpMode Der OLTP-Modus. Dieser bedingt ob der Name der OLTP-Datenbank in dem Namensraum des Web-Services mit aufgenommen werden soll oder nicht. Die möglichen Werte sind:

·         „oltp“
Mit der Angabe „oltp“ enthält der XML-Namensraum die OLTP-Datenbank, und die erzeugte WSDL kann nur auf dem aktuellen System und der angegebenen OLTP-Datenbank verwendet werden.

·         „extended“
Mit der Angabe „extended“ kann die WSDL auf beliebigen Systemen bzw. OLTP-Datenbanken verwendet werden. Sie müssen dann jedoch sicherstellen, dass der verwendete Filter auf den jeweiligen OLTP-Datenbanken existiert und gleiche Einstellungen besitzt.

Vorschlagswert: „oltp“.

Dieser Parameter ist nur für die Web-Services „Import“ und „Export“ erforderlich.

5                     Test-Clients

Mit Comarch ERP Enterprise ausgeliefert werden fünf Test-Clients, die als Vorlagen für eigene Entwicklungen dienen sollen. Sie befinden sich in Form von Java-Klasse im Namensraum „com.cisag.app.system.webservices“ und können von der Toolshell aus direkt mit den nachfolgend beschriebenen Befehlen aufgerufen werden.

Hinweis:

Die Web-Services „Import“ und „Export“ benötigen einen Filter auf der Datenbank auf der ein Import- oder Exportvorgang stattfinden soll. Für die ausgelieferten Test-Clients ist dies ein Filter Namens „TITLE“ auf dem Business Entity „Titel“ („com.cisag.app.general.obj.Title“) auf einer der OLTP-Datenbanken. Dieser Filter wird nicht mit ausgeliefert, sondern muss vom Benutzer des Exports oder Imports angelegt werden. Die Test-Clients funktionieren nur dann, wenn die Attribute „name“ und „description“ ausgewählt sind und nur diese Attribute. Der Filter muss darüber hinaus die Spracheinstellung „Einsprachig“ haben.

Beachten Sie bei allen Test-Clients, dass mehrfache Aufrufe des Test-Clients im selben Prozess zu Verbindungsproblemen führen können, wenn dabei unterschiedliche Server-Zertifikate verwendet werden. Wenn Sie die Test-Clients von der Toolshell aus starten und Verbindungsfehler erhalten, prüfen Sie ob ein Neustart des Application Servers das Problem behebt.

 

5.1               Erzeugen von Java-Source-Dateien aus WSDL

Die folgenden Parameter stehen bei dem Beispiel-Client „CreateWSDLJavaSources“ zur Verfügung:

Parameter Erläuterung
userCertificateFileName Der vollständige Dateiname zur Zertifikats-Datei die das Benutzer-Zertifikat enthält.
userCertificateFilePassword Das Kennwort zum Öffnen der Zertifikats-Datei, die das Benutzerzertifikat enthält.
serverCertificateFileName Der vollständige Dateiname des Zertifikats-Datei die das Server-Zertifikat enthält
uri Die URI der zu übersetzenden WSDL. Dieser Parameter kann verwendet werden, um die WSDL von einer beliebigen Internet-Adresse („https://…“) oder auf dem Dateisystem („file:///…“) zu öffnen. Der Parameter kann nicht zusammen mit den Parametern „server“, „port“, „service“, „oltp“ und „filter“ verwendet werden.
server Die Adresse des Web-Services-Servers. Dieser Parameter kann nicht zusammen mit dem Parameter „uri“ verwendet werden.
port Der Port des Web-Services-Servers. Dieser Parameter kann nicht zusammen mit dem Parameter „uri“ verwendet werden.
service Der angesprochene Web-Service des Web-Services-Servers. Dieser Parameter kann nicht zusammen mit dem Parameter „uri“ verwendet werden.
oltp Die Identifikation der OLTP-Datenbank des Web-Services-Servers an der sich der Web-Service anmelden soll. Dieser Parameter kann nicht zusammen mit dem Parameter „uri“ verwendet werden.
filter Die Identifikation des Filters des Web-Services-Servers der zur Auswahl der Attribute des Business Entitys angewendet werden soll. Hier muss der gleiche Filter angegeben werden der auch bei der Erzeugung der WSDL angegeben wurde. Für die ausgelieferten Test-Clients ist dies ein Filter mit dem Namen „TITLE“. Dieser Parameter kann nicht zusammen mit dem Parameter „uri“ verwendet werden.
outputNameSpace Der Name des Namensraums in dem die erzeugten Java-Klassen liegen sollen. Pro XML-Namensraum in der WSDL kann jeweils ein Java-Namensraum angegeben werden. Die Angabe erfolgt in der Form
„http://cisag…=com.example.app….“
outputDirectory Der Order im lokalen Dateisystem in den die erzeugten Java-Source-Dateien geschrieben werden.
oltpMode Das Format der Namensräume in der abzurufenden WSDL. Mögliche Werte: „extended“ oder „oltp“. Optional, Vorschlagswert ist oltp.
help Gibt eine kurze Beschreibung aller Parameter aus. Optional.
verbose Gibt Informationen während des Erzeugens der Java-Source-Dateien aus. Optional.
debug Gibt Debug-Informationen während des Erzeugens der Java-Source-Dateien aus. Optional.

 

Beispiel:

CreateWSDLJavaSources -server:rXYZ.cisag.com -service:CallApplication -userCertificateFileName:C:\temp\XYZ.jks -userCertificateFilePassword:1234567 -serverCertificateFileName:C:\temp\XYZ.jks -outputDirectory: C:\semiramis\work\jobxxxxx\usrXYZ\source -outputNameSpace:http://webservices.semiramis.com/2006-01/common=com.cisag.app.system.webservices.log.generated

 

Der Test-Client umfasst die folgenden Java-Klassen:

  • Namensraum com.cisag.app.system.webservices.log
  • CreateWSDLJavaSources
  • WebServicesClientBase
  • WebServicesClientDebugHelper
  • Namensraum com.cisag.app.system.webservices.tools
  • CreateWSDLJavaSources
  • Namensraum com.cisag.pgm.external.webservices
  • Message
  • MessageQueue
  • MessageSeverity
  • ParameterListEntry
  • ParameterListEntryType

5.2               CallApplication

Die folgenden Parameter stehen bei dem Beispiel-Client „WebServicesTestClient“ zur Verfügung:

Parameter Erläuterung
userCertificateFileName Der vollständige Dateiname zur Zertifikats-Datei die das Benutzer-Zertifikat enthält.
userCertificateFilePassword Das Kennwort zum Öffnen der Zertifikats-Datei, die das Benutzerzertifikat enthält.
serverCertificateFileName Der vollständige Dateiname des Zertifikats-Datei die das Server-Zertifikat enthält
server Die Adresse des Web-Services-Servers.
port Der Port des Web-Services-Servers.
oltp Die Identifikation der OLTP-Datenbank des Web-Services-Servers an der sich der Web-Service anmelden soll
help Gibt eine kurze Beschreibung aller Parameter aus.

 

Beispiel:

WebServicesTestClient
-server:rXYZ.semiramis.com
-oltp:OLTPDB00

-userCertificateFileName:C:\temp\XYZ.jks

-userCertificateFilePassword:1234567

-serverCertificateFileName:C:\temp\XYZ.jks

Der Test-Client umfasst die folgenden Java-Klassen:

  • Namensraum com.cisag.app.system.webservices.log
  • WebServicesTestClient
  • WebServicesClientBase
  • Namensraum com.cisag.app.system.webservices.tools
  • WebServicesTestClient
  • Namensraum com.cisag.pgm.external.webservices
  • CallApplication
  • CallApplicationLocator
  • CallApplicationRequest
  • CallApplicationResponse
  • CallApplicationService
  • CallApplicationService
  • Message
  • MessageQueue
  • MessageSeverity
  • ParameterListEntry
  • ParameterListEntryType

5.3               Export

Die folgenden Parameter stehen bei dem Beispiel-Client „WebServicesRemoteExportTestClient“ zur Verfügung:

Parameter Erläuterung
userCertificateFileName Der vollständige Dateiname zur Zertifikats-Datei die das Benutzer-Zertifikat enthält.
userCertificateFilePassword Das Kennwort zum Öffnen der Zertifikats-Datei, die das Benutzerzertifikat enthält.
serverCertificateFileName Der vollständige Dateiname des Zertifikats-Datei die das Server-Zertifikat enthält
server Die Adresse des Web-Services-Servers.
port Der Port des Web-Services-Servers.
oltp Die Identifikation der OLTP-Datenbank des Web-Services-Servers an der sich der Web-Service anmelden soll
filter Die Identifikation des Filters des Web-Services-Servers der zur Auswahl der Attribute des Business Entitys angewendet werden soll. Hier muss der gleiche Filter angegeben werden der auch bei der Erzeugung der WSDL angegeben wurde. Für die ausgelieferten Test-Clients ist dies ein Filter mit dem Namen „TITLE“.
select Ein Suchmuster für die Eingrenzung der zu exportierenden Datensätze. . Der angegebene Wert wird mit dem Namen der Datensätze verglichen Vorschlagswert ist „*“, also alle Objekte werden ausgewählt.
help Gibt eine kurze Beschreibung aller Parameter aus.

 

Beispiel:

WebServicesRemoteExportTestClient -server:rXYZ.cisag.com -oltp:DATABASE00 -filter:TITLE -userCertificateFileName:C:\temp\XYZ.jks      -userCertificateFilePassword:1234567      -serverCertificateFileName:C:\temp\XYZ.jks

Der Test-Client umfasst die folgenden Java-Klassen:

  • Namensraum com.cisag.app.system.webservices.log
  • WebServicesClientBase
  • WebServicesClientDebugHelper
  • WebServicesRemoteExportTestClient
  • Namensraum com.cisag.app.system.webservice.log..generated.exp
  • Export
  • ExportLocator
  • ExportService
  • ExportSoapBindingStub
  • ExportRequest
  • ExportResponse
  • java
  • Title
  • Namensraum com.cisag.app.system.webservices.tools
  • ExportService
  • Namensraum com.cisag.app.system.webservices.log.generated
  • Message
  • MessageQueue
  • MessageSeverity
  • ParameterListEntry
  • ParameterListEntryType

5.4               Import

Die folgenden Parameter stehen bei dem Beispiel-Client „WebServicesRemoteImportTestClient“ zur Verfügung:

Parameter Erläuterung
userCertificateFileName Der vollständige Dateiname zur Zertifikats-Datei die das Benutzer-Zertifikat enthält.
userCertificateFilePassword Das Kennwort zum Öffnen der Zertifikats-Datei, die das Benutzerzertifikat enthält.
serverCertificateFileName Der vollständige Dateiname des Zertifikats-Datei die das Server-Zertifikat enthält
server Die Adresse des Web-Services-Servers.
port Der Port des Web-Services-Servers.
oltp Die Identifikation der OLTP-Datenbank des Web-Services-Servers an der sich der Web-Service anmelden soll.
filter Die Identifikation des Filters des Web-Services-Servers der zur Auswahl der Attribute des Business Entitys angewendet werden soll. Hier muss der gleiche Filter angegeben werden der auch bei der Erzeugung der WSDL angegeben wurde. Für die ausgelieferten Test-Clients ist dies ein Filter mit dem Namen „TITLE“.
help Gibt eine kurze Beschreibung aller Parameter aus.

 

Beispiel:

WebServicesRemoteImportTestClient -server:rXYZ.cisag.com -oltp:DATABSE00 -filter:TITLE -userCertificateFileName:C:\temp\XYZ.jks      -userCertificateFilePassword:1234567      -serverCertificateFileName:C:\temp\XYZ.jks

Der Test-Client umfasst die folgenden Java-Klassen:

  • Namensraum com.cisag.app.system.webservices.log
  • WebServicesClientBase
  • WebServicesClientDebugHelper
  • WebServicesRemoteImportTestClient
  • Namensraum com.cisag.app.system.webservice.log..generated.imp
  • Import
  • ImportLocator
  • ImportService
  • ImportSoapBindingStub
  • ImportRequest
  • ImportResponse
  • ImportResult
  • EntityWrapper
  • Title
  • Namensraum com.cisag.app.system.webservices.tools
  • ImportService
  • Namensraum com.cisag.app.system.webservices.log.generated
  • Message
  • MessageQueue
  • MessageSeverity
  • ImportMode
  • ImportCorrectionMode
  • ImportWarningsMode

Hinweis:
Wenn Sie selbst Java-Klassen aus der WSDL generieren, werden folgende Klassen abweichend von dieser Liste generiert:

  • java wird ein Unterstrich vorangesetzt. Dies entspricht der WSDL.
  • java und ImportLocator.java werden aufgrund einer Eigenschaft der ausgelieferten Axis-Version 1.3 ebenfalls mit vorangestelltem Unterstrich generiert.

Sie können diese Klassen jedoch bei Bedarf umbenennen.

Hinweis:
Java-Klassen, die Valuesets aus Comarch ERP Enterprise repräsentieren, werden mit der ausgelieferten Axis-Version 1.3 in bestimmten Fällen mit Konstanten der Form „valueX“ anstatt der Valueset-Konstantennamen generiert. In diesem Fall sollten Sie diese Konstanten nicht benutzten, sondern Objekte mittels der static-Methode „fromString“ erzeugen, wobei Sie den Konstantennamen selbst angeben. Dies erhöht die Lesbarkeit des Java-Source-Codes und ist bei zukünftigen Valueset-Erweiterungen portabler. Die verfügbaren Konstanten-Namen ersehen Sie u. a. aus dem Source der generierten Klasse.

5.5               Suchen

Die folgenden Parameter stehen bei dem Beispiel-Client „WebServicesRemoteSearchTestClient“ zur Verfügung:

Parameter Erläuterung
userCertificateFileName Der vollständige Dateiname zur Zertifikats-Datei die das Benutzer-Zertifikat enthält.
userCertificateFilePassword Das Kennwort zum Öffnen der Zertifikats-Datei, die das Benutzerzertifikat enthält.
serverCertificateFileName Der vollständige Dateiname des Zertifikats-Datei die das Server-Zertifikat enthält
server Die Adresse des Web-Services-Servers.
port Der Port des Web-Services-Servers.
oltp Die Identifikation der OLTP-Datenbank des Web-Services-Servers an der sich der Web-Service anmelden soll
searchName Der voll qualifizierte Name einer OQL-Suche.
searchParameter Ein Parameter für die OQL-Suche (optional).

Der Parameter muss das Format <name>=<wert> haben. Der Name ist jeweils der Name des Suchfeldes aus der OQL-Suche, Parameterwert ist jeweils der Selection-String.

Die möglichen Selection-Strings sind vom Datentyp des Suchfeldes abhängig und sind im Dokument „Entfernte BIS-Schnittstellen“, Abschnitt „Datentypen in der Suche“ beschrieben.

 

Beispiel:

WebServicesRemoteSearchTestClient

-server:rXYZ.semiramis.com

-oltp:OLTPDB00

-searchName: com.cisag.app.general.obj.TitleSearch

-userCertificateFileName:C:\temp\XYZ.jks

-userCertificateFilePassword:1234567

-serverCertificateFileName:C:\temp\XYZ.jks

Der Test-Client umfasst die folgenden Java-Klassen:

  • Namensraum com.cisag.app.system.webservices.log
  • WebServicesClientBase
  • WebServicesClientDebugHelper
  • WebServicesRemoteSearchTestClient
  • Namensraum com.cisag.app.system.webservice.log..generated.search
  • Search
  • SearchLocator
  • SearchService
  • SearchSoapBindingStub
  • SearchRequest
  • SearchExistsRequest
  • SearchResponse
  • SearchExistsResponse
  • SearchResult
  • SearchExistsResult
  • SearchFormat
  • Namensraum com.cisag.app.system.webservices.tools
  • SearchService
  • Namensraum com.cisag.app.system.webservices.log.generated
  • Message
  • MessageQueue
  • MessageSeverity
  • ParameterListEntry
  • ParameterListEntryType

5.6               Excel-Client (Microsoft.Net-Client)

Mit Comarch ERP Enterprise wird auch ein Web-Services-Client für Microsoft Excel ausgeliefert. Dieser besteht aus einer Excel-Arbeitsmappe und einer zusätzlichen Bibliothek. In diesem Client können sämtliche Datensätze des Business-Objects „Titel“ („com.cisag.app.general.obj.Title“) exportiert, bearbeitet und wieder importiert werden. Der Excel-Client ist also zugleich ein Export-Client und ein Import-Client.

Der Excel-Client besteht aus zwei Arbeitsblättern, „Anmeldung“ und „Daten“. Im Arbeitsblatt „Anmeldung“ müssen durch den Benutzer alle zur Anmeldung des Exports notwendigen Daten erfasst werden. Im Arbeitsblatt „Daten“ werden die exportierten Daten dargestellt und können vom Benutzer bearbeitet werden.

5.6.1          Voraussetzungen

Um selbst einen Excel-Client entwickeln zu können werden die folgenden Software-Pakete vorausgesetzt:

  • .NET 2.0
  • MS Visual Studio 2005 Professional Edition
  • MS Office 2003 Professional
  • MS Visual Studio 2005 Tools for the Microsoft Office System (Auf den MSDN-DVDs ist dies ein Zusatz zu Visual Studio; ansonsten ist dies eine eigene Edition)

5.6.2          Installation des Clients

Der Excel-Test-Client wird als Dateiauslieferung „com.cisag.sys.delivery.Install-Web-Services-Clients“ in Form einer „.zip“-Datei ausgeliefert und aktualisiert. Entpacken Sie sich die Datei „files/install/webservices/web-services-clients.zip“ mit einem entsprechenden Archivierungsprogramm vom Dateiserver-Ordner des Comarch-ERP-Enterprise-Systems in den Wurzelordner des Laufwerks „C:“. Hierbei entsteht folgende Ordnerstruktur:

C:\

semiramis\

webservices\

ExcelImportExportTestClient\

 

Der Ordner „ExcelImportExportTestClient“ beinhaltet alle notwendigen Dateien für die Entwicklung und das Benutzen des Excel-Clients.

Hinweis
Da die Projekte von Microsoft Visual Studio absolute Dateipfade beinhalten, muss der Excel-Client genau an die beschriebene Stell im Dateisystem extrahiert werden um ohne Anpassungen lauffähig zu sein.

Der Excel-Client verwendet die Kennwort-Authentifizierung. Daher muss zur Verwendung des Excel-Clients nur das Server-Zertifikat oder ein Zertifikat einer übergeordneten Zertifizierungsstelle (.cer-Datei) im Internet Explorer installiert werden.

5.6.3          Client starten

Öffnen Sie im Windows-Explorer den Ordner „C:\semiramis\webservices\ExcelRemoteImportExportClient“. Doppelklicken Sie auf die Datei „ExcelRemoteImportExportClient.sln“. Der Client wird nun in Visual Studio geöffnet. Starten Sie den Client mit dem Menüpunkt „Debug/Run without Debugging“. Damit erscheint der Client in Microsoft Excel. Im Folgenden ist die Bedienung des Clients beschrieben.

5.6.4          Arbeitsblatt „Anmeldung“

Im Arbeitsblatt „Anmeldung“ sind die folgenden Werte zu erfassen

Feld Wert
Server Der Adresse des ERP-System-Application-Servers, auf dem die Web-Services zur Verfügung gestellt werden.
Port Der Port auf dem die Web-Services zur Verfügung gestellt werden (Vorschlagswert 443).
OLTP Der Identifikation der der OLTP-Datenbank von der der Export durchgeführt werden soll.
Filter Die Identifikation eines Filters auf der angegebenen OLTP-Datenbank. Der Filter muss für das Business Entity „com.cisag.app.general.obj.Title“ erfasst worden sein.

Für den ausgelieferten Test-Client muss der Filter den Namen „TITLE“ heißen. Diesen Namen müssen Sie auch in diesem Feld angeben.

Im Filter selbst müssen die Attribute „name“ und „description“ ausgewählt sein, und die Spracheinstellung des Filters muss „Einsprachig“ sein.
Benutzer Die Identifikation des Benutzers, mit dem die Anmeldung erfolgen soll. Der Benutzer muss dem System zugeordnet und für die Anmeldung an die angegebene OLTP-Datenbank berechtigt sein.
Kennwort Das Kennwort für den angegebenen Benutzer.

Außer den Eingabefeldern gibt es im Arbeitsblatt noch zwei Schaltflächen, „Importieren“ und „Exportieren“. Diese Schaltflächen dienen dazu, den Importvorgang bzw. Exportvorgang nach dem vollständigen Erfassen der Anmeldedaten zu starten. Nach dem Drücken der Schaltfläche erfolgt die Kommunikation mit dem Server. Nach dem Abschluss der Kommunikation erscheint ein Dialog-Fenster mit einer Meldung.

5.6.5          Arbeitsblatt „Daten“

Im Arbeitsblatt „Daten“ werden die exportierten Daten dargestellt und können durch den Benutzer geändert werden. Es zwei Schaltflächen, „Hinzufügen“ und „Entfernen“. Mit der Schaltfläche „Hinzufügen“ wird eine neue, leere Zeile am Ende der Tabelle hinzugefügt, in der ein neuer Datensatz erfasst werden kann. Mit der Schaltfläche „Entfernen“ wird der Datensatz entfernt, in dem sich die momentan aktive Zelle des Arbeitsblattes befindet. Bei einem späteren Import wird jedoch der entsprechende Datensatz in der OLTP-Datenbank hierdurch nicht gelöscht. Generell kann durch diesen Test-Client kein Datensatz in der Datenbank gelöscht werden.

6                     Unterstützung zur Fehlersuche

Der Comarch ERP Enterprise Web-Services-Server bietet die Mögichkeit, Informationen über Anfragen von Clients auszugeben. Dies gilt sowohl für die nicht-programmierbaren wie für die programmierbaren Web-Services.

Aktivieren Sie hierzu das Klassendebugging der Javaklasse com.cisag.sys.kernel.webservices.CisWebServicesResource auf dem ERP-System-Application-Server, der von Clients aufgerufen wird. Auf der Toolshell erscheinen abhängig von der Debuggingstufe folgende Ausgaben:

Debuggingstufe Ausgaben
INFO Für jeden Aufruf eines Web-Services erfolgt eine Ausgabe beim Beginn und am Ende der Verarbeitung im SAS.

Ausgegeben werden: Session-Nummer, HTTP Method, Anfrage-URI, Verarbeitungszeit.
FINEST Zusätzlich zu den Ausgaben in der Stufe INFO wird mit der Stufe FINEST der Inhalt (HTTP Body) der Anfrage des Clients und der Antwort des Service ausgegeben.

Die Ausgaben können über den Toolshell-Befehl dbgcls für einen laufenden SAS ein- und ausgeschaltet werden.

7                     Anhang

Hier sind alle Toolshell-Befehle zusammengefasst die zum Erzeugen der Java-Source-Dateien für die Test-Clients bzw. zum Ausführen der Test-Clients notwendig sind.

#

# CallApplication

#

# Abfragen der WSDL:

# https://rXYZ.semiramis.com/webservices/CallApplication?wsdl

 

CreateWSDLJavaSources -server:rXYZ.cisag.com -service:CallApplication -userCertificateFileName:C:\temp\XYZ.jks -userCertificateFilePassword:1234567 -serverCertificateFileName:C:\temp\XYZ.jks -outputDirectory: C:\semiramis\work\jobxxxxx\usrXYZ\source -outputNameSpace:http://webservices.semiramis.com/2006-01/common=com.cisag.app.system.webservices.log.generated

 

 

WebServicesTestClient -server:rXYZ.semiramis.com -oltp:OLTPDB00-userCertificateFileName:C:\temp\XYZ.jks -userCertificateFilePassword:1234567     -serverCertificateFileName:C:\temp\XYZ.jks

 

 

#

# Export

#

# Abfragen der WSDL:

# https://rXYZ.semiramis.com/webservices/Export?wsdl;oltp=OLTPDB00;filter=TITLE

 

CreateWSDLJavaSources -server:rXYZ.cisag.com -service:Export -oltp:OLTPDB00 -filter:TITLE -oltpMode:extended -userCertificateFileName:C:\temp\XYZ.jks -userCertificateFilePassword:1234567 -serverCertificateFileName:C:\temp\XYZ.jks -outputDirectory: C:\semiramis\work\jobxxxxx\usrXYZ\source -outputNameSpace:http://webservices.semiramis.com/2006-01/Export/extended/TITLE=com.cisag.app.system.webservices.log.generated.exp -outputNameSpace:http://webservices.semiramis.com/2006-01/common=com.cisag.app.system.webservices.log.generated -outputNameSpace:http://webservices.semiramis.com/2006-01/Export/extended/TITLE/data=com.cisag.app.system.webservices.log.generated.exp

 

 

WebServicesRemoteExportTestClient -server:rXYZ.semiramis.com -oltp:OLTPDB00 -filter:TITLE -userCertificateFileName:C:\temp\XYZ.jks      -userCertificateFilePassword:1234567      -serverCertificateFileName:C:\temp\XYZ.jks

 

 

#

# Import

#

# Abfragen der WSDL:

# https://rXYZ.semiramis.com/webservices/Import?wsdl;oltp=OLTPDB00;

 

CreateWSDLJavaSources   -server:rXYZ.semiramis.com    -service:Import   -oltp: OLTPDB00 -filter:TITLE -oltpMode:extended -userCertificateFileName:C:\temp\XYZ.jks     -userCertificateFilePassword:1234567      -serverCertificateFileName:C:\temp\XYZ.jks       -outputDirectory:C:\semiramis\work\jobxxxxx\usrXYZ\source -outputNameSpace:http://webservices.semiramis.com/2006-01/common=com.cisag.app.system.webservices.log.generated -outputNameSpace:http://webservices.semiramis.com/2006-01/Import/extended/TITLE=com.cisag.app.system.webservices.log.generated.imp -outputNameSpace:http://webservices.semiramis.com/2006-01/Import/extended/TITLE/data=com.cisag.app.system.webservices.log.generated.imp

 

WebServicesRemoteImportTestClient -server:rXYZ.semiramis.com -oltp:OLTPDB00 -filter:TITLE -userCertificateFileName:C:\temp\XYZ.jks      -userCertificateFilePassword:1234567      -serverCertificateFileName:C:\temp\XYZ.jks

 

 

#

# Search

#

# Abfragen der WSDL:

# https://rXYZ.semiramis.com/webservices/Search?wsdl;oltp=OLTPDB00;

 

CreateWSDLJavaSources   -server:rXYZ.semiramis.com    -service:Search   -oltp:OLTPDB00       -userCertificateFileName:C:\temp\XYZ.jks -userCertificateFilePassword:1234567        -serverCertificateFileName:C:\temp\XYZ.jks     -outputDirectory:C:\semiramis\work\jobxxxxx\usrXYZ\source   -outputNameSpace:http://webservices.semiramis.com/2006-01/common=com.cisag.app.system.webservices.log.generated -outputNameSpace:http://webservices.semiramis.com/2006-01/Search=com.cisag.app.system.webservices.log.generated.search

 

WebServicesRemoteSearchTestClient -server:rXYZ.semiramis.com -oltp:OLTPDB00 -searchName:com.cisag.app.general.obj.TitleSearch     -userCertificateFileName:C:\temp\XYZ.jks -userCertificateFilePassword:1234567     -serverCertificateFileName:C:\temp\XYZ.jks

 

[1] Java 1.5 unterstützt ohne zusätzliche Bibliotheken nur „.jks“-Dateien.

Czy ten artykuł był pomocny?

Wyślij opnie