strong-soap

This module provides a Node.js SOAP client for invoking web services and a mock-up SOAP server capability to create and test your web service. This module is based on node-soap module.

Overview

Features:

  • Full SOAP Client capability and mock-up SOAP server capability
  • Handles both RPC and Document styles
  • Handles both SOAP 1.1 and SOAP 1.2 Fault
  • APIs to parse XML into JSON and JSON into XML
  • API to describe WSDL document
  • Support for both synchronous and asynchronous method handlers
  • WS-Security (currently only UsernameToken and PasswordText encoding is supported)

Install

Install with npm:

  npm install strong-soap

Client

Start with the WSDL for the web service you want to invoke. For example, the stock quote service http://www.webservicex.net/stockquote.asmx and the WSDL is http://www.webservicex.net/stockquote.asmx?WSDL

Create a new SOAP client from WSDL URL using soap.createClient(url[, options], callback). Also supports a local file system path. An instance of Client is passed to the soap.createClient callback. It is used to execute methods on the soap service.

"use strict";

var soap = require('strong-soap').soap;
// wsdl of the web service this client is going to invoke. For local wsdl you can use, url = './wsdls/stockquote.wsdl'
var url = 'http://www.webservicex.net/stockquote.asmx?WSDL';

var requestArgs = {
  symbol: 'IBM'
};

var options = {};
soap.createClient(url, options, function(err, client) {
  var method = client['StockQuote']['StockQuoteSoap']['GetQuote'];
  method(requestArgs, function(err, result, envelope, soapHeader) {
    //response envelope
    console.log('Response Envelope: \n' + envelope);
    //'result' is the response body
    console.log('Result: \n' + JSON.stringify(result));
  });
});

As well as creating a client via a url, an existing WSDL object can be passed in via options.WSDL_CACHE.

var soap = require('strong-soap').soap;
var WSDL = soap.WSDL;

var url = 'http://www.webservicex.net/stockquote.asmx?WSDL';

// Pass in WSDL options if any

var options = {};
WSDL.open(url,options,
  function(err, wsdl) {
    // You should be able to get to any information of this WSDL from this object. Traverse
    // the WSDL tree to get  bindings, operations, services, portTypes, messages,
    // parts, and XSD elements/Attributes.

    // Set the wsdl object in the cache. The key (e.g. 'stockquotewsdl')
    // can be anything, but needs to match the parameter passed into soap.createClient()
    var clientOptions = {
      WSDL_CACHE : {
        stockquotewsdl: wsdl
      }
    };
    soap.createClient('stockquotewsdl', clientOptions, function(err, client) {
      var method = client['StockQuote']['StockQuoteSoap']['GetQuote'];
      method(requestArgs, function(err, result, envelope, soapHeader) {

      //response envelope
      console.log('Response Envelope: \n' + envelope);
      //'result' is the response body
      console.log('Result: \n' + JSON.stringify(result));
    });
  });
});

The Request envelope created by above service invocation:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header/>
  <soap:Body>
    <ns1:GetQuote xmlns:ns1="http://www.webserviceX.NET/">
      <ns1:symbol>IBM</ns1:symbol>
    </ns1:GetQuote>
  </soap:Body>
</soap:Envelope>

This WSDL operation is defined as document/literal-wrapped style. Hence the request in soap is wrapped in operation name. Refer to test cases server-client-document-test and server-client-rpc-test to understand document and rpc styles and their Request, Response and Fault samples.

The options argument allows you to customize the client with the following properties:

  • endpoint: to override the SOAP service's host specified in the .wsdl file.
  • request: to override the request module.
  • httpClient: to provide your own http client that implements request(rurl, data, callback, exheaders, exoptions).
  • envelopeKey: to set specific key instead of
    <soap:Body>soap:Body>
  • wsdl_options: custom options for the request module on WSDL requests.
  • wsdl_headers: custom HTTP headers to be sent on WSDL requests.

Note: for versions of node >0.10.X, you may need to specify {connection: 'keep-alive'} in SOAP headers to avoid truncation of longer chunked responses.

Extra headers (optional)

User can define extra HTTP headers to be sent on the request.

var clientOptions = {};
soap.createClient(url, clientOptions, function(err, client) {
  var customRequestHeader = {customheader1: 'test1'};
  // Custom request header
  client.GetQuote(requestArgs, function(err, result, envelope) {
    // Result in SOAP envelope body which is the wrapper element.
    // In this case, result object corresponds to GetCityForecastByZIPResponse.
    console.log(JSON.stringify(result));
  }, null, customRequestHeader);
});

Client.describe()

Describes services, ports and methods as a JavaScript object.

// Describes the entire WSDL in a JSON tree object form.
var description = client.describe();
// Inspect GetQuote operation. You can inspect Service: {Port: {operation: {
console.log(JSON.stringify(description.StockQuote.StockQuoteSoap.GetQuote));

Client.setSecurity(security)

Use the specified security protocol.

Refer to test case ssl-test for an example of using this API.

Client.method(args, callback)

Call method on the SOAP service.

```js client.MyFunction({name: 'value'}, function(err, result, envelope, soapHeader) { // Result is a javascript objec