Skip to main content

Introduction​

This document describes how to configure and use Incoming SOAP Web Services in ADITO. It covers endpoint formatting, configuration prerequisites, authentication methods, and detailed behavior of SOAP response properties.

Endpoint Format​

SOAP web services are accessible at the following URL pattern:

http://<host>:<port>/services/soap/<webserviceProcessName>

To retrieve the WSDL definition for a SOAP web service, append ?wsdl to the endpoint URL:

http://<host>:<port>/services/soap/<webserviceProcessName>?wsdl

Example​

  • Service endpoint:
    http://aditoserver:8080/services/soap/customerService
  • WSDL URL:
    http://aditoserver:8080/services/soap/customerService?wsdl
info

The <webserviceProcessName> corresponds to the name of the process configured in ADITO.

Configuration​

To enable a SOAP web service endpoint in ADITO, ensure the following:

  • The process exists under the Processes node.
  • The process has its style property set to SOAP_DOCUMENT.
  • At least one authentication method is enabled (see Authentication).

Server Host Configuration​

When configuring the jditoWebserviceServerHost parameter:

  • Setting the host to localhost restricts the server to listen only on local addresses (localhost, 127.0.0.1, etc.).
  • Leaving the field empty allows the server to listen on all network interfaces (e.g., server.adito.de, 192.168.0.200, localhost, etc.).

Timeout Configuration​

You can adjust the timeout for incoming web services by setting the expert parameter jditoWebserviceIdleTimeout in the server instance configuration. The value is specified in milliseconds.

Authentication​

ADITO supports the following authentication methods for SOAP web services:

  • Anonymous access
  • Basic Authentication
  • User Token
info

At least one authentication method must be enabled to allow access to SOAP web services.

Response Behavior​

Starting with version 2023.1.3, two process properties control the SOAP web service response structure:

Propertyfalse (default)true
soapOmitEmptyResultAlways include the <result></result> node, even if empty or missingOmit the <result></result> node if the function returns no value
soapUseRawXmlResultWrap the returned value inside a <result></result> nodeInsert the returned XML directly into the SOAP body without wrapping

Example: Input "foo"​

This example demonstrates how the response varies based on the combination of soapOmitEmptyResult and soapUseRawXmlResult settings.

1. Default behavior (soapOmitEmptyResult: false, soapUseRawXmlResult: false)​

The response wraps the returned value inside a <return> node.

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
               xmlns:tns="http://adito/webservice">
  <soap:Body>
    <tns:getXMLResponse xmlns:tns="http://adito/webservice">
      <return>foo</return>
    </tns:getXMLResponse>
  </soap:Body>
</soap:Envelope>

2. Raw XML Result enabled (soapOmitEmptyResult: false, soapUseRawXmlResult: true)​

The returned value is inserted directly without wrapping <return> node.

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
               xmlns:tns="http://adito/webservice">
  <soap:Body>
    <tns:getXMLResponse xmlns:tns="http://adito/webservice">
      foo
    </tns:getXMLResponse>
  </soap:Body>
</soap:Envelope>

3. Omit Empty Result enabled (soapOmitEmptyResult: true, soapUseRawXmlResult: false)​

Since the input is not empty, the <return> node is included as usual.

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
               xmlns:tns="http://adito/webservice">
  <soap:Body>
    <tns:getXMLResponse xmlns:tns="http://adito/webservice">
      <return>foo</return>
    </tns:getXMLResponse>
  </soap:Body>
</soap:Envelope>

Example: Input "" (empty string)​

This example shows the SOAP response for an empty string input under different settings.

1. Default behavior (soapOmitEmptyResult: false, soapUseRawXmlResult: false)**: The <return> node is present but empty.​

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
               xmlns:tns="http://adito/webservice">
  <soap:Body>
    <tns:getXMLResponse xmlns:tns="http://adito/webservice">
      <return></return>
    </tns:getXMLResponse>
  </soap:Body>
</soap:Envelope>

2. Raw XML Result enabled (soapOmitEmptyResult: false, soapUseRawXmlResult: true)​

The returned value is inserted directly without wrapping <return> node. As it is empty, the body is also empty.

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
               xmlns:tns="http://adito/webservice">
  <soap:Body>
    <tns:getXMLResponse xmlns:tns="http://adito/webservice">
    </tns:getXMLResponse>
  </soap:Body>
</soap:Envelope>

3. Omit Empty Result enabled (soapOmitEmptyResult: true, soapUseRawXmlResult: false)​

Since the input is empty and soapOmitEmptyResult is enabled, the <return> node is omitted from the response.

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
               xmlns:tns="http://adito/webservice">
  <soap:Body>
    <tns:getXMLResponse xmlns:tns="http://adito/webservice">
    </tns:getXMLResponse>
  </soap:Body>
</soap:Envelope>

Note on empty string return (""):

  • With soapOmitEmptyResult enabled, the <return> node is omitted entirely if empty.
  • With soapUseRawXmlResult enabled, the response body is empty inside the <tns:getXMLResponse> node.

Note on raw XML return (e.g., <someResult>foo</someResult><bool>true</bool>):

  • With default settings, the XML is wrapped inside <return>.
  • With soapUseRawXmlResult enabled, the XML is inserted directly, preserving the structure.

Namespace Requirement​

warning

SOAP documents can only be processed correctly if the nodes use the ADITO namespace:

xmlns:adito="http://adito/webservice"

ADITO requires this exact URL to map the input to the SOAP function and its parameters. Using a different URL will cause internal processing errors.

The alias prefix (adito) can be different, but the namespace URL must match exactly, for example:

xmlns:CUSTOM="http://adito/webservice"

Parallel Execution​

Web service calls in ADITO are processed in parallel. Sequential execution is not supported.