SOAP-Webservice im Document-Modus bereitstellen

Wie Sie mit der X4 BPMS einen SOAP-Webservice im Document-Stil bereitstellen, wird im Folgenden beschrieben.

Voraussetzungen:

• Grundlegendes Wissen über den Aufbau von SOAP-Webservices im Document-Stil, bei welchen der Request/Response Body per XML-Schema (XSD) vollständig beschrieben sind.
• Ein Technical Process pro Webservice-Operation, der die Verarbeitung der eingehenden Anfrage übernimmt.  Der Technical Process wird dabei über seine x4db:/-URL referenziert.
• Ein URL-Part, über den der SOAP-Webservice via HTTP erreichbar sein soll, z.B. über http://localhost:8080/X4/httpstarter/ReST/MyDocumentWebservice. Diesen URL-Part haben Sie bereits typischerweise als Konstante innerhalb der Webservices-Konfiguration definiert, siehe Webservice-Konfiguration grafisch bearbeiten.

Um einen Technical Process als SOAP-Webservice im Document-Stil bereitzustellen, gehen Sie wie folgt vor:

1. Unter der gewünschten URL-Ressource (definiert z.B. durch einen konstanten URL-Part) über das Kontextmenü Add SOAP Service einen neuen Service-Eintrag vom Typ SOAP anlegen.

2. SOAP-Version festlegen (entweder SOAP 1.1, SOAP 1.2 oder Unterstützung für beide Standards).

3. WSDL-Modus in WSDL Mode und Zielpräfix in Service Prefix wählen.

4. Für jede Operation folgende Informationen hinterlegen:

   • Einen gültigen Namen für die Operation hinterlegen.
     SOAP-Webservices im Document-Modus erfordern eindeutige Localnames für die Operationen.

   • Namespace-Deklaration für die Daten im Request/Response Body hinterlegen.

   • Technical Process, der die Webservice-Anfrage über den X4 Server verarbeitet, über dessen x4db:/-URL verknüpfen.
     Im Webservice Configuration Editor ist dies per Drag & Drop aus dem Repository Navigator möglich.

   • Input Handler und Output Handler für den SOAP-Webservice definieren.
     Beispiel: SOAP-Content definieren, um das erste Element im soap:Body als Input zu verwenden sowie beim Output ein soap:Body- und soap:Envelope-Element zu erzeugen.

   • Erwartete Input-XML-Datenstruktur innerhalb von Element <Input> inklusive Namespace angeben.

   • Zu erzeugende Ausgabe-Datenstruktur innerhalb von Element <Output> inklusive Namespace angeben.

5. Speichern und Webservice-Konfiguration mit Reload on Server anwenden.
   Der SOAP-Webservice im Document-Stil ist ab sofort aktiv.

Generierte WSDL-Definition im Document-Modus

Die automatisch generierte zugehörige WSDL-Definition verwendet den Document-Stil und wird bei einem HTTP GET-Aufruf der SOAP-Webservice-URLs ausgeliefert.

Für den WSDL-Modus DOCUMENT erzeugt der X4 Server eine WSDL-Definition aus der Service-Konfiguration. Die WSDL-Definition wird wie folgt erstellt:

• Für jedes Namespace-Element mit schemaLocation-Attribut wird unter wsdl:types ein xsd:schema mit xsd:include für die schemaLocation erzeugt.
• Für jede Operation wird eine wsdl:message erzeugt, deren Name dem Localname der konfigurierten Operation entspricht. Innerhalb dieser Message wird für jedes Input-Part ein entsprechendes wsdl:part erstellt.
• Für jede Operation wird eine wsdl:message erzeugt, deren Name dem Localname der konfigurierten Operation, ergänzt um Response, entspricht. Innerhalb dieser Nachricht wird für jedes Output-Part ein entsprechendes wsdl:part erstellt.
• Für jede Operation wird eine wsdl:operation und damit ein wsdl:portTyp erzeugt. Der Name der wsdl:operation ist der Localname der konfigurierten Operation. Als Input-/Output-Nachricht werden die oben erzeugten Nachrichten verwendet.
• Je nach SOAP-Version werden entsprechende wsdl:bindings erzeugt (ausschließlich literal Bindings). Es wird immer eine leere SOAP-Action definiert.

<Service type="Soap">
	<SoapVersion>
		<SOAP11/>
		<SOAP12/>
	</SoapVersion>
	<Wsdl name="NameOfTheDocumentService" targetPrefix="service" mode="DOCUMENT"/>
	<Namespace prefix="service" namespace="http://example.org/serviceSpace"/>
	<Namespace prefix="exampleSpace" namespace="http://example.org/namespace"
     schemaLocation="http://localhost:8080/X4/httpstarter/ReST/soapService/xsd/namespace.xsd"/>
	<Namespace prefix="anotherSpace" namespace="http://example.org/different/namespace"
     schemaLocation="http://localhost:8080/X4/httpstarter/ReST/soapService/xsd/differentNamespace.xsd"/>
	<!-- DOCUMENT requires unique localnames for the operations -->
	<Operation name="irrelevantName1" 
        process="x4db:/1/RestExamples/soap/DirectOutput.wrf">
		<InputHandler type="SOAP-Envelope"/>
		<OutputHandler type="SOAP-Envelope"/>
		<Input>
			<Part name="firstPart" element="exampleSpace:SpacedOperation"/>
		</Input>
		<Output>
			<Part name="firstPart" element="exampleSpace:Operation1"/>
		</Output>
	</Operation>
	<Operation name="irrelevantName2" 
        process="x4db:/1/RestExamples/soap/DirectOutput.wrf">
		<InputHandler type="SOAP-Envelope"/>
		<OutputHandler type="SOAP-Envelope"/>
		<Input>
			<Part name="firstPart" element="anotherSpace:SpacedOperation"/>
		</Input>
		<Output>
			<Part name="Output" element="anotherSpace:SpacedOperation"/>
		</Output>
	</Operation>
	<Operation name="irrelevantName3" 
        process="x4db:/1/RestExamples/soap/DirectOutput.wrf">
		<InputHandler type="SOAP-Envelope"/>
		<OutputHandler type="SOAP-Envelope"/>
		<Input>
			<Part name="UnSpacedOperation" type="xsd:integer"/>
		</Input>
		<Output>
			<Part name="Value" type="xsd:String"/>
		</Output>
	</Operation>
</Service>