overridePromiseSuffix: if your wsdl operations contains names with Async suffix, you will need to override the default promise suffix to a custom one, default: Async.

normalizeNames: if your wsdl operations contains names with non identifier characters ([^a-z$_0-9]), replace them with _. Note: if using this option, clients using wsdls with two operations like soap:method and soap-method will be overwritten. Then, use bracket notation instead (client['soap:method']()).

namespaceArrayElements: provides support for nonstandard array semantics. If true, JSON arrays of the form {list: [{elem: 1}, {elem: 2}]} are marshalled into xml as <list><elem>1</elem></list> <list><elem>2</elem></list>. If false, marshalls into <list> <elem>1</elem> <elem>2</elem> </list>. Default: true.

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.

Server Events

request - Emitted for every received messages. The signature of the callback is function(request, methodName).

headers - Emitted when the SOAP Headers are not empty. The signature of the callback is function(headers, methodName).

The sequence order of the calls is request, headers and then the dedicated service method.

Server Response on one-way calls

The so called one-way (or asynchronous) calls occur when an operation is called with no output defined in WSDL. The server sends a response (defaults to status code 200 with no body) to the client disregarding the result of the operation.

You can configure the response to match the appropriate client expectation to the SOAP standard implementation. Pass in oneWay object in server options. Use the following keys: emptyBody: if true, returns an empty body, otherwise no content at all (default is false) responseCode: default statusCode is 200, override it with this options (for example 202 for SAP standard compliant response)

SOAP Fault

A service method can reply with a SOAP Fault to a client by throwing an object with a Fault property.

SOAP Headers

Received SOAP Headers

It is also possible to subscribe to the 'headers' event. The event is triggered before the service method is called, and only when the SOAP Headers are not empty.

server = soap.listen(...)
server.on('headers', function(headers, methodName) {
// It is possible to change the value of the headers
// before they are handed to the service method.
// It is also possible to throw a SOAP Fault
});

First parameter is the Headers object; second parameter is the name of the SOAP method that will called (in case you need to handle the headers differently based on the method).

Outgoing SOAP Headers

Both client & server can define SOAP headers that will be added to what they send. They provide the following methods to manage the headers.

Parameters

For servers only, soapHeader can be a function, which allows headers to be dynamically generated from information in the request. This function will be called with the following arguments for each received request:

methodName The name of the request method

args The arguments of the request

headers The headers in the request

req The original request object

The return value of the function must be an Object({rootName: {name: 'value'}}) or strict xml-string, which will be inserted as an outgoing header of the response to that request.

Note that the "Request" element in the output above comes from the WSDL. If an element in args contains no namespace prefix, the default namespace is assumed. Otherwise, you must add the namespace prefixes to the element names as necessary (e.g., ns1:name).

Currently, when supplying JSON args, elements may not contain both child elements and a text value, even though that is allowed in the XML specification.

Example with XML String for the args

You may pass in a fully-formed XML string instead the individual elements in JSON args and attributes that make up the XML. The XML string should not contain an XML declaration (e.g., <?xml version="1.0" encoding="UTF-8"?>) or a document type declaration (e.g., <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">).

You must specify all of the namespaces and namespace prefixes yourself. The element(s) from the WSDL are not utilized as they were in the "Example with JSON as the args" example above, which automatically populated the "Request" element.

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

Overriding the namespace prefix

node-soap is still working out some kinks regarding namespaces. If you find that an element is given the wrong namespace prefix in the request body, you can add the prefix to it's name in the containing object. I.E.:

client.MyService.MyPort.MyFunction({'ns1:name': 'value'}, function(err, result) {
// request body sent with `<ns1:name`, regardless of what the namespace should have been.
}, {timeout: 5000})

Remove namespace prefix of param

client.MyService.MyPort.MyFunction({':name': 'value'}, function(err, result) {
// request body sent with `<name`, regardless of what the namespace should have been.
}, {timeout: 5000})

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

Client.setEndpoint(url) - overwrite the SOAP service endpoint address

Client Events

Client instances emit the following events:

request

Emitted before a request is sent. The event handler has the signature (xml, eid).

xml - The entire Soap request (Envelope) including headers.

eid - The exchange id.

message

Emitted before a request is sent, but only the body is passed to the event handler. Useful if you don't want to log /store Soap headers. The event handler has the signature (message, eid).

message - Soap body contents.

eid - The exchange id.

soapError

Emitted when an erroneous response is received. Useful if you want to globally log errors. The event handler has the signature (error, eid).

error - An error object which also contains the resoponse.

eid - The exchange id.

response

Emitted after a response is received. This is emitted for all responses (both success and errors). The event handler has the signature (body, response, eid)

body - The SOAP response body.

response - The entire IncomingMessage response object.

eid - The exchange id.

An 'exchange' is a request/response couple. Event handlers receive the exchange id in all events. The exchange id is the same for the requests events and the responses events, this way you can use it to retrieve the matching request when an response event is received.

By default exchange ids are generated by using node-uuid but you can use options in client calls to pass your own exchange id.

Handling XML Attributes, Value and XML (wsdlOptions).

Sometimes it is necessary to override the default behaviour of node-soap in order to deal with the special requirements of your code base or a third library you use. Therefore you can use the wsdlOptions Object, which is passed in the #createClient() method and could have any (or all) of the following contents:

If nothing (or an empty Object {}) is passed to the #createClient() method, the node-soap defaults (attributesKey: 'attributes', valueKey: '$value' and xmlKey: '$xml') are used.

Overriding the value key

By default, node-soap uses $value as the key for any parsed XML value which may interfere with your other code as it could be some reserved word, or the $ in general cannot be used for a key to start with.

You can define your own valueKey by passing it in the wsdl_options to the createClient call:

Custom Deserializer

Sometimes it's useful to handle deserialization in your code instead of letting node-soap do it. For example if the soap response contains dates that are not in a format recognized by javascript, you might want to use your own function to handle them.

To do so, you can pass a customDeserializer object in options. The properties of this object are the types that your deserializer handles itself.

Changing the tag formats to use self-closing (empty element) tags

The XML specification specifies that there is no semantic difference between <Tag></Tag> and <Tag />, and node-soap defaults to using the <Tag></Tag> format. But if your web service is particular, or if there is a stylistic preference, the useEmptyTag option causes tags with no contents to use the <Tag /> format instead.

var wsdlOptions = {
useEmptyTag: true
};

For example: { MyTag: { attributes: { MyAttr: 'value' } } } is:

Without useEmptyTag: <MyTag MyAttr="value"></MyTag>

With useEmptyTag set to true: <MyTag MyAttr="value" />

Handling "ignored" namespaces

If an Element in a schema definition depends on an Element which is present in the same namespace, normally the tns: namespace prefix is used to identify this Element. This is not much of a problem as long as you have just one schema defined (inline or in a separate file). If there are more schema files, the tns: in the generated soap file resolved mostly to the parent wsdl file, which was obviously wrong.

node-soap now handles namespace prefixes which shouldn't be resolved (because it's not necessary) as so called ignoredNamespaces which default to an Array of 3 Strings (['tns', 'targetNamespace', 'typedNamespace']).

If this is not sufficient for your purpose you can easily add more namespace prefixes to this Array, or override it in its entirety by passing an ignoredNamespaces object within the options you pass in soap.createClient() method.

A simple ignoredNamespaces object, which only adds certain namespaces could look like this:

This would override the default ignoredNamespaces of the WSDL processor to ['namespaceToIgnore', 'someOtherNamespace']. (This shouldn't be necessary, anyways).

Handling "ignoreBaseNameSpaces" attribute

If an Element in a schema definition depends has a basenamespace defined but the request does not need that value, for example you have a "sentJob" with basenamespace "v20" but the request need only: <sendJob> set in the tree structure, you need to set the ignoreBaseNameSpaces to true. This is set because in a lot of workaround the wsdl structure is not correctly set or the webservice bring errors.

By default the attribute is set to true. An example to use:

A simple ignoredNamespaces object, which only adds certain namespaces could look like this:

var options = {
ignoredNamespaces: true
}

soap-stub

Unit testing services that use soap clients can be very cumbersome. In order to get around this you can use soap-stub in conjunction with sinon to stub soap with your clients.