Providing SOAP Web Services in Document Mode

Learn how to provide SOAP web services in Document mode with the X4 BPMS.

Prerequisites:

• Basic knowledge of the structure of  SOAP web services in Document style, in which the Request/Response Body is described completely via an XML Schema (XSD).
• A Technical Process per web service operation, which assumes the processing of the incoming request. The Technical Process is referenced via its x4db:/ URL, thereby.
• A URL part, under which the SOAP web service shall be accessible via HTTP, e.g. http://localhost:8080/X4/httpstarter/ReST/MyDocumentWebservice. Normally, you have already defined this URL part as constant within the webservices configuration, see Graphically Editing the Web Service Configuration.

In order to provide a Technical Process as SOAP web service in Document mode, proceed as follows:

1. Create a new SOAP service entry under the desired URL resource (defined e.g. by means of a constant URL part) via the context menu Add SOAP Service.

2. Specify the SOAP version (either SOAP 1.1, SOAP 1.2 or support for both standards).

3. Select the WSDL mode in WSDL Mode and the target prefix in Service Prefix.

4. Define the following configuration for each operation:

   • Specify a valid name for the operation.
      SOAP web services in Document mode require explicit Localnames for the operations.

   • Specify the namespace declaration for the data within the Request/Response body.

   • Link the Technical Process which handles the web service request using its x4db:/ URL.
      Within the Webservice Configuration Editor this is possible by drag & drop from the Repository Navigator.

   • Define the input handler and output handler for the SOAP web service.
     Example: Define the SOAP-Content to use the first element within the soap:Body as input and to create a soap:Body and a soap:Envelope element for the output.

   • Specify the expected input XML data structure including the namespace within the element <Input>.

   • Specify the output data structure to be generated including the namespace within the element <Output>.

5. Save and apply the web service configuration with Reload on Server.
   The SOAP web service in Document mode will be active instantly.

Generated WSDL Definitions in Document Mode

The automatically generated corresponding WSDL definition uses the DOCUMENT mode and is output in case of an HTTP GET call of the SOAP web service URL.

For the WSDL mode DOCUMENT, the X4 Server generates a WSDL definition from the service configuration. The WSDL definition is created as follows:

• For each namespace element with an attribute schemaLocation an xsd:schema with xsd:include for the schemaLocation will be generated under wsdl:types. 
• For each operation a wsdl:message will be generated whose name corresponds to the Localname of the configured operation. For each Input part a corresponding wsdl:part will be generated within this message.
• For each operation a wsdl:message will be generated whose name corresponds to the Localname of the configured operation, supplemented by Response. For each Output part a corresponding wsdl:part will be generated within this message.
• For each operation a wsdl:operation and thus a wsdl:portTyp will be generated. The name of the wsdl:operation is the Localname of the configured operation. The above generated messages are used as input/output message.
• Depending on the SOAP version, corresponding wsdl:bindings are generated (exclusivelyliteral bindings). An empty SOAP action is defined at all times.

<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>