node-soap

The soap module provides a simple API for connecting to web services using SOAP and running your own SOAP services. Key features include:

• Support for both RPC and Document schema types.
• Support for multiRef SOAP messages.
• Support for both synchronous and asynchronous method handlers.
• WS-Security UsernameToken Profile 1.0.
• Integration with Express-based web servers (can use body-parser middleware).

If server.authenticate is not defined, no authentication occurs. You can implement either synchronous or asynchronous authentication.

Asynchronous Authentication: Pass a callback that receives a boolean indicating success.

Synchronous Authentication: Return a boolean directly.

If node-soap assigns an incorrect namespace prefix, you can manually specify it by including the prefix in the object key, or remove it by prefixing the key with a colon.

• To force a prefix: { 'ns1:name': 'value' }
• To remove a prefix: { ':name': 'value' }

client.MyService.MyPort.MyFunction(
  { 'ns1:name': 'value' },
  function (err, result) { /* ... */ },
  { timeout: 5000 },
);

Install the soap package using npm to use the SOAP client and server in your Node.js application.

npm install soap

By default, node-soap uses attributes to define a node's attributes. If your system requires a literal node named attributes, you can change this by passing attributesKey in the wsdl_options object.

var wsdlOptions = {
  attributesKey: '$attributes',
};

soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
  client.method({
    parentnode: {
      childnode: {
        $attributes: {
          name: 'childsname',
        },
        $value: 'Value',
      },
    },
  });
});

If a schema definition has a basenamespace that is not required in the actual request, you can set ignoredNamespaces: true in the options object to ignore it.

var options = {
  ignoredNamespaces: true
};

One-way calls occur when an operation has no output defined in the WSDL. By default, the server sends a 200 status code with no body. You can customize this using the oneWay object in the server options:

• emptyBody: If true, returns an empty body. If false (default), returns no content at all.
• responseCode: Overrides the default 200 status code (e.g., set to 202 for SAP compliance).

To precisely control the namespace definitions included in the root element, use the overrideRootElement key in wsdlOptions. This allows you to define the namespace and an array of xmlnsAttributes.

var wsdlOptions = {
  overrideRootElement: {
    namespace: 'xmlns:tns',
    xmlnsAttributes: [
      {
        name: 'xmlns:ns2',
        value: 'http://tempuri.org/',
      },
      {
        name: 'xmlns:ns3',
        value: 'http://sillypets.com/xsd',
      },
    ],
  },
};

Use the wsdlOptions object in the createClient method to override how node-soap handles XML attributes, values, and raw XML. This is useful if the default keys interfere with your codebase.

Default values:

• attributesKey: 'attributes'
• valueKey: '$value'
• xmlKey: '$xml'

var wsdlOptions = {
  attributesKey: 'theAttrs',
  valueKey: 'theVal',
  xmlKey: 'theXml',
};

// Example: Overriding the value key
var wsdlOptions = {
  valueKey: 'theVal',
};

soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
  // your code
});

If an external implementation does not match the WSDL spec exactly, you can map WSDL element names to different XML keys in requests or responses using overrideElementKey in wsdlOptions.

var wsdlOptions = {
  overrideElementKey: {
    Nom: 'Name',
    Commande: 'Order',
    SillyResponse: 'DummyResponse'
  };
};

By default, node-soap uses $xml as the key to pass through an XML string as-is, bypassing parsing and namespacing. You can customize this key by providing xmlKey in the wsdl_options object when calling createClient.

var wsdlOptions = {
  xmlKey: 'theXml',
};

soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
  // your code
});

To manage how node-soap handles namespace prefixes (like tns:) that shouldn't be resolved, use the ignoredNamespaces option within the options object passed to createClient.

• To add namespaces: Pass { namespaces: ['name1', 'name2'] } to extend the defaults.
• To override defaults entirely: Pass { namespaces: ['name1'], override: true }.

// Extend default ignored namespaces
var options = {
  ignoredNamespaces: {
    namespaces: ['namespaceToIgnore', 'someOtherNamespace']
  }
};

// Override default ignored namespaces completely
var options = {
    ignoredNamespaces: {
      namespaces: ['namespaceToIgnore', 'someOtherNamespace'],
      override: true
    }
};