Connecting to SOAP Web Services

S imple O bject A ccess P rotocol (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:

STEP 1: Create a custom component and name it SOAP Tutorial

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

STEP 2: Use a template SOAP XML structure to build SOAP request

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>   
]==]   

STEP 3: Parse the XML template and map source data to the XML.

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.

STEP 4: Use Custom Fields to store any configurations

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()

STEP 5: Prepare the POST request and view the response from the SOAP web service

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.

Info

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.

Here is a copy of the entire script

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>   
]==]   
   
local config = component.fields()   
   
function main(Data)   
   
   -- Parse the XML SOAP template   
   local X = xml.parse{data=XmlTemplate}   
   
   -- Map source data to the XML   
   X["soap:Envelope"]["soap:Body"].CapitalCity.sCountryISOCode:setInner('CA')   
   
   -- Serialize the XML   
   local soapBody = X:S()   
   
   -- Send POST request to the SOAP web service   
   local response, code, headers = net.http.post{   
      url=config.URL,   
      headers={['Content-type']='text/xml; charset=utf-8'},   
      body=soapBody,   
      live=true   
   }   
   -- Handle the response   
   local R = xml.parse{data=response}   
   local capitalCity = R["soap:Envelope"]["soap:Body"]["m:CapitalCityResponse"]["m:CapitalCityResult"]:nodeText()   
   
   trace(capitalCity)   
   
end   
   