Connecting to SOAP Web Services

Simple Object Access Protocol (SOAP) is protocol that uses an XML-based format for sending and receiving messages via web services. The SOAP XML structure can consist of:

<envelope> element that identifies the XML document as a SOAP message.
<header> element that contains header information specific to the application, like security credentials or instructions for processing the request.
<body> element that contains call and response information.
<fault> element containing errors and status information.

To get started working with SOAP web services, let’s review a simple tutorial using a Postman public SOAP API. You can apply these concepts to your own integration projects:

Create a Component named SOAP Tutorial. Open the Translator to get started! We’ll be using the following WSDL

Using Postman's public SOAP APIs we can learn how to interact with a SOAP web service. When provided a country code, this SOAP web service responds with the country’s capital city.

https://www.postman.com/cs-demo/public-soap-apis/request/w274p5s/captial-city-for-a-country

Let’s use the provided XML structure from Postman as a SOAP template to get started. Add it to the top of the Translator script.

You can see that this SOAP template contains the SOAP envelope and body.

The template will vary depending on the web service’s required SOAP structure.

local XmlTemplate=[==[
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CapitalCity xmlns="http://www.oorsprong.org/websamples.countryinfo">
      <sCountryISOCode></sCountryISOCode>
    </CapitalCity>
  </soap:Body>
</soap:Envelope>
]==]

Use xml.parse{} and map the your source data into the parsed XML.
Using :setInner() we can set the Country Code value as 'CA' for Canada.
Once finished populating the XML, it must be serialized as a string before being sent in the body of the SOAP web request. This can be done using :S() or tostring().

When doing more complex processing on XML data, import the XML Library to extend processing capabilities and generate your SOAP XML efficiently.

For SOAP web services, use Custom Fields to store configurations such as:

The SOAP URL or endpoint.
Authentication information such as username and password.
TLS/SSL certificates and keys if the SOAP web service requires TLS authentication.

For this tutorial, open config.json and add a URL configuration with the SOAP URL.

http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso'

Store your custom fields in a config variable outside of main() to use it in your web request.

local config = component.fields()

Send the request with net.http.post{} where:

url of the SOAP web service. Stored in your custom field config variable.
headers table providing details about the HTTP request such as Content-Type or Authentication information. This is separate from the <header> element included in the SOAP envelope of the request which stores application specific information important in processing the request.
body with the prepared soapXML payload.
Optional: ssl parameter if you require TLS.

Set live=true and use the Annotations to view the returned XML response containing the corresponding capital city.

Use xml.parse{} again to parse the XML response and capture the information.

In Production, use pcall() and the Retry Library to make the web request to enhance resiliency and response handling. See Building HTTP Requests for more recommendations.