Consume SOAP Web Service

Owned by Kevin Joseff Cabrera
Last updated: Apr 22, 2024
4 min read



This plugin consumes a SOAP Web Service and optionally captures the response as a list, record, or value.

It is similar to the Consume REST Web Service plugin in both look and functionality, but with some changes:

  • This plugin only uses POST method by default

  • If capturing a response, the http response status is also required to be received along with the response body

  • The plugin expects to receive an XML response from a SOAP API and allows users to parse this response into a javascript object

  • The Auth field is not yet added to it as some SOAP APIs have different methods of requiring authorization, i.e. from the HTTP header itself, or within the SOAP envelope

  • Only an XML object is accepted by the Body question. XML objects or entries can however be passed by inserting Dynamic Data.

This plugin is compatible to use with conditional low-code steps such as “Check if last step was successful” and any similar custom code usage. See Using conditional steps with the Consume SOAP Web Service Plugin section for more details.

chrome_CSzU6qoJE9.png

Endpoint URL

  • Specify a REST endpoint. Internal endpoint URL's you've defined previously are suggested in the dropdown.

Headers

  • Provide HTTP headers in the form of a JavaScript object.

Body

  • Specify the request body as a valid XML string. Line breaks should not be present within the XML entry to prevent errors during execution.

Capture response?

  • Check this box to capture the Web Service response into a variable or property. When enabled, the response is captured as a javascript object with all the components of the response as values, including the response header and status. It also captures the responses for errors such as 4xx and 5xx status codes.

Parse captured SOAP response into Javascript object?

  • By default, the response captured for SOAP APIs is in XML format. Checking this will convert the XML response into a Javascript object,

    • When enabled, the first key from the resulting Javascript object’s is labelled using the SOAP XML body’s namespace + “:” + the element name.

      • For example, if the XML body namespace was “soapenv”, and the first element is named “Envelope”, and the variable to store the response is “yourVariableName”, then the first object key within the body property is:
        yourVariableName["body"]["soapenv:Envelope"]

      • You may find more details via the Extracting the data from the captured response section

Where do you want to place the response?

  • The response can be placed into a work, global property, or a session property.

Enter Work variable name

  • A work variable is accessible by other steps within the same routine.

Enter Global property name

  • A global property is accessible by any routine within your Rich Display.

Enter Session property name

  • A session property is accessible across all Rich Display apps and Node.js programs.

Enter Module Output name

  • If the routine is in a Module Context, this saves the response into a Module property’s output.

Enter API Output name

  • If the routine is in an API Context, this saves the response into an API output.

Extracting the data from the captured response

  • When “Capture Response” is enabled, the response is recorded into a javascript object. To access the response object’s different properties, the following keys can be used:

    • body - for the response body. This value returns a string if “Parse captured SOAP response into Javascript object?” is disabled.

    • code - for the response status

    • headers - for the response headers

  • e.g. if the assigned variable for the response is “soapresponse”, accessing the properties would be as follows:

    • soapresponse[“body”]

    • soapresponse[“code”]

    • soapresponse[“headers”]

  • If “Parse captured SOAP response into Javascript object?” is also enabled, then the body property will also contain a parsed object. Depending on the SOAP request’s XML namespace, the object key name would also vary accordingly.
    e.g. if the Soap request XML used was:

    • <?xml version="1.0" encoding="utf-8"?>
      <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> soap:Body
      <NumberToWords xmlns="http://www.dataaccess.com/webservicesserver/">
      <ubiNum>500</ubiNum>
      </NumberToWords>
      </soap:Body>
      </soap:Envelope>
      Then accessing the parsed object would be via:

      • soapresponse[“body”]["soap:Envelope"]

WindowsTerminal_TWl2JpullY.png

Using conditional steps with the Consume SOAP Web Service Plugin

  • The Consume SOAP Web Service’s generated code includes a try-catch block to capture errors if ever the API call fails or times out. This block of code either fills a variable called “_success” when the call succeeds, or “_error” when it fails or times out:

  • The “_success” and “_error” variables allow the SOAP plugin to work inside a Conditional Low-code step, such as the “Check if Last Step was successful” step:

  • You can also use the same “_success” and “_error” variables if you need to check if the previous consume SOAP step was successful or not in your custom code:
    if (typeof _success !== "undefined" && _success) {
    do code if SOAP call was successful
    }