Overview

This document describes how to interact with external SOAP web services using JDito. JDito provides methods to send SOAP requests with or without Basic Authentication.

Method Signatures

JDito exposes the following methods for calling SOAP web services:

• net.callSoapWebserviceBasicAuth(url, xml, action, user, password)
• net.callSoapWebserviceNoAuth(url, xml, action)

Parameters

Parameter	Description
url	The URL of the SOAP web service endpoint.
xml	An XML string structured according to the SOAP call defined in the WSDL. This XML can be generated with SoapUI.
action	The name of the web service action to be executed.
user	(Basic Auth only) Username for authentication.
password	(Basic Auth only) Password for authentication.

Return Structure

Both methods return a string array with two elements:

Index	Description
0	"true" or "false" indicating whether the call was successful.
1	The response XML if successful, or an error message if the call failed.

Creating SOAP XML with SoapUI

To generate the SOAP XML required for the request, you can use the SoapUI tool, which is available at https://www.soapui.org/downloads/soapui.html.

1. Download and install SoapUI.
2. Create a new SOAP project via File → New SOAP Project.
3. Configure the project to target the desired web service.
4. Construct the request XML as needed.
5. Copy the generated XML from the request window for use in JDito.

Example SOAP XML:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://adito/webservice">
   <soapenv:Header/>
   <soapenv:Body>
      <web:getXML>
         <inputRequest>?</inputRequest>
      </web:getXML>
   </soapenv:Body>
</soapenv:Envelope>

Example Call

The following example demonstrates how to call a SOAP web service using net.callSoapWebserviceNoAuth:

import { logging, net } from "@aditosoftware/jdito-types";

// URL of the SOAP web service
var url = "http://localhost:7936/ws_soap_in";
// Name of the web service action
var action = "getXML";
// Input data to be sent
var data = "This is the input";

// Construct the SOAP XML string (note the escaped quotes)
var xmlString = 
    "<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:web=\"http://adito/webservice\">" +
        "<soapenv:Header/>" +
        "<soapenv:Body>" +
            "<web:getXML>" + // The part after 'web:' is the action name
                "<inputRequest>" + data + "</inputRequest>" +
            "</web:getXML>" +
        "</soapenv:Body>" +
    "</soapenv:Envelope>";

// Call the web service without authentication
var res = net.callSoapWebserviceNoAuth(url, xmlString, action);

// Check if the call was successful
if (res[0] === "true") {
    logging.log("SOAP Call Response:\n" + res[1]);
} else {
    // Throw an error with the returned message
    throw res[1];
}

Special Character Handling

If the input data contains special characters such as Ä, Ö, Ü, or ß, the SOAP call may fail. To prevent this, you can escape these characters by replacing them with their Unicode entity codes.

Example function to escape special characters:

function escapeSpecialCharacters(pStr) {
    var replaceRegEx = /Ä|ä|Ö|ö|Ü|ü|ß/g;

    pStr = pStr.replace(replaceRegEx, function (value) {
        switch (value) {
            case "Ä":
                return "Ä";
            case "ä":
                return "ä";
            case "Ö":
                return "Ö";
            case "ö":
                return "ö";
            case "Ü":
                return "Ü";
            case "ü":
                return "ü";
            case "ß":
                return "ß";
        }
    });

    return pStr;
}

Pass your input string through this function before inserting it into the XML to ensure proper encoding of special characters.