Providing SOAP Web Services with External WSDL Definition

Learn how to provide SOAP web services (e.g. in RPC style) based on a consisting WSDL definition with the X4 BPMS.

Prerequisites:

Basic knowledge of the structure of SOAP webservices.
The WSDL definition must be valid and accessible for the consumer via a valid URL, e.g. via HTTP.
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/ MyExternalWSDLWebservice. Typically, you have already defined this URL part as constant within the webservice configuration, see Graphically Editing the Web Service Configuration.

In order to provide a Technical Process as SOAP web service with external WSDL definition, proceed as follows:

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 and adjust the (security) properties, if required.
Specify the SOAP version (either SOAP 1.1, SOAP 1.2 or support for both standards).
Select the WSDL mode EXTERNAL and enter a valid URL to the WSDL definition in WSDL URL.
You can can also provide a self-created WSDL definition and an XSD from the repository. Provide the WSDL definition file as file service via HTTP for this purpose, see Providing File Web Services.
Example (Excerpt from XML storage format)

XML
```
<Constant value="externalWsdl">
	<Service type="File" path="x4db:/1/RestExamples/soap/externalWsdl.xml"/>
</Constant>
<Constant value="xsd">
	<Remainder name="FILE">
		<Service type="File" path="x4db:/1/RestExamples/soap/xsd/&lt;FILE>"/>
	</Remainder>
</Constant>
```
You can then reference the file web service URL within the SOAP web service definition e.g. as follows:
Example (Excerpt from XML storage format)

XML
```
<Wsdl mode="EXTERNAL" url="http://localhost:8080/X4/httpstarter/Rest/soapService/externalWsdl"/>
```
You can click on Load Configuration from WSDL within the X4 Webservice Configuration Editor to load the WSDL definition with the corresponding web service information (SOAP version, service prefix, linked XSD schemas and available web service operations).
For each web service operation defined in WSDL, a correspondingly named child node will be generated within the tree structure of the X4 Webservice Configuration Editor.
Adjust the configuration for each web service operation within the corresponding child node:
- Link the Technical Process which handles the web service request via the X4 Server using its x4db:/ URL.
  Within the Webservice Configuration Editor this is possible via drag & drop from the repository.
- Define the input and output handler for the SOAP web service.
- Adjust the safety realms (Guest Allowed, Token Return etc.), if required.
Save and apply the web service configuration via Reload on Server.
The SOAP web service will be active instantly and can be called by means of its service URL via HTTP POST.

In case of the service URL's call via HTTP GET, the URL specified within WSDL URL (attribute url) will be forwarded (HTTP redirect).

Example: Configuration of the web service with external WSDL definition

XML

<Service type="Soap">
	<SoapVersion>
		<SOAP11/>
		<SOAP12/>
	</SoapVersion>
	<Wsdl mode="EXTERNAL" url="http://www.webservicex.com/CurrencyConvertor.asmx?wsdl"/>
	<Namespace prefix="exampleSpace" namespace="http://example.org/namespace"/>
	<Namespace prefix="anotherSpace" namespace="http://example.org/different/namespace"/>
	<!-- requires unique qualified names for the operations -->
	<Operation name="exampleSpace:SpacedOperation" 
        process="x4db:/1/RestExamples/soap/DirectOutput.wrf">
		<InputHandler type="SOAP-Envelope"/>
		<OutputHandler type="SOAP-Envelope"/>
	</Operation>
	<Operation name="anotherSpace:SpacedOperation" 
        process="x4db:/1/RestExamples/soap/DirectOutput.wrf">
		<InputHandler type="SOAP-Envelope"/>
		<OutputHandler type="SOAP-Envelope"/>
	</Operation>
	<Operation name="UnSpacedOperation" 
        process="x4db:/1/RestExamples/soap/DirectOutput.wrf">
		<InputHandler type="SOAP-Envelope"/>
		<OutputHandler type="SOAP-Envelope"/>
	</Operation>
</Service>