SOAP-Aktionen der Fabasoft Produktinstallation

Die SOAP-Aktionen der Fabasoft Produktinstallation werden über die Fabasoft Folio Webservices verfügbar gemacht. Für die Nutzung der SOAP-Aktionen muss daher mindestens eine Fabasoft Folio Webservice Installation verfügbar sein.

Hinweis: Detaillierte Informationen zu unterstützten Betriebssystemen und unterstützter Software finden Sie im Readme-Dokument im Verzeichnis Additions/Documents auf Ihrer Fabasoft Produkt-CD.

SOAP ist ein XML-basiertes Protokoll für den Austausch von Informationen in einer dezentralisierten, verteilten Umgebung. SOAP-Nachrichten werden über die Schnittstelle der Fabasoft Produktinstallation mithilfe des Transportprotokolls HTTP übermittelt.

Die vollständige Beschreibung der einzelnen Webservices erfolgt über ein WSDL-Dokument (Web Service Description Language). Darin enthalten sind

1. Typdefinitionen der Parameter und Prototypen der aufrufbaren Methoden
2. Bindung an ein Transportprotokoll (HTTP)
3. Endpunkt des Service (Service-URL)

Technische Aspekte der SOAP-Schnittstelle

Die WSDL-Beschreibung eines Webservice der Fabasoft Produktinstallation wird dynamisch über einen parametrisierten URL erzeugt, auf den ein HTTP-GET-Request ausgeführt wird. Dieser URL beschreibt auch den Endpunkt des Webservice. Über einen HTTP-POST-Request werden SOAP-Nachrichten an das entsprechende Webservice übermittelt.

Die Verwendung der Webservices der Fabasoft Produktinstallation entspricht einem Request-Response-Modell. Um die Webservices anzusprechen, wird die „Document-Style“-Aufrufkonvention des SOAP-Protokolls verwendet. Das Webservice erhält über den SOAP-Request ein XML-Dokument als Input. Der SOAP-Response, der dem Aufruf folgt, enthält wiederum ein XML-Dokument, das die Output-Daten des Webservice enthält.

Falls bei der Ausführung des Webservice ein Fehler auftritt, wird im SOAP-Response ein SOAP-Fehler übermittelt, der die Fehlerbeschreibung des Webservice enthält.

Jeder Aufruf eines Webservice der Fabasoft Produktinstallation entspricht mindestens einer Transaktion, wobei jede Transaktion ein atomarer Schritt ist, der entweder zur Gänze ausgeführt wird oder nicht. Ein Aufruf eines Webservice kann auch mehrere Transaktionen umfassen; soweit nicht gegenteilig dokumentiert, ist ein Aufruf genau eine Transaktion.

Mehrere atomare SOAP-Aktionen können in einer Transaktion zusammengefasst werden. Eine Transaktion kann durch die letzte SOAP-Aktion abgeschlossen oder durch Aufruf der Aktion Verwerfen einer SOAP-Transaktion (FSCOWS@1.1001:SOAPAbort) abgebrochen werden.

Beispiel:

In diesem Beispiel wird eine Transaktionsklammer verwendet. Innerhalb einer Transaktion werden ein Ordner und ein Word-Dokument erzeugt. Das Commit der Transaktion passiert hier vor dem Aufruf der letzten SOAP-Aktion.

FSC.SWC_1_1009_MyWebSvc svc = new FSC.SWC_1_1009_MyWebSvc();
svc.cootx = new FSC.TXContext();
...
res1 = svc.FSCBAI_1_1001_SOAPCreateObject(…); // Ordner erstellen
...

svc.cootx.commit = TRUE;
res2 = svc.FSCBAI_1_1001_SOAPCreateObject(…); //Word erstellen
...

Aufbau des Service-URL

Der URL, der zum Generieren des WSDL-Dokuments und als Service-Endpunkt dient, ist folgendermaßen aufgebaut:

http://<webserver>/<vdir>/fscdav/wsdl?params

params ist wie folgt zusammengesetzt:

params::=param { "&" param }

param::=websvc | operation | mapping

websvc::="websvc=" object

operation::="operation=" operationname

mapping::="mapping=" object

operationname::=<name of the operation to be executed>

object::=objectaddr | reference

objectaddr::=<Fabasoft Folio object address>

reference::=<Fabasoft Folio reference>

Die Bedeutung der einzelnen Parameter ist in der folgenden Auflistung näher beschrieben. Parameter, die in eckiger Klammer ([]) angeführt werden, sind optional.

Webservice-Definition

Der websvc-Parameter eines Webservice-URL verweist auf ein Objekt der Klasse Webservice-Definition (FSCOWS@1.1001:WebServiceDefinition). In diesem Objekt sind eine Liste von SOAP-Aktionen und andere Einstellungen hinterlegt, die das Webservice bilden.

• Kennung (FSCOWS@1.1001:webserviceidentifier)
  Alternative Bezeichnung des Webservices für SOAP-Clients. Falls nicht angegeben, so wird die Referenz der Webservice-Definition verwendet.
• Verwende Transaktion (FSCOWS@1.1001:webserviceusetransaction)
  Erlaubt es dem Client, mehrere SOAP-Aktionen in einer Transaktion zu bündeln.
• Webservice-Aktionen (FSCOWS@1.1001:webserviceactions)
  Aggregatsliste mit den aufrufbaren Aktionen. Ein Eintrag besteht aus folgenden Eigenschaften:
  • Operation (FSCOWS@1.1001:webserviceoperation)
    Alternative Bezeichnung der Aktion. Falls nicht angegeben, so wird die Referenz der Aktion (Eigenschaft FSCOWS@1.1001:webserviceaction) verwendet.
  • Webservice-Aktion (FSCOWS@1.1001:webserviceaction)
    Aktionen der Klassen Aktion (COOSYSTEM@1.1:Action) und SOAP-Aktion (FSCOWS@1.1001:SOAPAction) können angegeben werden.
  • Objekt-Klasse (FSCOWS@1.1001:webserviceobjclass)
    Diese Eigenschaft ist nur bei Aktionen der Klasse SOAP-Aktion (FSCOWS@1.1001:SOAPAction) relevant. Eine SOAP-Aktion kann mit einer Objektklasse qualifiziert werden, wodurch unterschiedliche XML-Zuordnungen für dieselbe SOAP-Aktion definiert werden können.
  • XML-Zuordnung (FSCOWS@1.1001:webservicemapping)
    In dieser Eigenschaft wird die anzuwendende XML-Zuordnung angegeben. XML-Zuordnungen werden nur für SOAP-Aktionen (Objektklasse FSCOWS@1.1001:SOAPAction) berücksichtigt. Mithilfe von XML-Zuordnungen werden die benötigten Parameter aus dem eingehenden XML-Datenstrom extrahiert bzw. es wird der ausgehende XML-Datenstrom generiert. Siehe auch zuvor beschriebene Eigenschaft Objekt-Klasse.

XML-Zuordnungen können an mehreren Stellen definiert werden. Die Priorisierung erfolgt gemäß folgender Liste:

1. Höchste Priorität hat der mapping-Parameter des Webservice-URL. So besteht die Möglichkeit, beim Aufruf einer SOAP-Aktion die XML-Zuordnung vorzugeben.
2. XML-Zuordnung in der Webservice-Definition.
3. XML-Zuordnung, die durch einen Pre-Wrapper der Aktion Ermittle das tatsächliche Mapping einer SOAP-Aktion (FSCOWS@1.1001:GetMapping) geliefert wird.
4. Die XML-Zuordnung der SOAP-Aktion (Eigenschaft XML-Zuordnung (COOXML@1.1:xmlactmapping)) hat die niedrigste Priorität.

Es besteht auch die Möglichkeit Aktionen (Objektklasse COOSYSTEM@1.1:Action) in die Webservice-Definition einzuhängen. In diesem Fall erfolgt eine automatische Zuordnung der Aktionsparameter zu SOAP-Nachrichten.

Weiters enthält ein Webservice-Definitionsobjekt Informationen für die Registrierung des Webservice in einem UDDI-Verzeichnis (Universal Description Discovery and Integration). Die Registrierung bzw. Deregistrierung erfolgt über die Menübefehle „Registriere in UDDI-Datenbank“ bzw. „Entferne Registrierung von UDDI-Datenbank“.

Beispiel:

Folgende Beispiele beschreiben verschiedene Möglichkeiten, ein konkretes Webservice (hier das Service SWC@1.1001:WebService mit der Objektadresse COO.1.1001.1.2049569) aufzurufen:

http://<webserver>/<vdir>/fscdav/wsdl?websvc=COO.1.1001.1.2049569
&style=doc
http://<webserver>/<vdir>/fscdav/wsdl?websvc=SWC@1.1001:WebService
&style=doc

Im ersten Beispiel wird das Webservice über die Objektadresse (COO.1.1001.1.2049569) angesprochen. Das zweite Beispiel benutzt die Referenz des Webservice (SWC@1.1001:WebService).

Ab der Version Fabasoft Folio 2017 wird die Beschreibung der Parameter (actparoptional) ausgewertet, bis dahin waren alle Parameter optional.