[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Coveralls Status][coveralls-image]][coveralls-url]

[![Support][buy-me-a-coffee-image]][buy-me-a-coffee-url]

Sponsors

Travel Axis is proud to support this project by contributing engineering resources.
The company is building Helix, a SaaS platform designed to transform the travel management industry.

SOAP client and server for node.js.

This module lets you connect to web services using SOAP. It also provides a server that allows you to run your own SOAP services.

• Features
• Install
• Support
• Module
• soap
  • createClient(url[, options], callback)
  • createClientAsync(url[, options])
  • listen(server, path, services, wsdl, callback)
  • listen(server, options)
  • createServerless(options)
• Server Logging
• Server Events
• Server Response on one-way calls
• SOAP Fault
• Server security example using PasswordDigest
• Server connection authorization
• SOAP Headers
• Received SOAP Headers
• Outgoing SOAP Headers
  • addSoapHeader(soapHeader[, name, namespace, xmlns])
  • changeSoapHeader(index, soapHeader[, name, namespace, xmlns])
  • getSoapHeaders()
  • clearSoapHeaders()
• Client
• describe()
• setSecurity(security)
• method(args, callback, options)
• methodAsync(args, options)
• service.port.method(args, callback[, options[, extraHeaders]])
  • Options (optional)
  • Extra Headers (optional)
  • Alternative method call using callback-last pattern
• Overriding the namespace prefix
• lastRequest
• setEndpoint(url)
• Client Events
  • request
  • message
  • soapError
  • response
• WSDL
• Constructor(wsdl, baseURL, options)
  • Parameters
• xmlToObject(xml)
  • Parameters:
  • Returns:
• objectToXML(object, typeName, namespacePrefix, namespaceURI, ...)
  • Parameters:
  • Returns:
• Security
• BasicAuthSecurity
• BearerSecurity
• ClientSSLSecurity
• ClientSSLSecurityPFX
• WSSecurity
• WSSecurityCert
• WSSecurityPlusCert
  • Option examples
• WSSecurityCertWithToken
• NTLMSecurity
• Handling XML Attributes, Value and XML (wsdlOptions).
• Overriding the value key
• Overriding the xml key
• Overriding the attributes key
• Overriding imports relative paths
• Overriding import locations
• Specifying the exact namespace definition of the root element
• Overriding element key specification in XML
• Custom Deserializer
• Changing the tag formats to use self-closing (empty element) tags
• Handling "ignored" namespaces
• Handling "ignoreBaseNameSpaces" attribute
• Contributors

Features

• Very simple API
• Handles both RPC and Document schema types
• Supports multiRef SOAP messages (thanks to @kaven276)
• Support for both synchronous and asynchronous method handlers
• WS-Security UsernameToken Profile 1.0
• Supports Express based web server (body parser middleware can be used)

Install

  npm install soap

Support

Community support is available through GitHub issues tab. Paid support can be provided as well, please contact one of the active maintainers.

Module

soap

createClient(url[, options], callback)

Creates a new SOAP client from a WSDL URL. Also supports a local filesystem path.

• url (string): A HTTP/HTTPS URL, XML or a local filesystem path.
• options (Object):
• endpoint (string): Override the host specified by the SOAP service in the WSDL file.
• envelopeKey (string): Set a custom envelope key. (Default: 'soap')
• preserveWhitespace (boolean): Preserve any leading and trailing whitespace characters in text and cdata.
• escapeXML (boolean): Escape special XML characters (e.g. &, >, < etc) in SOAP messages. (Default: true)
• suppressStack (boolean): Suppress the full stack trace for error messages.
• returnFault (boolean): Return an Invalid XML SOAP fault upon a bad request. (Default: false)
• forceSoap12Headers (boolean): Enable SOAP 1.2 compliance.
• httpClient (Object): Override the built-in HttpClient object with your own. Must implement request(rurl, data, callback, exheaders, exoptions).
• request (Object): Override the default request module (Axios as of v0.40.0).
• wsdl_headers (Object): Set HTTP headers with values to be sent on WSDL requests.
• wsdl_options (Object): Set options for the request module on WSDL requests. If using the default request module, see Request Config | Axios Docs.
• disableCache (boolean): Prevents caching WSDL files and option objects.
• wsdlCache (IWSDLCache): Custom cache implementation. If not provided, defaults to caching WSDLs indefinitely.
• overridePromiseSuffix (string): Override the default method name suffix of WSDL operations for Promise-based methods. If any WSDL operation name ends with Async', you must use this option. (**Default:**Async`)
• normalizeNames (boolean): Replace non-identifier characters ([^a-z$_0-9]) with _ in WSDL operation names. Note: Clients using WSDLs with two operations like soap:method and soap-method will be overwritten. In this case, you must use bracket notation instead (client['soap:method']()).
• namespaceArrayElements (boolean): Support non-standard array semantics. JSON arrays of the form {list: [{elem: 1}, {elem: 2}]} will be marshalled into XML as <list><elem>1</elem></list> <list><elem>2</elem></list>. If false, it would be marshalled into <list> <elem>1</elem> <elem>2</elem> </list>. (Default: true)
• stream (boolean): Use streams to parse the XML SOAP responses. (Default: false)
• returnSaxStream (boolean): Return the SAX stream, transferring responsibility of parsing XML to the end user. Only valid when the stream option is set to true. (Default: false)
• parseReponseAttachments (boolean): Treat response as multipart/related response with MTOM attachment. Reach attachments on the lastResponseAttachments property of SoapClient. (Default: false)
• encoding (string): Response data enconding, used with parseReponseAttachments. (Default: utf8)
• forceUseSchemaXmlns (boolean): Force to use schema xmlns when schema prefix not found, this is needed when schema prefix is different for the same namespace in different files, for example wsdl and in imported xsd file fir complex types (Default false)
• callback (Function):
• err (Error | \<AggregateError>)
• result (Any)
• Returns: Client

Example

HTTP/HTTPS:

var soap = require('soap');
var url = 'http://example.com/wsdl?wsdl';
var args = { name: 'value' };

soap.createClient(url, {}, function (err, client) {
  client.MyFunction(args, function (err, result) {
    console.log(result);
  });
});

XML string format:

var soap = require('soap');
var xml = `
    <?xml version="1.0" encoding="UTF-8"?>
    <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
       <message name="MyFunctionRequest"/>
       <message name="MyFunctionResponse"/>

       <portType name="MyFunctionPortType">
          <operation name="MyFunction">
             <input message="MyFunctionRequest"/>
             <output message="MyFunctionResponse"/>
          </operation>
       </portType>

       <binding name="MyFunctionBinding" type="MyFunctionPortType">
          <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
          <operation name="MyFunction">
             <soap:operation soapAction="MyFunction"/>
             <input><soap:body use="encoded"/></input>
             <output><soap:body use="encoded"/></output>
          </operation>
       </binding>

       <service name="MyService">
          <port binding="MyFunctionBinding" name="MyFunctionPort">
             <soap:address location="http://www.examples.com/MyFunction/" />
          </port>
       </service>
    </definitions>
  `;
var args = { name: 'value' };

soap.createClient(xml, {}, function (err, client) {
  client.MyFunction(args, function (err, result) {
    console.log(result);
  });
});

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.

createClientAsync(url[, options])

Creates a new SOAP client from a WSDL URL. Also supports a local filesystem path.

Construct a Promise<Client> with the given WSDL file.

• url (string): A HTTP/HTTPS URL, XML or a local filesystem path.
• options (Object): See createClient(url[, options], callback) for a description.
• Returns: Promise<Client>

Example

var soap = require('soap');
var url = 'http://example.com/wsdl?wsdl';
var args = { name: 'value' };

// then/catch
soap
  .createClientAsync(url)
  .then((client) => {
    return client.MyFunctionAsync(args);
  })
  .then((result) => {
    console.log(result);
  });

// async/await
var client = await soap.createClientAsync(url);
var result = await client.MyFunctionAsync(args);
console.log(result[0]);

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.

listen(server, path, services, wsdl, callback)

Creates a new SOAP server that listens on path and provides services.

listen(server, options)

Creates a new SOAP server that listens on path and provides services.

• server (Object): A http server or Express framework based server.
• path (string)
• options (Object): An object containing server options and WSDL Options
• path (string)
• services (Object)
• xml (string)
• uri (string)
• pfx (string | Buffer): The private key, certificate and CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with the key, cert and ca options.)
• key (string | Buffer): The private key of the server in PEM format. (Could be an array of keys). (Required)
• passphrase (string): The passphrase for the private key or pfx.
• cert (string | Buffer): The certificate key of the server in PEM format. (Could be an array of certs). (Required)
• ca (string[] | Buffer[]): Trusted certificates in PEM format. If this is omitted several well known "root" CAs will be used, like VeriSign. These are used to authorize connections.
• crl (string | string[]: PEM encoded CRLs (Certificate Revocation List)
• ciphers (string): A description of the ciphers to use or exclude, separated by :. The default cipher suite is:
• enableChunkedEncoding (boolean): Controls chunked transfer encoding in response. Some clients (such as Windows 10's MDM enrollment SOAP client) are sensitive to transfer-encoding mode and can't accept chunked response. This option lets users disable chunked transfer encoding for such clients. (Default: true)
• services (Object)
• wsdl (string): An XML string that defines the service.
• callback (Function): A function to run after the server has been initialized.
• Returns: Server

Example

```javascript var myService = { MyService: { MyPort: {