SOAP module

Last modified by Aurelie Bertrand on 2026/01/12 15:14

This document describes how to connect to a data source by querying a SOAP web service.

Prerequisites

  • The acronyms used below are referenced in the lexicon at the end of this document.
  • Have the <digdash_installation>/add-ons/soap folder containing the web application needed to set up calls to SOAP Web Services from DigDash. The installation of this add-on will be described in this document.
  • Have a list of WSDL files corresponding to the Services we want to call.
  • Have a basic understanding of the structure of SOAP requests (in XML) and the methods to be called. Documentation from the Service Provider (which DigDash does not supply) may be required.
  • Knowledge of the formats of the SOAP request parameter values to be filled in, documentation from the Service Provider (which DigDash does not provide) may be required.

💡 DigDash provides help for consulting the structure of SOAP requests.

Go to <digdash_server>/ddsoap?about=true for information about your SOAP configuration.

Description

General

DigDash offers the ability to retrieve data sources by querying SOAP web services.

Since SOAP exchanges take place via messages in XML format, the aim is to be able to retrieve SOAP responses in XML format from the web service and use them directly as XML data sources that DigDash can process.

To do this, DigDash will work mainly with the web service interfaces, the WSDL files that you will need to supply. These provide a detailed description of what the web services to be called offer.

DigDash is based on the Java API of the famous SOAP client, SOAP UI. The logic and the way of querying the desired web service will be quite similar, in the sense that you will have to fill in the values of the request parameters.

Hence, as indicated in the prerequisites, you need to have a basic understanding of the structure of SOAP requests in XML format.

Technical description

DigDash offers this functionality as a module (or add-on) to be installed with the product (it is not installed natively). There is therefore no "web service" type data source, but we will use the existing principle in DigDash of WLNK files to host the information needed to retrieve data via SOAP.

💡 A WLNK file in DigDash contains a URL. The content pointed to by the URL is downloaded by the server each time it needs it (for a data source or on request from a user).

Why create a WLNK file?

We could create a simple XML data source file, but this would simply be a snapshot of the data at a given point in time. The WLNK file makes it possible to refresh the data when necessary.

You should also bear in mind that a WLNK file only contains the information needed to calla single SOAP request.

⇒ One WLNK file = One SOAP request

In DigDash, you will not need to call the service entry point directly, but instead use a web application (which can be deployed on the same DigDash Tomcat server) that DigDash has developed and which is mainly the add-on. This web application will be responsible for sending the SOAP request with the information you have provided in DigDash and will be responsible for retrieving the SOAP response in DigDash.

SOAP

Installation and configuration of the SOAP module

Installation and deployment of the web application

  1. First of all, stop the DigDash server.
  2. Copy the ddsoap.war web application located in the <digdash_installation>/add-ons/soap folder to the <digdash_installation>/apache-tomcat/webapps folder.
  3. Restart the DigDash server to deploy the application.

wsdls folder

In the <digdash_installation>/add-ons/ddsoap/wsdls folder, place the list of WSDL files (.wsdl) corresponding to the descriptions of the services you wish to query.

Configuring the soap_props.properties file

In the deployed application folder, configure the ddsoap/soap_props.properties file as follows:

Miscellaneous properties

PropertiesDescription
PRINT_DEBUG

This property must be set to true for other traces to be displayed. Only error traces are displayed at all times.

This property is used to display debug traces in the logs.

SHOW_REQUESTSUsed to display SOAP requests sent to the Web Service.
SHOW_RESPONSESDisplays SOAP responses sent by the Web Service.
LOGIN_BEFORE_CALL_SERVICEEnables authentication to be performed before the request is sent, using the identifier properties (prefixed with _creds , see next section).
REMOVE_REQUEST_EMPTY_VALUESRemoves empty values (identified by "?") from the SOAP request.
REMOVE_REQUEST_EMPTY_NODESRemoves empty nodes from the SOAP request.

Identifier properties

Authentication may be required before calling a service method.

ALL these properties must be prefixed with "creds_" AND the LOGIN_BEFORE_CALL_SERVICE property must be set to "true" (see III.3.1).

PropertiesDescription
Warning : special characters must be escaped in property names (\= for = , \: for :)
creds_binding(Mandatory) The name of the service used to authenticate.
creds_operation(Required) The name of the authentication operation.
creds_<username>The login, if any, for authentication.
creds_<password>The password, if any, for authentication.
creds_<any other parameter>Any other parameters used for authentication.

Configuration in DigDash

Creating the WLNK file

We're going to start with the classic process of extracting data from a file in XML format.

  1. From the Templates tab in the Studio, click on the New Template button.
  2. In the Create a new data model box, click on the All types button in the Files section.
  3. Select the document server you wish to use.
  4. Click on the Add a file... button.
  5. Three options are available. To retrieve content via SOAP, we'll use the From a remote address or server option
    • The URL to call is that of the previously deployed ddsoap web application (<digdash_server_address>/ddsoap).
    • The name of the WLNK file must end in .xml
    • Check the option Add only the URL link to the document server. This option creates a WLNK file.
    • You can customise the maximum request time (in seconds) for a WLNK (only values > 0 will be taken into account, otherwise the default timeout is applied).
      ddsoap wlnk file

You can enter the parameters for the SOAP request in the form of a key-value in the GET HTTP parameters:

  • Click on the HTTP GET parameters... button, then enter the name and value of each parameter.

You MUST enter at least these two parameters :
 _binding: the name of the Service to be called
 _operation: the name of the operation or method of the Service to be called.

HTTP request parameters

For the other SOAP parameters, you must specify their names (don't forget the namespaces if there are any). If several parameters appear in the request, fill in the names of the parents enabling you to reach the required node.

In general, the first node in the request with the specified name will be selected, unless the path to a specific node is specified (by going back into the parents, but not all the way to the root).

SeparatorsDescriptionExample
/Path separator in the XML tree.

<a>

<a1>

<b>?</b>

<c>?</c>

</a1>

<b>?</b>

<c>?</c>

</a>

<a1>

<b>?</b>

<c>?</c>

</a1>

To access element c, write a/c (c will select the first element c)

@To access an attribute of an XML element.

<a>

<b>?</b>

<c attr=?>?</c>

<a>

To access the attr attribute of element c, we would write a/c@attr (or  c@attrmailto:c@attr directly)

Once the SOAP parameters have been entered, click OK to validate.
➡ The WLNK document will be created and uploaded to the selected document server.

This WLNK file can then be loaded as an XML data source in the conventional way.

The newly created WLNK file can then be modified manually if required. Right-click on the "Configure WLNK file" menu to edit the link and query parameters.
Contextual menu

Edit wlnk

Pagination management

The SOAP module can help you aggregate the data from a paginated request to retrieve all the data from DigDash.

To do this, you must specify the following GET parameters in the URL:

pagination: this parameter must be true to specify a case of pagination.

_pageTag: in this parameter you must specify the name of the tag (it can be an element or an attribute) which defines pagination (see the table: Naming convention for accessing a node to define this parameter).

_pageStartElement: this is the name of the element containing the lines of data we are interested in (see next section). If you do not know the structure of the SOAP response, you will generally have to send an initial request without pagination to find out the name of this tag (see the table: Naming convention for accessing a node to define this parameter).

pageInc: the page index starts at 0. This parameter defines the incrementation of this index.

_resultSize (optional): specifying the total number of results optimises response time.

Configuring the XML data source

Loading the SOAP response in XML format as a data source in DigDash can be difficult to read at first.

You need to make a few changes to the configuration of the DigDash data source to make it easier to read.

For example: if we consider a SOAP response with the following XML structure :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>

<a></a>

<structs>
   <struct1>
       <s11></s11>
       <s12>
           <s121></s121>
       </s12>
       <s13></s13>
       <s14></s14>
   </struct1>
   
   <struct2>
       <s21></s21>
       <s22>
           <s221></s221>
       </s22>
       <s23></s23>
       <s24></s24>
   </struct2>

   <struct3>
       <s31></s31>
       <s32>
           <s321></s321>
       </s32>
       <s33></s33>
       <s34></s34>
   </struct3>
</structs>

</soapenv:Body>
</soapenv:Envelope>

We need to try and identify the structure encompassing the structures (rows) we are interested in. In this example of a SOAP response, the structures struct1, struct2, struct3 are the ones we are interested in.

The structure encompassing these is the structs structure .

In the configuration of the data model, in the advanced options for data selection, you will therefore need to specify the following:

  1. Click on the Advanced button in the Data selection section.
    Avancé​​​​​​​

  2. Check the Start reading XML from a specified tag option and specify the structure from which to start reading the XML.
    It is also preferable to uncheck the Expand child nodes and attributes into columns option

  3. Click OK.

Glossary

In this document we refer to :

  • SOAP: Simple Object Access Protocol. It is a protocol for exchanging structured information in the implementation of XML-based web services. (Wikipedia)
  • WSDL: Web Services Description Language. This is a file in XML format used to describe a web service.
  • WLNK : Web LiNK. Files with the .wlnk extension contain links to data sources.

References

DigDash uses the soapui OpenSource library from SmartBear Software to support exchanges with SOAP web services.

https://www.soapui.org