soap

What is soap?

The 'soap' npm package is a SOAP client and server library for Node.js. It allows you to create SOAP clients to consume web services and also create SOAP servers to expose your own web services.

What are soap's main functionalities?

Create a SOAP Client

This feature allows you to create a SOAP client that can consume a SOAP web service. You provide the WSDL URL, and the client can then call the web service methods.

const soap = require('soap');
const url = 'http://example.com/wsdl?wsdl';
soap.createClient(url, function(err, client) {
  if (err) throw err;
  client.MyFunction({name: 'value'}, function(err, result) {
    if (err) throw err;
    console.log(result);
  });
});

Create a SOAP Server

This feature allows you to create a SOAP server that exposes your own web service. You define the service and its methods, and provide the WSDL file.

const soap = require('soap');
const express = require('express');
const app = express();
const myService = {
  MyService: {
    MyPort: {
      MyFunction: function(args) {
        return { name: args.name };
      }
    }
  }
};
const xml = require('fs').readFileSync('myservice.wsdl', 'utf8');
soap.listen(app, '/wsdl', myService, xml);
app.listen(8000);

Handle SOAP Headers

This feature allows you to add custom SOAP headers to your SOAP client requests. This can be useful for authentication or other custom header requirements.

const soap = require('soap');
const url = 'http://example.com/wsdl?wsdl';
soap.createClient(url, function(err, client) {
  if (err) throw err;
  const soapHeader = { 'MyHeader': 'value' };
  client.addSoapHeader(soapHeader);
  client.MyFunction({name: 'value'}, function(err, result) {
    if (err) throw err;
    console.log(result);
  });
});

Other packages similar to soap

strong-soap

The 'strong-soap' package is another SOAP client and server library for Node.js. It is similar to 'soap' but offers additional features like better WSDL handling and support for more complex SOAP scenarios. It is maintained by the StrongLoop team.

easy-soap-request

The 'easy-soap-request' package is a lightweight SOAP client for Node.js. It focuses on simplicity and ease of use, making it a good choice for simple SOAP requests. However, it does not offer server-side capabilities like 'soap'.

node-soap-client

The 'node-soap-client' package is a minimalistic SOAP client for Node.js. It is designed to be easy to use and integrates well with modern JavaScript features like Promises and async/await. It is a good alternative if you only need client-side functionality.

README

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:

• 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 (currently only UsernameToken and PasswordText encoding is supported)

Install

Install with npm:

  npm install soap

Module

soap.createClient(url, callback) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.

  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);
      });
  });

soap.listen(server, path, services, wsdl) - create a new SOAP server that listens on path and provides services.

wsdl is an xml string that defines the service.

  var myService = {
      MyService: {
          MyPort: {
              MyFunction: function(args) {
                  return {
                      name: args.name
                  };
              }

              // This is how to define an asynchronous function.
              MyAsyncFunction: function(args, callback) {
                  // do some work
                  callback({
                      name: args.name
                  })
              }
          }
      }
  }

  var xml = require('fs').readFileSync('myservice.wsdl', 'utf8'),
      server = http.createServer(function(request,response) {
          response.end("404: Not Found: "+request.url)
      });

  server.listen(8000);
  soap.listen(server, '/wsdl', myService, xml);

server logging

If the log method is defined it will be called with 'received' and 'replied' along with data.

  server = soap.listen(...)
  server.log = function(type, data) {
    // type is 'received' or 'replied'
  };

server security example using PasswordDigest

If server.authenticate is not defined no authentation will take place.

  server = soap.listen(...)
  server.authenticate = function(security) {
    var created, nonce, password, user, token;
    token = security.UsernameToken, user = token.Username,
            password = token.Password, nonce = token.Nonce, created = token.Created;
    return user === 'user' && password === soap.passwordDigest(nonce, created, 'password');
  };

server connection authorization

This is called prior to soap service method If the method is defined and returns false the incoming connection is terminated.

  server = soap.listen(...)
  server.authorizeConnection = function(req) {
    return true; // or false
  };

Client

An instance of Client is passed to the soap.createClient callback. It is used to execute methods on the soap service.

Client.describe() - description of services, ports and methods as a JavaScript object

  client.describe() // returns
    {
      MyService: {
        MyPort: {
          MyFunction: {
            input: {
              name: 'string'
            }
          }
        }
      }
    }

Client.setSecurity(security) - use the specified security protocol

node-soap has several default security protocols. You can easily add your own as well. The interface is quite simple. Each protocol defines 2 methods:

• addOptions - a method that accepts an options arg that is eventually passed directly to request
• toXML - a method that reurns a string of XML.

By default there are 3 protocols:

####BasicAuthSecurity

  client.setSecurity(new soap.BasicAuthSecurity('username', 'password'));

####ClientSSLSecurity Note: If you run into issues using this protocol, consider passing these options as default request options to the constructor:

• rejectUnauthorized: false
• strictSSL: false
• secureOptions: constants.SSL_OP_NO_TLSv1_2//this is likely needed for node >= 10.0

  client.setSecurity(new soap.ClientSSLSecurity(
    '/path/to/key'
    , '/path/to/cert'
    , {/*default request options*/}
  ));

####WSSecurity

  client.setSecurity(new WSSecurity('username', 'password'))

Client.method(args, callback) - call method on the SOAP service.

  client.MyFunction({name: 'value'}, function(err, result) {
      // result is a javascript object
  })

Client.service.port.method(args, callback[, options]) - call a method using a specific service and port

  client.MyService.MyPort.MyFunction({name: 'value'}, function(err, result) {
      // result is a javascript object
  })

+#### Options (optional)

• Accepts any option that the request module accepts, see here.
• For example, you could set a timeout of 5 seconds on the request like this:

  client.MyService.MyPort.MyFunction({name: 'value'}, function(err, result) {
      // result is a javascript object
  }, {timeout: 5000})

Client.addSoapHeader(soapHeader[, name, namespace, xmlns]) - add soapHeader to soap:Header node

Options

• soapHeader Object({rootName: {name: "value"}}) or strict xml-string

Optional parameters when first arg is object :

• name Unknown parameter (it could just a empty string)
• namespace prefix of xml namespace
• xmlns URI

Client.lastRequest - the property that contains last full soap request for client logging

WSSecurity

WSSecurity implements WS-Security. UsernameToken and PasswordText/PasswordDigest is supported. An instance of WSSecurity is passed to Client.setSecurity.

  new WSSecurity(username, password, passwordType)
    //'PasswordDigest' or 'PasswordText' default is PasswordText