SOAP interface

With the SOAP interface system type, DDM fetches documents from a system that offers them through a SOAP web service – often older DMS, ERP or archive systems. It works like the REST interface: a request chain calls the service, and a field mapping says what each value of the response means. Read the REST guide first – this page only covers what is different with SOAP.

What is different from REST

• You write the SOAP envelope yourself in the Body of a step with the POST method. DDM does not read a WSDL and does not build an envelope.
• Responses in XML are converted by DDM into a tree, so you can address them with the same dotted paths as JSON – see Paths in XML responses.
• The files themselves are downloaded by DDM with GET from the File URL. Your service must return such an address for each document; file contents embedded as Base64 in the SOAP response cannot be taken over by DDM.

1. Add the source

Under Settings › External sources, add a source with New source, give it a name and choose SOAP interface as the System type.

The steps' paths are appended to the Endpoint as they are to the base URL with REST. Usually all steps call the endpoint itself – then leave the Path empty (or /) – see Path and base URL.

Test connection calls the endpoint with GET. Many SOAP services answer that with 405 or 500 – here that counts as The interface answers (HTTP …) and only means the address is reachable. Whether the service really answers is shown by Test chain.

2. Headers and SOAP version

SOAP 1.1 – most services: enter the operation under SOAPAction, e.g. urn:documents/List. DDM sends it as the SOAPAction header on every step (in quotation marks, as SOAP requires) and marks the XML body as text/xml. Nothing else is needed.

SOAP 1.2: leave SOAPAction empty and enter the Content-Type with the operation under the step's Headers:

Content-Type: application/soap+xml; charset=utf-8; action="urn:documents/List"

If a step calls a different operation from the others, give it under the step's Headers – SOAPAction: "urn:documents/File". What a step names itself takes precedence over the source's field. Headers takes one header per line.

3. A step with a SOAP envelope

Step 1 – „List documents": POST, path empty, Body:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:d="urn:documents">
  <soap:Body>
    <d:List>
      <d:Folder>Sales</d:Folder>
    </d:List>
  </soap:Body>
</soap:Envelope>

You insert variables from earlier steps into the body with {{name}}, e.g. <d:Folder>{{folder}}</d:Folder>. DDM escapes them as XML text – an & in the value does not break the envelope.

Paths in XML responses

Suppose the service answers:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ListResponse xmlns="urn:documents">
      <document id="4711">
        <title>Pricelist.pdf</title>
        <url>https://archive.company.com/files/4711</url>
        <folder>Sales/Prices</folder>
      </document>
      <document id="4712">
        <title>Catalogue.pdf</title>
        <url>https://archive.company.com/files/4712</url>
        <folder>Sales</folder>
      </document>
    </ListResponse>
  </soap:Body>
</soap:Envelope>

DDM reads this as follows:

• Namespace prefixes are dropped: soap:Envelope becomes Envelope.
• An element that occurs more than once becomes a list: document is a list with two entries.
• An element that contains only text is that text: title is Pricelist.pdf.
• Attributes are prefixed with @: @id is 4711.

Click Test chain: under Example response you see the service's response, and the preview beside each mapping shows what becomes of the first entry. If the service answers with a SOAP fault, the step is set to failed (usually HTTP 500), with the text of the fault beneath it – e.g. HTTP 500 — soap:Client Unknown operation. The Example response keeps the last successful response.

Everything else

Variables, transformations, group mapping, multi-step chains and the limits are the same as with the REST interface – see REST interface. Import scope and sync are explained in the Overview.