soap 1.1.12 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Readme.md +654 -505
- package/lib/http.js +2 -2
- package/lib/http.js.map +1 -1
- package/lib/security/WSSecurityCert.js +1 -1
- package/lib/security/WSSecurityCert.js.map +1 -1
- package/lib/types.d.ts +2 -0
- package/lib/wsdl/elements.js +15 -2
- package/lib/wsdl/elements.js.map +1 -1
- package/package.json +3 -3
package/Readme.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
|
|
1
|
+
[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Coveralls Status][coveralls-image]][coveralls-url]
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[![Support][buy-me-a-coffee-image]][buy-me-a-coffee-url]
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
# SOAP client and server for node.js.
|
|
6
|
+
|
|
7
|
+
This module lets you connect to web services using SOAP. It also provides a server that allows you to run your own SOAP services.
|
|
6
8
|
|
|
7
9
|
<!-- Run `npm run toc` to update below section -->
|
|
8
10
|
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
@@ -14,8 +16,8 @@ This module lets you connect to web services using SOAP. It also provides a ser
|
|
|
14
16
|
- [Module](#module)
|
|
15
17
|
- [soap.createClient(url[, options], callback) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.](#soapcreateclienturl-options-callback---create-a-new-soap-client-from-a-wsdl-url-also-supports-a-local-filesystem-path)
|
|
16
18
|
- [soap.createClientAsync(url[, options]) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.](#soapcreateclientasyncurl-options---create-a-new-soap-client-from-a-wsdl-url-also-supports-a-local-filesystem-path)
|
|
17
|
-
- [soap.listen(
|
|
18
|
-
- [soap.listen(
|
|
19
|
+
- [soap.listen(_server_, _path_, _services_, _wsdl_, _callback_) - create a new SOAP server that listens on _path_ and provides _services_.](#soaplistenserver-path-services-wsdl-callback---create-a-new-soap-server-that-listens-on-path-and-provides-services)
|
|
20
|
+
- [soap.listen(_server_, _options_) - create a new SOAP server that listens on _path_ and provides _services_.](#soaplistenserver-options---create-a-new-soap-server-that-listens-on-path-and-provides-services)
|
|
19
21
|
- [Server Logging](#server-logging)
|
|
20
22
|
- [Server Events](#server-events)
|
|
21
23
|
- [Server Response on one-way calls](#server-response-on-one-way-calls)
|
|
@@ -28,11 +30,11 @@ This module lets you connect to web services using SOAP. It also provides a ser
|
|
|
28
30
|
- [Client](#client)
|
|
29
31
|
- [Client.describe() - description of services, ports and methods as a JavaScript object](#clientdescribe---description-of-services-ports-and-methods-as-a-javascript-object)
|
|
30
32
|
- [Client.setSecurity(security) - use the specified security protocol](#clientsetsecuritysecurity---use-the-specified-security-protocol)
|
|
31
|
-
- [Client
|
|
32
|
-
- [Client.*method*Async(args, options) - call
|
|
33
|
-
- [Client
|
|
33
|
+
- [Client._method_(args, callback, options) - call _method_ on the SOAP service.](#clientmethodargs-callback-options---call-method-on-the-soap-service)
|
|
34
|
+
- [Client.*method*Async(args, options) - call _method_ on the SOAP service.](#clientmethodasyncargs-options---call-method-on-the-soap-service)
|
|
35
|
+
- [Client._service_._port_._method_(args, callback[, options[, extraHeaders]]) - call a _method_ using a specific _service_ and _port_](#clientserviceportmethodargs-callback-options-extraheaders---call-a-method-using-a-specific-service-and-port)
|
|
34
36
|
- [Overriding the namespace prefix](#overriding-the-namespace-prefix)
|
|
35
|
-
- [Client
|
|
37
|
+
- [Client._lastRequest_ - the property that contains last full soap request for client logging](#clientlastrequest---the-property-that-contains-last-full-soap-request-for-client-logging)
|
|
36
38
|
- [Client.setEndpoint(url) - overwrite the SOAP service endpoint address](#clientsetendpointurl---overwrite-the-soap-service-endpoint-address)
|
|
37
39
|
- [Client Events](#client-events)
|
|
38
40
|
- [_request_](#_request_)
|
|
@@ -72,12 +74,12 @@ This module lets you connect to web services using SOAP. It also provides a ser
|
|
|
72
74
|
|
|
73
75
|
## Features:
|
|
74
76
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
77
|
+
- Very simple API
|
|
78
|
+
- Handles both RPC and Document schema types
|
|
79
|
+
- Supports multiRef SOAP messages (thanks to [@kaven276](https://github.com/kaven276))
|
|
80
|
+
- Support for both synchronous and asynchronous method handlers
|
|
81
|
+
- WS-Security UsernameToken Profile 1.0
|
|
82
|
+
- Supports [Express](http://expressjs.com/) based web server (body parser middleware can be used)
|
|
81
83
|
|
|
82
84
|
## Install
|
|
83
85
|
|
|
@@ -94,51 +96,54 @@ Paid support can be provided as well, please contact one of the active maintaine
|
|
|
94
96
|
|
|
95
97
|
### soap.createClient(url[, options], callback) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.
|
|
96
98
|
|
|
97
|
-
- `url` (
|
|
98
|
-
- `options` (
|
|
99
|
-
- `endpoint` (
|
|
100
|
-
- `envelopeKey` (
|
|
101
|
-
- `preserveWhitespace` (
|
|
102
|
-
- `escapeXML` (
|
|
103
|
-
- `suppressStack` (
|
|
104
|
-
- `returnFault` (
|
|
105
|
-
- `forceSoap12Headers` (
|
|
106
|
-
- `httpClient` (
|
|
107
|
-
- `request` (
|
|
108
|
-
- `wsdl_headers` (
|
|
109
|
-
- `wsdl_options` (
|
|
110
|
-
- `disableCache` (
|
|
111
|
-
- `wsdlCache` (
|
|
112
|
-
- `overridePromiseSuffix` (
|
|
113
|
-
- `normalizeNames` (
|
|
114
|
-
- `namespaceArrayElements` (
|
|
115
|
-
- `stream` (
|
|
116
|
-
- `returnSaxStream` (
|
|
117
|
-
- `parseReponseAttachments` (
|
|
118
|
-
- `
|
|
119
|
-
|
|
120
|
-
- `
|
|
99
|
+
- `url` (_string_): A HTTP/HTTPS URL, XML or a local filesystem path.
|
|
100
|
+
- `options` (_Object_):
|
|
101
|
+
- `endpoint` (_string_): Override the host specified by the SOAP service in the WSDL file.
|
|
102
|
+
- `envelopeKey` (_string_): Set a custom envelope key. (**Default:** `'soap'`)
|
|
103
|
+
- `preserveWhitespace` (_boolean_): Preserve any leading and trailing whitespace characters in text and cdata.
|
|
104
|
+
- `escapeXML` (_boolean_): Escape special XML characters (e.g. `&`, `>`, `<` etc) in SOAP messages. (**Default:** `true`)
|
|
105
|
+
- `suppressStack` (_boolean_): Suppress the full stack trace for error messages.
|
|
106
|
+
- `returnFault` (_boolean_): Return an `Invalid XML` SOAP fault upon a bad request. (**Default:** `false`)
|
|
107
|
+
- `forceSoap12Headers` (_boolean_): Enable SOAP 1.2 compliance.
|
|
108
|
+
- `httpClient` (_Object_): Override the built-in HttpClient object with your own. Must implement `request(rurl, data, callback, exheaders, exoptions)`.
|
|
109
|
+
- `request` (_Object_): Override the default request module ([Axios](https://axios-http.com/) as of `v0.40.0`).
|
|
110
|
+
- `wsdl_headers` (_Object_): Set HTTP headers with values to be sent on WSDL requests.
|
|
111
|
+
- `wsdl_options` (_Object_): Set options for the request module on WSDL requests. If using the default request module, see [Request Config | Axios Docs](https://axios-http.com/docs/req_config).
|
|
112
|
+
- `disableCache` (_boolean_): Prevents caching WSDL files and option objects.
|
|
113
|
+
- `wsdlCache` (_IWSDLCache_): Custom cache implementation. If not provided, defaults to caching WSDLs indefinitely.
|
|
114
|
+
- `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`)
|
|
115
|
+
- `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']()`).
|
|
116
|
+
- `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`)
|
|
117
|
+
- `stream` (_boolean_): Use streams to parse the XML SOAP responses. (**Default:** `false`)
|
|
118
|
+
- `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`)
|
|
119
|
+
- `parseReponseAttachments` (_boolean_): Treat response as multipart/related response with MTOM attachment. Reach attachments on the `lastResponseAttachments` property of SoapClient. (**Default:** `false`)
|
|
120
|
+
- `encoding` (_string_): response data enconding, used with `parseReponseAttachments`. (**Default:** `utf8`)
|
|
121
|
+
- `callback` (_Function_):
|
|
122
|
+
- `err` (_Error_ | _<AggregateError>_)
|
|
123
|
+
- `result` (_Any_)
|
|
121
124
|
- Returns: `Client`
|
|
122
125
|
|
|
123
126
|
#### Example
|
|
124
127
|
|
|
125
128
|
HTTP/HTTPS:
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
129
|
+
|
|
130
|
+
```javascript
|
|
131
|
+
var soap = require("soap");
|
|
132
|
+
var url = "http://example.com/wsdl?wsdl";
|
|
133
|
+
var args = { name: "value" };
|
|
134
|
+
|
|
135
|
+
soap.createClient(url, {}, function (err, client) {
|
|
136
|
+
client.MyFunction(args, function (err, result) {
|
|
137
|
+
console.log(result);
|
|
135
138
|
});
|
|
139
|
+
});
|
|
136
140
|
```
|
|
137
141
|
|
|
138
142
|
XML string format:
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
143
|
+
|
|
144
|
+
```javascript
|
|
145
|
+
var soap = require("soap");
|
|
146
|
+
var xml = `
|
|
142
147
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
143
148
|
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
|
|
144
149
|
<message name="MyFunctionRequest"/>
|
|
@@ -167,169 +172,182 @@ XML string format:
|
|
|
167
172
|
</service>
|
|
168
173
|
</definitions>
|
|
169
174
|
`;
|
|
170
|
-
|
|
175
|
+
var args = { name: "value" };
|
|
171
176
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
});
|
|
177
|
+
soap.createClient(xml, {}, function (err, client) {
|
|
178
|
+
client.MyFunction(args, function (err, result) {
|
|
179
|
+
console.log(result);
|
|
176
180
|
});
|
|
181
|
+
});
|
|
177
182
|
```
|
|
178
183
|
|
|
179
|
-
|
|
180
184
|
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.
|
|
181
185
|
|
|
182
186
|
### soap.createClientAsync(url[, options]) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.
|
|
183
187
|
|
|
184
188
|
Construct a `Promise<Client>` with the given WSDL file.
|
|
185
189
|
|
|
186
|
-
- `url` (
|
|
187
|
-
- `options` (
|
|
190
|
+
- `url` (_string_): A HTTP/HTTPS URL, XML or a local filesystem path.
|
|
191
|
+
- `options` (_Object_): See [soap.createClient(url[, options], callback)](#soapcreateclienturl-options-callback---create-a-new-soap-client-from-a-wsdl-url-also-supports-a-local-filesystem-path) for a description.
|
|
188
192
|
- Returns: `Promise<Client>`
|
|
189
193
|
|
|
190
194
|
#### Example
|
|
191
195
|
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
196
|
+
```javascript
|
|
197
|
+
var soap = require("soap");
|
|
198
|
+
var url = "http://example.com/wsdl?wsdl";
|
|
199
|
+
var args = { name: "value" };
|
|
200
|
+
|
|
201
|
+
// then/catch
|
|
202
|
+
soap
|
|
203
|
+
.createClientAsync(url)
|
|
204
|
+
.then((client) => {
|
|
199
205
|
return client.MyFunctionAsync(args);
|
|
200
|
-
})
|
|
206
|
+
})
|
|
207
|
+
.then((result) => {
|
|
201
208
|
console.log(result);
|
|
202
209
|
});
|
|
203
210
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
211
|
+
// async/await
|
|
212
|
+
var client = await soap.createClientAsync(url);
|
|
213
|
+
var result = await client.MyFunctionAsync(args);
|
|
214
|
+
console.log(result[0]);
|
|
208
215
|
```
|
|
209
216
|
|
|
210
217
|
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.
|
|
211
218
|
|
|
212
|
-
### soap.listen(
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
- `
|
|
217
|
-
- `
|
|
218
|
-
|
|
219
|
-
- `
|
|
220
|
-
- `
|
|
221
|
-
- `
|
|
222
|
-
- `
|
|
223
|
-
- `
|
|
224
|
-
- `
|
|
225
|
-
- `
|
|
226
|
-
- `
|
|
227
|
-
- `
|
|
228
|
-
- `
|
|
229
|
-
- `
|
|
230
|
-
- `
|
|
231
|
-
- `
|
|
232
|
-
- `
|
|
219
|
+
### soap.listen(_server_, _path_, _services_, _wsdl_, _callback_) - create a new SOAP server that listens on _path_ and provides _services_.
|
|
220
|
+
|
|
221
|
+
### soap.listen(_server_, _options_) - create a new SOAP server that listens on _path_ and provides _services_.
|
|
222
|
+
|
|
223
|
+
- `server` (_Object_): A [http](https://nodejs.org/api/http.html) server or [Express](http://expressjs.com/) framework based server.
|
|
224
|
+
- `path` (_string_)
|
|
225
|
+
- `options` (_Object_): An object containing _server options_ and [WSDL Options](#handling-xml-attributes-value-and-xml-wsdloptions)
|
|
226
|
+
- `path` (_string_)
|
|
227
|
+
- `services` (_Object_)
|
|
228
|
+
- `xml` (_string_)
|
|
229
|
+
- `uri` (_string_)
|
|
230
|
+
- `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.)
|
|
231
|
+
- `key` (_string_ | _Buffer_): The private key of the server in PEM format. (Could be an array of keys). (Required)
|
|
232
|
+
- `passphrase` (_string_): The passphrase for the private key or pfx.
|
|
233
|
+
- `cert` (_string_ | _Buffer_): The certificate key of the server in PEM format. (Could be an array of certs). (Required)
|
|
234
|
+
- `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.
|
|
235
|
+
- `crl` (_string_ | _string[]_: PEM encoded CRLs (Certificate Revocation List)
|
|
236
|
+
- `ciphers` (_string_): A description of the ciphers to use or exclude, separated by `:`. The default cipher suite is:
|
|
237
|
+
- `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`)
|
|
238
|
+
- `services` (_Object_)
|
|
239
|
+
- `wsdl` (_string_): An XML string that defines the service.
|
|
240
|
+
- `callback` (_Function_): A function to run after the server has been initialized.
|
|
233
241
|
- Returns: `Server`
|
|
234
242
|
|
|
235
243
|
#### Example
|
|
236
244
|
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
// This is how to define an asynchronous function with a callback.
|
|
248
|
-
MyAsyncFunction: function(args, callback) {
|
|
249
|
-
// do some work
|
|
250
|
-
callback({
|
|
251
|
-
name: args.name
|
|
252
|
-
});
|
|
253
|
-
},
|
|
254
|
-
|
|
255
|
-
// This is how to define an asynchronous function with a Promise.
|
|
256
|
-
MyPromiseFunction: function(args) {
|
|
257
|
-
return new Promise((resolve) => {
|
|
258
|
-
// do some work
|
|
259
|
-
resolve({
|
|
260
|
-
name: args.name
|
|
261
|
-
});
|
|
262
|
-
});
|
|
263
|
-
},
|
|
264
|
-
|
|
265
|
-
// This is how to receive incoming headers
|
|
266
|
-
HeadersAwareFunction: function(args, cb, headers) {
|
|
267
|
-
return {
|
|
268
|
-
name: headers.Token
|
|
269
|
-
};
|
|
270
|
-
},
|
|
271
|
-
|
|
272
|
-
// You can also inspect the original `req`
|
|
273
|
-
reallyDetailedFunction: function(args, cb, headers, req) {
|
|
274
|
-
console.log('SOAP `reallyDetailedFunction` request from ' + req.connection.remoteAddress);
|
|
275
|
-
return {
|
|
276
|
-
name: headers.Token
|
|
277
|
-
};
|
|
278
|
-
}
|
|
279
|
-
}
|
|
280
|
-
}
|
|
281
|
-
};
|
|
245
|
+
```javascript
|
|
246
|
+
var myService = {
|
|
247
|
+
MyService: {
|
|
248
|
+
MyPort: {
|
|
249
|
+
MyFunction: function (args) {
|
|
250
|
+
return {
|
|
251
|
+
name: args.name,
|
|
252
|
+
};
|
|
253
|
+
},
|
|
282
254
|
|
|
283
|
-
|
|
255
|
+
// This is how to define an asynchronous function with a callback.
|
|
256
|
+
MyAsyncFunction: function (args, callback) {
|
|
257
|
+
// do some work
|
|
258
|
+
callback({
|
|
259
|
+
name: args.name,
|
|
260
|
+
});
|
|
261
|
+
},
|
|
284
262
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
263
|
+
// This is how to define an asynchronous function with a Promise.
|
|
264
|
+
MyPromiseFunction: function (args) {
|
|
265
|
+
return new Promise((resolve) => {
|
|
266
|
+
// do some work
|
|
267
|
+
resolve({
|
|
268
|
+
name: args.name,
|
|
269
|
+
});
|
|
270
|
+
});
|
|
271
|
+
},
|
|
289
272
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
273
|
+
// This is how to receive incoming headers
|
|
274
|
+
HeadersAwareFunction: function (args, cb, headers) {
|
|
275
|
+
return {
|
|
276
|
+
name: headers.Token,
|
|
277
|
+
};
|
|
278
|
+
},
|
|
294
279
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
}
|
|
305
|
-
|
|
280
|
+
// You can also inspect the original `req`
|
|
281
|
+
reallyDetailedFunction: function (args, cb, headers, req) {
|
|
282
|
+
console.log(
|
|
283
|
+
"SOAP `reallyDetailedFunction` request from " +
|
|
284
|
+
req.connection.remoteAddress
|
|
285
|
+
);
|
|
286
|
+
return {
|
|
287
|
+
name: headers.Token,
|
|
288
|
+
};
|
|
289
|
+
},
|
|
290
|
+
},
|
|
291
|
+
},
|
|
292
|
+
};
|
|
293
|
+
|
|
294
|
+
var xml = require("fs").readFileSync("myservice.wsdl", "utf8");
|
|
306
295
|
|
|
296
|
+
//http server example
|
|
297
|
+
var server = http.createServer(function (request, response) {
|
|
298
|
+
response.end("404: Not Found: " + request.url);
|
|
299
|
+
});
|
|
300
|
+
|
|
301
|
+
server.listen(8000);
|
|
302
|
+
soap.listen(server, "/wsdl", myService, xml, function () {
|
|
303
|
+
console.log("server initialized");
|
|
304
|
+
});
|
|
305
|
+
|
|
306
|
+
//express server example
|
|
307
|
+
var app = express();
|
|
308
|
+
//body parser middleware are supported (optional)
|
|
309
|
+
app.use(
|
|
310
|
+
bodyParser.raw({
|
|
311
|
+
type: function () {
|
|
312
|
+
return true;
|
|
313
|
+
},
|
|
314
|
+
limit: "5mb",
|
|
315
|
+
})
|
|
316
|
+
);
|
|
317
|
+
app.listen(8001, function () {
|
|
318
|
+
//Note: /wsdl route will be handled by soap module
|
|
319
|
+
//and all other routes & middleware will continue to work
|
|
320
|
+
soap.listen(app, "/wsdl", myService, xml, function () {
|
|
321
|
+
console.log("server initialized");
|
|
322
|
+
});
|
|
323
|
+
});
|
|
307
324
|
```
|
|
308
325
|
|
|
309
|
-
```
|
|
310
|
-
var xml = require(
|
|
326
|
+
```javascript
|
|
327
|
+
var xml = require("fs").readFileSync("myservice.wsdl", "utf8");
|
|
311
328
|
|
|
312
329
|
soap.listen(server, {
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
330
|
+
// Server options.
|
|
331
|
+
path: "/wsdl",
|
|
332
|
+
services: myService,
|
|
333
|
+
xml: xml,
|
|
334
|
+
|
|
335
|
+
// WSDL options.
|
|
336
|
+
attributesKey: "theAttrs",
|
|
337
|
+
valueKey: "theVal",
|
|
338
|
+
xmlKey: "theXml",
|
|
322
339
|
});
|
|
323
340
|
```
|
|
324
341
|
|
|
325
342
|
### Server Logging
|
|
326
343
|
|
|
327
344
|
If the `log` method is defined, it will be called with:
|
|
345
|
+
|
|
328
346
|
- `type`: 'received', 'replied', 'info' or 'error'.
|
|
329
347
|
- `data`: The data to be logged which will be an XML for 'received' and 'replied' or a message for the other types.
|
|
330
348
|
- `req`: The original request object
|
|
331
349
|
|
|
332
|
-
```
|
|
350
|
+
```javascript
|
|
333
351
|
server = soap.listen(...)
|
|
334
352
|
server.log = function(type, data, req) {
|
|
335
353
|
// type is 'received', 'replied', 'info' or 'error'
|
|
@@ -340,11 +358,11 @@ If the `log` method is defined, it will be called with:
|
|
|
340
358
|
|
|
341
359
|
Server instances emit the following events:
|
|
342
360
|
|
|
343
|
-
|
|
361
|
+
- request - Emitted for every received messages.
|
|
344
362
|
The signature of the callback is `function(request, methodName)`.
|
|
345
|
-
|
|
363
|
+
- response - Emitted before sending SOAP response.
|
|
346
364
|
The signature of the callback is `function(response, methodName)`.
|
|
347
|
-
|
|
365
|
+
- headers - Emitted when the SOAP Headers are not empty.
|
|
348
366
|
The signature of the callback is `function(headers, methodName)`.
|
|
349
367
|
|
|
350
368
|
The sequence order of the calls is `request`, `headers` and then the dedicated
|
|
@@ -365,31 +383,31 @@ Pass in `oneWay` object in server options. Use the following keys:
|
|
|
365
383
|
A service method can reply with a SOAP Fault to a client by `throw`ing an
|
|
366
384
|
object with a `Fault` property.
|
|
367
385
|
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
386
|
+
```javascript
|
|
387
|
+
throw {
|
|
388
|
+
Fault: {
|
|
389
|
+
Code: {
|
|
390
|
+
Value: "soap:Sender",
|
|
391
|
+
Subcode: { value: "rpc:BadArguments" },
|
|
392
|
+
},
|
|
393
|
+
Reason: { Text: "Processing Error" },
|
|
394
|
+
},
|
|
395
|
+
};
|
|
378
396
|
```
|
|
379
397
|
|
|
380
|
-
To change the HTTP statusCode of the response include it on the fault.
|
|
398
|
+
To change the HTTP statusCode of the response include it on the fault. The statusCode property will not be put on the xml message.
|
|
381
399
|
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
400
|
+
```javascript
|
|
401
|
+
throw {
|
|
402
|
+
Fault: {
|
|
403
|
+
Code: {
|
|
404
|
+
Value: "soap:Sender",
|
|
405
|
+
Subcode: { value: "rpc:BadArguments" },
|
|
406
|
+
},
|
|
407
|
+
Reason: { Text: "Processing Error" },
|
|
408
|
+
statusCode: 500,
|
|
409
|
+
},
|
|
410
|
+
};
|
|
393
411
|
```
|
|
394
412
|
|
|
395
413
|
### Server security example using PasswordDigest
|
|
@@ -397,7 +415,8 @@ To change the HTTP statusCode of the response include it on the fault. The stat
|
|
|
397
415
|
If `server.authenticate` is not defined then no authentication will take place.
|
|
398
416
|
|
|
399
417
|
Asynchronous authentication:
|
|
400
|
-
|
|
418
|
+
|
|
419
|
+
```javascript
|
|
401
420
|
server = soap.listen(...)
|
|
402
421
|
server.authenticate = function(security, callback) {
|
|
403
422
|
var created, nonce, password, user, token;
|
|
@@ -416,7 +435,8 @@ Asynchronous authentication:
|
|
|
416
435
|
```
|
|
417
436
|
|
|
418
437
|
Synchronous authentication:
|
|
419
|
-
|
|
438
|
+
|
|
439
|
+
```javascript
|
|
420
440
|
server = soap.listen(...)
|
|
421
441
|
server.authenticate = function(security) {
|
|
422
442
|
var created, nonce, password, user, token;
|
|
@@ -432,21 +452,20 @@ The `server.authorizeConnection` method is called prior to the soap service meth
|
|
|
432
452
|
If the method is defined and returns `false` then the incoming connection is
|
|
433
453
|
terminated.
|
|
434
454
|
|
|
435
|
-
```
|
|
455
|
+
```javascript
|
|
436
456
|
server = soap.listen(...)
|
|
437
457
|
server.authorizeConnection = function(req) {
|
|
438
458
|
return true; // or false
|
|
439
459
|
};
|
|
440
460
|
```
|
|
441
461
|
|
|
442
|
-
|
|
443
462
|
## SOAP Headers
|
|
444
463
|
|
|
445
464
|
### Received SOAP Headers
|
|
446
465
|
|
|
447
466
|
A service method can look at the SOAP headers by providing a 3rd arguments.
|
|
448
467
|
|
|
449
|
-
```
|
|
468
|
+
```javascript
|
|
450
469
|
{
|
|
451
470
|
HeadersAwareFunction: function(args, cb, headers) {
|
|
452
471
|
return {
|
|
@@ -460,7 +479,7 @@ It is also possible to subscribe to the 'headers' event.
|
|
|
460
479
|
The event is triggered before the service method is called, and only when the
|
|
461
480
|
SOAP Headers are not empty.
|
|
462
481
|
|
|
463
|
-
```
|
|
482
|
+
```javascript
|
|
464
483
|
server = soap.listen(...)
|
|
465
484
|
server.on('headers', function(headers, methodName) {
|
|
466
485
|
// It is possible to change the value of the headers
|
|
@@ -478,20 +497,21 @@ second parameter is the name of the SOAP method that will called
|
|
|
478
497
|
Both client & server can define SOAP headers that will be added to what they send.
|
|
479
498
|
They provide the following methods to manage the headers.
|
|
480
499
|
|
|
500
|
+
#### _addSoapHeader_(soapHeader[, name, namespace, xmlns]) - add soapHeader to soap:Header node
|
|
481
501
|
|
|
482
|
-
#### *addSoapHeader*(soapHeader[, name, namespace, xmlns]) - add soapHeader to soap:Header node
|
|
483
502
|
##### Parameters
|
|
484
|
-
|
|
485
|
-
|
|
503
|
+
|
|
504
|
+
- `soapHeader` Object({rootName: {name: 'value'}}), strict xml-string,
|
|
505
|
+
or function (server only)
|
|
486
506
|
|
|
487
507
|
For servers only, `soapHeader` can be a function, which allows headers to be
|
|
488
508
|
dynamically generated from information in the request. This function will be
|
|
489
509
|
called with the following arguments for each received request:
|
|
490
510
|
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
511
|
+
- `methodName` The name of the request method
|
|
512
|
+
- `args` The arguments of the request
|
|
513
|
+
- `headers` The headers in the request
|
|
514
|
+
- `req` The original request object
|
|
495
515
|
|
|
496
516
|
The return value of the function must be an Object({rootName: {name: 'value'}})
|
|
497
517
|
or strict xml-string, which will be inserted as an outgoing header of the
|
|
@@ -499,7 +519,7 @@ response to that request.
|
|
|
499
519
|
|
|
500
520
|
For example:
|
|
501
521
|
|
|
502
|
-
```
|
|
522
|
+
```javascript
|
|
503
523
|
server = soap.listen(...);
|
|
504
524
|
server.addSoapHeader(function(methodName, args, headers, req) {
|
|
505
525
|
console.log('Adding headers for method', methodName);
|
|
@@ -512,58 +532,61 @@ For example:
|
|
|
512
532
|
```
|
|
513
533
|
|
|
514
534
|
##### Returns
|
|
535
|
+
|
|
515
536
|
The index where the header is inserted.
|
|
516
537
|
|
|
517
538
|
##### Optional parameters when first arg is object :
|
|
518
|
-
- `name` Unknown parameter (it could just a empty string)
|
|
519
|
-
- `namespace` prefix of xml namespace
|
|
520
|
-
- `xmlns` URI
|
|
521
539
|
|
|
522
|
-
|
|
540
|
+
- `name` Unknown parameter (it could just a empty string)
|
|
541
|
+
- `namespace` prefix of xml namespace
|
|
542
|
+
- `xmlns` URI
|
|
543
|
+
|
|
544
|
+
#### _changeSoapHeader_(index, soapHeader[, name, namespace, xmlns]) - change an already existing soapHeader
|
|
545
|
+
|
|
523
546
|
##### Parameters
|
|
524
|
-
- `index` index of the header to replace with provided new value
|
|
525
|
-
- `soapHeader` Object({rootName: {name: 'value'}}), strict xml-string
|
|
526
|
-
or function (server only)
|
|
527
547
|
|
|
528
|
-
|
|
548
|
+
- `index` index of the header to replace with provided new value
|
|
549
|
+
- `soapHeader` Object({rootName: {name: 'value'}}), strict xml-string
|
|
550
|
+
or function (server only)
|
|
529
551
|
|
|
530
|
-
|
|
552
|
+
See `addSoapHeader` for how to pass a function into `soapHeader`.
|
|
531
553
|
|
|
532
|
-
####
|
|
554
|
+
#### _getSoapHeaders_() - return all defined headers
|
|
533
555
|
|
|
556
|
+
#### _clearSoapHeaders_() - remove all defined headers
|
|
534
557
|
|
|
535
558
|
## Client
|
|
536
559
|
|
|
537
|
-
An instance of `Client` is passed to the `soap.createClient` callback.
|
|
560
|
+
An instance of `Client` is passed to the `soap.createClient` callback. It is used to execute methods on the soap service.
|
|
538
561
|
|
|
539
562
|
### Client.describe() - description of services, ports and methods as a JavaScript object
|
|
540
563
|
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
}
|
|
550
|
-
}
|
|
564
|
+
```javascript
|
|
565
|
+
client.describe(); // returns
|
|
566
|
+
{
|
|
567
|
+
MyService: {
|
|
568
|
+
MyPort: {
|
|
569
|
+
MyFunction: {
|
|
570
|
+
input: {
|
|
571
|
+
name: "string";
|
|
551
572
|
}
|
|
552
573
|
}
|
|
553
574
|
}
|
|
575
|
+
}
|
|
576
|
+
}
|
|
554
577
|
```
|
|
555
578
|
|
|
556
579
|
### Client.setSecurity(security) - use the specified security protocol
|
|
557
580
|
|
|
558
581
|
See [Security](#security) for example usage.
|
|
559
582
|
|
|
560
|
-
### Client
|
|
583
|
+
### Client._method_(args, callback, options) - call _method_ on the SOAP service.
|
|
561
584
|
|
|
562
|
-
- `args` (
|
|
563
|
-
- `callback` (
|
|
564
|
-
- `options` (
|
|
565
|
-
- `forever` (
|
|
566
|
-
- `attachments` (
|
|
585
|
+
- `args` (_Object_): Arguments that generate an XML document inside of the SOAP Body section.
|
|
586
|
+
- `callback` (_Function_)
|
|
587
|
+
- `options` (_Object_): Set options for the request module on WSDL requests. If using the default request module, see [Request Config | Axios Docs](https://axios-http.com/docs/req_config). Additional options supported by `node-soap` are documented below:
|
|
588
|
+
- `forever` (_boolean_): Enables keep-alive connections and pools them
|
|
589
|
+
- `attachments` (_Array_): array of attachment objects. This converts the request into MTOM: _headers['Content-Type']='multipart/related; type="application/xop+xml"; start= ... '_
|
|
567
590
|
```
|
|
568
591
|
[{
|
|
569
592
|
mimetype: content mimetype,
|
|
@@ -574,41 +597,45 @@ See [Security](#security) for example usage.
|
|
|
574
597
|
...
|
|
575
598
|
]
|
|
576
599
|
```
|
|
577
|
-
- `forceMTOM` (
|
|
578
|
-
- `forceGzip` (
|
|
600
|
+
- `forceMTOM` (_boolean_): Send the request as MTOM even if you don't have attachments.
|
|
601
|
+
- `forceGzip` (_boolean_): Force transfer-encoding in gzip. (**Default:** `false`)
|
|
579
602
|
|
|
580
603
|
#### Example
|
|
581
604
|
|
|
582
|
-
```
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
605
|
+
```javascript
|
|
606
|
+
client.MyFunction(
|
|
607
|
+
{ name: "value" },
|
|
608
|
+
function (err, result, rawResponse, soapHeader, rawRequest) {
|
|
609
|
+
// result is a javascript object
|
|
610
|
+
// rawResponse is the raw xml response string
|
|
611
|
+
// soapHeader is the response soap header as a javascript object
|
|
612
|
+
// rawRequest is the raw xml request string
|
|
613
|
+
}
|
|
614
|
+
);
|
|
589
615
|
```
|
|
590
616
|
|
|
591
|
-
### Client.*method*Async(args, options) - call
|
|
617
|
+
### Client.*method*Async(args, options) - call _method_ on the SOAP service.
|
|
592
618
|
|
|
593
|
-
- `args` (
|
|
594
|
-
- `options` (
|
|
619
|
+
- `args` (_Object_): Arguments that generate an XML document inside of the SOAP Body section.
|
|
620
|
+
- `options` (_Object_): See [Client._method_(args, callback, options) - call _method_ on the SOAP service.](#clientmethodargs-callback-options---call-method-on-the-soap-service) for a description.
|
|
595
621
|
|
|
596
622
|
#### Example
|
|
597
623
|
|
|
598
|
-
```
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
624
|
+
```javascript
|
|
625
|
+
client.MyFunctionAsync({ name: "value" }).then((result) => {
|
|
626
|
+
// result is a javascript array containing result, rawResponse, soapheader, and rawRequest
|
|
627
|
+
// result is a javascript object
|
|
628
|
+
// rawResponse is the raw xml response string
|
|
629
|
+
// soapHeader is the response soap header as a javascript object
|
|
630
|
+
// rawRequest is the raw xml request string
|
|
631
|
+
});
|
|
606
632
|
```
|
|
607
633
|
|
|
608
634
|
##### Example with JSON for the `args`
|
|
635
|
+
|
|
609
636
|
The example above uses `{name: 'value'}` as the args. This may generate a SOAP messages such as:
|
|
610
637
|
|
|
611
|
-
```
|
|
638
|
+
```javascript
|
|
612
639
|
<?xml version="1.0" encoding="utf-8"?>
|
|
613
640
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|
|
614
641
|
<soapenv:Body>
|
|
@@ -619,12 +646,13 @@ The example above uses `{name: 'value'}` as the args. This may generate a SOAP m
|
|
|
619
646
|
</soapenv:Envelope>
|
|
620
647
|
```
|
|
621
648
|
|
|
622
|
-
Note that the "Request" element in the output above comes from the WSDL.
|
|
649
|
+
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`).
|
|
623
650
|
|
|
624
651
|
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.
|
|
625
652
|
|
|
626
653
|
##### Example with XML String for the `args`
|
|
627
|
-
|
|
654
|
+
|
|
655
|
+
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">`).
|
|
628
656
|
|
|
629
657
|
```
|
|
630
658
|
var args = { _xml: "<ns1:MyRootElement xmlns:ns1="http://www.example.com/v1/ns1">
|
|
@@ -632,72 +660,97 @@ You may pass in a fully-formed XML string instead the individual elements in JSO
|
|
|
632
660
|
</ns1:MyRootElement>"
|
|
633
661
|
};
|
|
634
662
|
```
|
|
635
|
-
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.
|
|
636
663
|
|
|
637
|
-
|
|
664
|
+
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.
|
|
665
|
+
|
|
666
|
+
### Client._service_._port_._method_(args, callback[, options[, extraHeaders]]) - call a _method_ using a specific _service_ and _port_
|
|
638
667
|
|
|
639
|
-
- `args` (
|
|
640
|
-
- `callback` (
|
|
641
|
-
- `options` (
|
|
642
|
-
- `extraHeaders` (
|
|
668
|
+
- `args` (_Object_): Arguments that generate an XML document inside of the SOAP Body section.
|
|
669
|
+
- `callback` (_Function_)
|
|
670
|
+
- `options` (_Object_): See [Client._method_(args, callback, options) - call _method_ on the SOAP service.](#clientmethodargs-callback-options---call-method-on-the-soap-service) for a description.
|
|
671
|
+
- `extraHeaders` (_Object_): Sets HTTP headers for the WSDL request.
|
|
643
672
|
|
|
644
673
|
#### Example
|
|
645
674
|
|
|
646
|
-
```
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
675
|
+
```javascript
|
|
676
|
+
client.MyService.MyPort.MyFunction({ name: "value" }, function (err, result) {
|
|
677
|
+
// result is a javascript object
|
|
678
|
+
});
|
|
650
679
|
```
|
|
651
680
|
|
|
652
681
|
#### Options (optional)
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
682
|
+
|
|
683
|
+
- Accepts any option that the request module accepts, see [here.](https://github.com/mikeal/request)
|
|
684
|
+
- For example, you could set a timeout of 5 seconds on the request like this:
|
|
685
|
+
|
|
686
|
+
```javascript
|
|
687
|
+
client.MyService.MyPort.MyFunction(
|
|
688
|
+
{ name: "value" },
|
|
689
|
+
function (err, result) {
|
|
690
|
+
// result is a javascript object
|
|
691
|
+
},
|
|
692
|
+
{ timeout: 5000 }
|
|
693
|
+
);
|
|
659
694
|
```
|
|
660
695
|
|
|
661
696
|
- You can measure the elapsed time on the request by passing the time option:
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
697
|
+
|
|
698
|
+
```javascript
|
|
699
|
+
client.MyService.MyPort.MyFunction(
|
|
700
|
+
{ name: "value" },
|
|
701
|
+
function (err, result) {
|
|
702
|
+
// client.lastElapsedTime - the elapsed time of the last request in milliseconds
|
|
703
|
+
},
|
|
704
|
+
{ time: true }
|
|
705
|
+
);
|
|
666
706
|
```
|
|
667
707
|
|
|
668
708
|
- Also, you could pass your soap request through a debugging proxy such as [Fiddler](http://www.telerik.com/fiddler) or [Betwixt](https://github.com/kdzwinel/betwixt).
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
},
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
709
|
+
|
|
710
|
+
```javascript
|
|
711
|
+
client.MyService.MyPort.MyFunction(
|
|
712
|
+
{ name: "value" },
|
|
713
|
+
function (err, result) {
|
|
714
|
+
// client.lastElapsedTime - the elapsed time of the last request in milliseconds
|
|
715
|
+
},
|
|
716
|
+
{
|
|
717
|
+
proxy: {
|
|
718
|
+
protocol: "https",
|
|
719
|
+
host: "127.0.0.1",
|
|
720
|
+
port: 9000,
|
|
721
|
+
auth: {
|
|
722
|
+
username: "mikeymike",
|
|
723
|
+
password: "rapunz3l",
|
|
724
|
+
},
|
|
725
|
+
},
|
|
726
|
+
}
|
|
727
|
+
);
|
|
683
728
|
```
|
|
684
729
|
|
|
685
730
|
- You can modify xml (string) before call:
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
731
|
+
|
|
732
|
+
```javascript
|
|
733
|
+
client.MyService.MyPort.MyFunction(
|
|
734
|
+
{ name: "value" },
|
|
735
|
+
function (err, result) {
|
|
736
|
+
// client.lastElapsedTime - the elapsed time of the last request in milliseconds
|
|
737
|
+
},
|
|
738
|
+
{
|
|
739
|
+
postProcess: function (_xml) {
|
|
740
|
+
return _xml.replace("text", "newtext");
|
|
741
|
+
},
|
|
742
|
+
}
|
|
743
|
+
);
|
|
744
|
+
```
|
|
693
745
|
|
|
694
746
|
#### Extra Headers (optional)
|
|
695
747
|
|
|
696
748
|
Object properties define extra HTTP headers to be sent on the request.
|
|
697
749
|
|
|
698
750
|
- Add custom User-Agent:
|
|
751
|
+
|
|
699
752
|
```javascript
|
|
700
|
-
client.addHttpHeader(
|
|
753
|
+
client.addHttpHeader("User-Agent", `CustomUserAgent`);
|
|
701
754
|
```
|
|
702
755
|
|
|
703
756
|
#### Alternative method call using callback-last pattern
|
|
@@ -705,57 +758,81 @@ client.addHttpHeader('User-Agent', `CustomUserAgent`);
|
|
|
705
758
|
To align method call signature with node' standard callback-last patter and event allow promisification of method calls, the following method signatures are also supported:
|
|
706
759
|
|
|
707
760
|
```javascript
|
|
708
|
-
client.MyService.MyPort.MyFunction(
|
|
709
|
-
|
|
710
|
-
|
|
761
|
+
client.MyService.MyPort.MyFunction(
|
|
762
|
+
{ name: "value" },
|
|
763
|
+
options,
|
|
764
|
+
function (err, result) {
|
|
765
|
+
// result is a javascript object
|
|
766
|
+
}
|
|
767
|
+
);
|
|
711
768
|
|
|
712
|
-
client.MyService.MyPort.MyFunction(
|
|
713
|
-
|
|
714
|
-
|
|
769
|
+
client.MyService.MyPort.MyFunction(
|
|
770
|
+
{ name: "value" },
|
|
771
|
+
options,
|
|
772
|
+
extraHeaders,
|
|
773
|
+
function (err, result) {
|
|
774
|
+
// result is a javascript object
|
|
775
|
+
}
|
|
776
|
+
);
|
|
715
777
|
```
|
|
716
778
|
|
|
717
779
|
### Overriding the namespace prefix
|
|
718
|
-
|
|
780
|
+
|
|
781
|
+
`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.:
|
|
719
782
|
|
|
720
783
|
```javascript
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
784
|
+
client.MyService.MyPort.MyFunction(
|
|
785
|
+
{ "ns1:name": "value" },
|
|
786
|
+
function (err, result) {
|
|
787
|
+
// request body sent with `<ns1:name`, regardless of what the namespace should have been.
|
|
788
|
+
},
|
|
789
|
+
{ timeout: 5000 }
|
|
790
|
+
);
|
|
724
791
|
```
|
|
725
792
|
|
|
726
793
|
- Remove namespace prefix of param
|
|
727
794
|
|
|
728
795
|
```javascript
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
796
|
+
client.MyService.MyPort.MyFunction(
|
|
797
|
+
{ ":name": "value" },
|
|
798
|
+
function (err, result) {
|
|
799
|
+
// request body sent with `<name`, regardless of what the namespace should have been.
|
|
800
|
+
},
|
|
801
|
+
{ timeout: 5000 }
|
|
802
|
+
);
|
|
732
803
|
```
|
|
733
804
|
|
|
734
|
-
### Client
|
|
805
|
+
### Client._lastRequest_ - the property that contains last full soap request for client logging
|
|
735
806
|
|
|
736
807
|
### Client.setEndpoint(url) - overwrite the SOAP service endpoint address
|
|
737
808
|
|
|
738
809
|
### Client Events
|
|
810
|
+
|
|
739
811
|
Client instances emit the following events:
|
|
740
812
|
|
|
741
813
|
### _request_
|
|
814
|
+
|
|
742
815
|
Emitted before a request is sent. The event handler has the signature `(xml, eid)`.
|
|
743
816
|
|
|
744
817
|
- _xml_ - The entire Soap request (Envelope) including headers.
|
|
745
818
|
- _eid_ - The exchange id.
|
|
746
819
|
|
|
747
820
|
### _message_
|
|
821
|
+
|
|
748
822
|
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)`.
|
|
749
823
|
|
|
750
824
|
- _message_ - Soap body contents.
|
|
751
825
|
- _eid_ - The exchange id.
|
|
752
826
|
|
|
753
827
|
### _soapError_
|
|
828
|
+
|
|
754
829
|
Emitted when an erroneous response is received. Useful if you want to globally log errors. The event handler has the signature `(error, eid)`.
|
|
755
830
|
|
|
756
831
|
- _error_ - An error object which also contains the resoponse.
|
|
757
832
|
- _eid_ - The exchange id.
|
|
833
|
+
|
|
758
834
|
### _response_
|
|
835
|
+
|
|
759
836
|
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)`
|
|
760
837
|
|
|
761
838
|
- _body_ - The SOAP response body.
|
|
@@ -772,9 +849,9 @@ By default exchange ids are generated by using node-uuid but you can use options
|
|
|
772
849
|
Example :
|
|
773
850
|
|
|
774
851
|
```javascript
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
852
|
+
client.MyService.MyPort.MyFunction(args, function (err, result) {}, {
|
|
853
|
+
exchangeId: myExchangeId,
|
|
854
|
+
});
|
|
778
855
|
```
|
|
779
856
|
|
|
780
857
|
## WSDL
|
|
@@ -787,18 +864,20 @@ services).
|
|
|
787
864
|
## WSDL.constructor(wsdl, baseURL, options):
|
|
788
865
|
|
|
789
866
|
Construct a WSDL instance from either the WSDL content or the URL to the WSDL.
|
|
867
|
+
|
|
790
868
|
#### Parameters
|
|
791
869
|
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
870
|
+
- wsdl: A string wSDL or an URL to the WSDL
|
|
871
|
+
- baseURL: base URL for the SOAP API
|
|
872
|
+
- options: options (see source for details), use `{}` as default.
|
|
795
873
|
|
|
796
874
|
### wsdl.xmlToObject(xml):
|
|
797
875
|
|
|
798
876
|
Unmarshal XML to object.
|
|
799
877
|
|
|
800
878
|
#### Parameters:
|
|
801
|
-
|
|
879
|
+
|
|
880
|
+
- xml: SOAP response (XML) to unmarshal
|
|
802
881
|
|
|
803
882
|
#### Returns:
|
|
804
883
|
|
|
@@ -809,16 +888,18 @@ Object containing the object types from the xml as keys.
|
|
|
809
888
|
Marshal an object to XML
|
|
810
889
|
|
|
811
890
|
#### Parameters:
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
891
|
+
|
|
892
|
+
- object: Object to marshal
|
|
893
|
+
- typeName: type (as per the wsdl) of the object
|
|
894
|
+
- namespacePrefix: namespace prefix
|
|
895
|
+
- namespaceURI: URI of the namespace
|
|
816
896
|
|
|
817
897
|
#### Returns:
|
|
818
898
|
|
|
819
899
|
XML representation of object.
|
|
820
900
|
|
|
821
901
|
#### Example:
|
|
902
|
+
|
|
822
903
|
```typescript
|
|
823
904
|
// Abstracted from a real use case
|
|
824
905
|
import { AxiosInstance } from 'axios';
|
|
@@ -858,154 +939,169 @@ async function samplePostCall(prospect: IProspectType) {
|
|
|
858
939
|
}
|
|
859
940
|
```
|
|
860
941
|
|
|
861
|
-
|
|
862
942
|
## Security
|
|
863
943
|
|
|
864
|
-
`node-soap` has several default security protocols.
|
|
865
|
-
as well.
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
944
|
+
`node-soap` has several default security protocols. You can easily add your own
|
|
945
|
+
as well. The interface is quite simple. Each protocol defines these optional methods:
|
|
946
|
+
|
|
947
|
+
- `addOptions(options)` - a method that accepts an options arg that is eventually passed directly to `request`.
|
|
948
|
+
- `addHeaders(headers)` - a method that accepts an argument with HTTP headers, to add new ones.
|
|
949
|
+
- `toXML()` - a method that returns a string of XML to be appended to the SOAP headers. Not executed if `postProcess` is also defined.
|
|
950
|
+
- `postProcess(xml, envelopeKey)` - a method that receives the the assembled request XML plus envelope key, and returns a processed string of XML. Executed before `options.postProcess`.
|
|
870
951
|
|
|
871
952
|
### BasicAuthSecurity
|
|
872
953
|
|
|
873
|
-
```
|
|
874
|
-
|
|
954
|
+
```javascript
|
|
955
|
+
client.setSecurity(new soap.BasicAuthSecurity("username", "password"));
|
|
875
956
|
```
|
|
876
957
|
|
|
877
958
|
### BearerSecurity
|
|
878
959
|
|
|
879
|
-
```
|
|
880
|
-
|
|
960
|
+
```javascript
|
|
961
|
+
client.setSecurity(new soap.BearerSecurity("token"));
|
|
881
962
|
```
|
|
882
963
|
|
|
883
964
|
### ClientSSLSecurity
|
|
884
965
|
|
|
885
966
|
_Note_: If you run into issues using this protocol, consider passing these options
|
|
886
967
|
as default request options to the constructor:
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
968
|
+
|
|
969
|
+
- `rejectUnauthorized: false`
|
|
970
|
+
- `strictSSL: false`
|
|
971
|
+
- `secureOptions: constants.SSL_OP_NO_TLSv1_2` (this is likely needed for node >= 10.0)
|
|
890
972
|
|
|
891
973
|
If you want to reuse tls sessions, you can use the option `forever: true`.
|
|
892
974
|
|
|
893
|
-
```
|
|
894
|
-
client.setSecurity(
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
975
|
+
```javascript
|
|
976
|
+
client.setSecurity(
|
|
977
|
+
new soap.ClientSSLSecurity(
|
|
978
|
+
"/path/to/key",
|
|
979
|
+
"path/to/cert",
|
|
980
|
+
"/path/to/ca-cert" /*or an array of buffer: [fs.readFileSync('/path/to/ca-cert/1', 'utf8'),
|
|
981
|
+
'fs.readFileSync('/path/to/ca-cert/2', 'utf8')], */,
|
|
982
|
+
{
|
|
983
|
+
/*default request options like */
|
|
984
|
+
// strictSSL: true,
|
|
985
|
+
// rejectUnauthorized: false,
|
|
986
|
+
// hostname: 'some-hostname'
|
|
987
|
+
// secureOptions: constants.SSL_OP_NO_TLSv1_2,
|
|
988
|
+
// forever: true,
|
|
989
|
+
}
|
|
990
|
+
)
|
|
991
|
+
);
|
|
907
992
|
```
|
|
908
993
|
|
|
909
994
|
### ClientSSLSecurityPFX
|
|
910
995
|
|
|
911
996
|
_Note_: If you run into issues using this protocol, consider passing these options
|
|
912
997
|
as default request options to the constructor:
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
998
|
+
|
|
999
|
+
- `rejectUnauthorized: false`
|
|
1000
|
+
- `strictSSL: false`
|
|
1001
|
+
- `secureOptions: constants.SSL_OP_NO_TLSv1_2` (this is likely needed for node >= 10.0)
|
|
916
1002
|
|
|
917
1003
|
If you want to reuse tls sessions, you can use the option `forever: true`.
|
|
918
1004
|
|
|
919
|
-
```
|
|
920
|
-
client.setSecurity(
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
1005
|
+
```javascript
|
|
1006
|
+
client.setSecurity(
|
|
1007
|
+
new soap.ClientSSLSecurityPFX(
|
|
1008
|
+
"/path/to/pfx/cert", // or a buffer: [fs.readFileSync('/path/to/pfx/cert', 'utf8'),
|
|
1009
|
+
"path/to/optional/passphrase",
|
|
1010
|
+
{
|
|
1011
|
+
/*default request options like */
|
|
1012
|
+
// strictSSL: true,
|
|
1013
|
+
// rejectUnauthorized: false,
|
|
1014
|
+
// hostname: 'some-hostname'
|
|
1015
|
+
// secureOptions: constants.SSL_OP_NO_TLSv1_2,
|
|
1016
|
+
// forever: true,
|
|
1017
|
+
}
|
|
1018
|
+
)
|
|
1019
|
+
);
|
|
931
1020
|
```
|
|
932
1021
|
|
|
933
1022
|
### WSSecurity
|
|
934
1023
|
|
|
935
1024
|
`WSSecurity` implements WS-Security. UsernameToken and PasswordText/PasswordDigest is supported.
|
|
936
1025
|
|
|
937
|
-
```
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
1026
|
+
```javascript
|
|
1027
|
+
var options = {
|
|
1028
|
+
hasNonce: true,
|
|
1029
|
+
actor: "actor",
|
|
1030
|
+
};
|
|
1031
|
+
var wsSecurity = new soap.WSSecurity("username", "password", options);
|
|
1032
|
+
client.setSecurity(wsSecurity);
|
|
944
1033
|
```
|
|
1034
|
+
|
|
945
1035
|
the `options` object is optional and can contain the following properties:
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
1036
|
+
|
|
1037
|
+
- `passwordType`: 'PasswordDigest' or 'PasswordText' (default: `'PasswordText'`)
|
|
1038
|
+
- `hasTimeStamp`: adds Timestamp element (default: `true`)
|
|
1039
|
+
- `hasTokenCreated`: adds Created element (default: `true`)
|
|
1040
|
+
- `hasNonce`: adds Nonce element (default: `false`)
|
|
1041
|
+
- `mustUnderstand`: adds mustUnderstand=1 attribute to security tag (default: `false`)
|
|
1042
|
+
- `actor`: if set, adds Actor attribute with given value to security tag (default: `''`)
|
|
952
1043
|
|
|
953
1044
|
### WSSecurityCert
|
|
954
1045
|
|
|
955
1046
|
WS-Security X509 Certificate support.
|
|
956
1047
|
|
|
957
|
-
```
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
1048
|
+
```javascript
|
|
1049
|
+
var privateKey = fs.readFileSync(privateKeyPath);
|
|
1050
|
+
var publicKey = fs.readFileSync(publicKeyPath);
|
|
1051
|
+
var password = ""; // optional password
|
|
1052
|
+
var options = {
|
|
1053
|
+
hasTimeStamp: true,
|
|
1054
|
+
additionalReferences: ["wsa:Action", "wsa:ReplyTo", "wsa:To"],
|
|
1055
|
+
signerOptions: {
|
|
1056
|
+
prefix: "ds",
|
|
1057
|
+
attrs: { Id: "Signature" },
|
|
1058
|
+
existingPrefixes: {
|
|
1059
|
+
wsse: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
|
|
1060
|
+
},
|
|
1061
|
+
},
|
|
1062
|
+
};
|
|
1063
|
+
var wsSecurity = new soap.WSSecurityCert(
|
|
1064
|
+
privateKey,
|
|
1065
|
+
publicKey,
|
|
1066
|
+
password,
|
|
1067
|
+
options
|
|
1068
|
+
);
|
|
1069
|
+
client.setSecurity(wsSecurity);
|
|
978
1070
|
```
|
|
979
1071
|
|
|
980
1072
|
The `options` object is optional and can contain the following properties:
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
1073
|
+
|
|
1074
|
+
- `hasTimeStamp`: Includes Timestamp tags (default: `true`)
|
|
1075
|
+
- `signatureTransformations`: sets the Reference Transforms Algorithm (default ['http://www.w3.org/2000/09/xmldsig#enveloped-signature', 'http://www.w3.org/2001/10/xml-exc-c14n#']). Type is a string array
|
|
1076
|
+
- `signatureAlgorithm`: set to `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` to use sha256
|
|
1077
|
+
- `digestAlgorithm`: set to `http://www.w3.org/2000/09/xmldsig#sha1` to use sha1 (default `http://www.w3.org/2001/04/xmlenc#sha256`)
|
|
1078
|
+
- `additionalReferences` : (optional) Array of Soap headers that need to be signed. This need to be added using `client.addSoapHeader('header')`
|
|
1079
|
+
- `excludeReferencesFromSigning`: (Optional) An array of SOAP element names to exclude from signing (e.g., `Body`, `Timestamp`, `To`, `Action`).
|
|
1080
|
+
- `signerOptions`: (optional) passes options to the XML Signer package - from (https://github.com/yaronn/xml-crypto)
|
|
1081
|
+
- `existingPrefixes`: (optional) A hash of prefixes and namespaces prefix: namespace that shouldn't be in the signature because they already exist in the xml (default: `{ 'wsse': 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' }`)
|
|
1082
|
+
- `prefix`: (optional) Adds this value as a prefix for the generated signature tags.
|
|
1083
|
+
- `attrs`: (optional) A hash of attributes and values attrName: value to add to the signature root node
|
|
1084
|
+
- `idMode`: (optional) either 'wssecurity' to generate wsse-scoped reference Id on <Body> or undefined for an unscoped reference Id
|
|
992
1085
|
|
|
993
1086
|
### WSSecurityPlusCert
|
|
994
1087
|
|
|
995
1088
|
Use WSSecurity and WSSecurityCert together.
|
|
996
1089
|
|
|
997
|
-
```
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1090
|
+
```javascript
|
|
1091
|
+
var wsSecurity = new soap.WSSecurity(/* see WSSecurity above */);
|
|
1092
|
+
var wsSecurityCert = new soap.WSSecurityCert(/* see WSSecurityCert above */);
|
|
1093
|
+
var wsSecurityPlusCert = new soap.WSSecurityPlusCert(
|
|
1094
|
+
wsSecurity,
|
|
1095
|
+
wsSecurityCert
|
|
1096
|
+
);
|
|
1097
|
+
client.setSecurity(wsSecurityPlusCert);
|
|
1002
1098
|
```
|
|
1003
1099
|
|
|
1004
1100
|
#### Option examples
|
|
1005
1101
|
|
|
1006
1102
|
`hasTimeStamp:true`
|
|
1007
1103
|
|
|
1008
|
-
```
|
|
1104
|
+
```xml
|
|
1009
1105
|
<soap:Header>
|
|
1010
1106
|
<wsse:Security soap:mustUnderstand="1">
|
|
1011
1107
|
<wsse:BinarySecurityToken>XXX</wsse:BinarySecurityToken>
|
|
@@ -1032,7 +1128,8 @@ Use WSSecurity and WSSecurityCert together.
|
|
|
1032
1128
|
```
|
|
1033
1129
|
|
|
1034
1130
|
`additionalReferences: ['To']`
|
|
1035
|
-
|
|
1131
|
+
|
|
1132
|
+
```XML
|
|
1036
1133
|
<soap:Header>
|
|
1037
1134
|
<To Id="To">localhost.com</To>
|
|
1038
1135
|
<wsse:Security soap:mustUnderstand="1">
|
|
@@ -1068,7 +1165,7 @@ Use WSSecurity and WSSecurityCert together.
|
|
|
1068
1165
|
|
|
1069
1166
|
`signerOptions.prefix:'ds'`
|
|
1070
1167
|
|
|
1071
|
-
```
|
|
1168
|
+
```XML
|
|
1072
1169
|
<soap:Header>
|
|
1073
1170
|
<To Id="To">localhost.com</To>
|
|
1074
1171
|
<wsse:Security soap:mustUnderstand="1">
|
|
@@ -1104,7 +1201,7 @@ Use WSSecurity and WSSecurityCert together.
|
|
|
1104
1201
|
|
|
1105
1202
|
`signerOptions.attrs:{ Id: 'signature-100', foo:'bar'}`
|
|
1106
1203
|
|
|
1107
|
-
```
|
|
1204
|
+
```xml
|
|
1108
1205
|
<soap:Header>
|
|
1109
1206
|
<wsse:Security soap:mustUnderstand="1">
|
|
1110
1207
|
<wsse:BinarySecurityToken>XXX</wsse:BinarySecurityToken>
|
|
@@ -1129,11 +1226,12 @@ Use WSSecurity and WSSecurityCert together.
|
|
|
1129
1226
|
</wsse:Security>
|
|
1130
1227
|
</soap:Header>
|
|
1131
1228
|
```
|
|
1229
|
+
|
|
1132
1230
|
### WSSecurityCertWithToken
|
|
1133
1231
|
|
|
1134
1232
|
WS-Security X509 Certificate support. Just like WSSecurityCert, except that it accepts the input properties as a single object, with two properties added `username` and `password`. Which if added, will add a UsernameToken Element to the xml security element.
|
|
1135
1233
|
|
|
1136
|
-
```
|
|
1234
|
+
```xml
|
|
1137
1235
|
<wsse:UsernameToken>
|
|
1138
1236
|
<wsse:Username>someusername</wsse:Username>
|
|
1139
1237
|
<wsse:Password>someusername's password</wsse:Password>
|
|
@@ -1143,47 +1241,68 @@ WS-Security X509 Certificate support. Just like WSSecurityCert, except that it a
|
|
|
1143
1241
|
### NTLMSecurity
|
|
1144
1242
|
|
|
1145
1243
|
Parameter invocation:
|
|
1146
|
-
|
|
1147
|
-
|
|
1244
|
+
|
|
1245
|
+
```javascript
|
|
1246
|
+
client.setSecurity(
|
|
1247
|
+
new soap.NTLMSecurity("username", "password", "domain", "workstation")
|
|
1248
|
+
);
|
|
1148
1249
|
```
|
|
1250
|
+
|
|
1149
1251
|
This can also be set up with a JSON object, substituting values as appropriate, for example:
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1252
|
+
|
|
1253
|
+
```javascript
|
|
1254
|
+
var loginData = {
|
|
1255
|
+
username: "username",
|
|
1256
|
+
password: "password",
|
|
1257
|
+
domain: "domain",
|
|
1258
|
+
workstation: "workstation",
|
|
1259
|
+
};
|
|
1260
|
+
client.setSecurity(new soap.NTLMSecurity(loginData));
|
|
1153
1261
|
```
|
|
1154
1262
|
|
|
1155
1263
|
## Handling XML Attributes, Value and XML (wsdlOptions).
|
|
1264
|
+
|
|
1156
1265
|
Sometimes it is necessary to override the default behaviour of `node-soap` in order to deal with the special requirements
|
|
1157
1266
|
of your code base or a third library you use. Therefore you can use the `wsdlOptions` Object, which is passed in the
|
|
1158
1267
|
`#createClient()` method and could have any (or all) of the following contents:
|
|
1268
|
+
|
|
1159
1269
|
```javascript
|
|
1160
1270
|
var wsdlOptions = {
|
|
1161
|
-
attributesKey:
|
|
1162
|
-
valueKey:
|
|
1163
|
-
xmlKey:
|
|
1164
|
-
}
|
|
1271
|
+
attributesKey: "theAttrs",
|
|
1272
|
+
valueKey: "theVal",
|
|
1273
|
+
xmlKey: "theXml",
|
|
1274
|
+
};
|
|
1165
1275
|
```
|
|
1276
|
+
|
|
1166
1277
|
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.
|
|
1167
1278
|
|
|
1168
1279
|
### Overriding the `value` key
|
|
1280
|
+
|
|
1169
1281
|
By default, `node-soap` uses `$value` as the key for any parsed XML value which may interfere with your other code as it
|
|
1170
1282
|
could be some reserved word, or the `$` in general cannot be used for a key to start with.
|
|
1171
1283
|
|
|
1172
1284
|
You can define your own `valueKey` by passing it in the `wsdl_options` to the createClient call:
|
|
1285
|
+
|
|
1173
1286
|
```javascript
|
|
1174
1287
|
var wsdlOptions = {
|
|
1175
|
-
valueKey:
|
|
1288
|
+
valueKey: "theVal",
|
|
1176
1289
|
};
|
|
1177
1290
|
|
|
1178
|
-
soap.createClient(
|
|
1179
|
-
|
|
1180
|
-
|
|
1291
|
+
soap.createClient(
|
|
1292
|
+
__dirname + "/wsdl/default_namespace.wsdl",
|
|
1293
|
+
wsdlOptions,
|
|
1294
|
+
function (err, client) {
|
|
1295
|
+
// your code
|
|
1296
|
+
}
|
|
1297
|
+
);
|
|
1181
1298
|
```
|
|
1182
1299
|
|
|
1183
1300
|
### Overriding the `xml` key
|
|
1301
|
+
|
|
1184
1302
|
By default, `node-soap` uses `$xml` as the key to pass through an XML string as is; without parsing or namespacing it. It overrides all the other content that the node might have otherwise had.
|
|
1185
1303
|
|
|
1186
1304
|
For example :
|
|
1305
|
+
|
|
1187
1306
|
```javascript
|
|
1188
1307
|
{
|
|
1189
1308
|
dom: {
|
|
@@ -1202,7 +1321,9 @@ For example :
|
|
|
1202
1321
|
}
|
|
1203
1322
|
};
|
|
1204
1323
|
```
|
|
1324
|
+
|
|
1205
1325
|
could become
|
|
1326
|
+
|
|
1206
1327
|
```xml
|
|
1207
1328
|
<tns:dom>
|
|
1208
1329
|
<tns:nodeone>
|
|
@@ -1219,20 +1340,26 @@ could become
|
|
|
1219
1340
|
```
|
|
1220
1341
|
|
|
1221
1342
|
You can define your own `xmlKey` by passing it in the `wsdl_options` object to the createClient call:
|
|
1343
|
+
|
|
1222
1344
|
```javascript
|
|
1223
1345
|
var wsdlOptions = {
|
|
1224
|
-
xmlKey:
|
|
1346
|
+
xmlKey: "theXml",
|
|
1225
1347
|
};
|
|
1226
1348
|
|
|
1227
|
-
soap.createClient(
|
|
1228
|
-
|
|
1229
|
-
|
|
1349
|
+
soap.createClient(
|
|
1350
|
+
__dirname + "/wsdl/default_namespace.wsdl",
|
|
1351
|
+
wsdlOptions,
|
|
1352
|
+
function (err, client) {
|
|
1353
|
+
// your code
|
|
1354
|
+
}
|
|
1355
|
+
);
|
|
1230
1356
|
```
|
|
1231
1357
|
|
|
1232
1358
|
### Overriding the `attributes` key
|
|
1359
|
+
|
|
1233
1360
|
By default, `node-soap` uses `attributes` as the key to define a nodes attributes.
|
|
1234
1361
|
|
|
1235
|
-
```
|
|
1362
|
+
```javascript
|
|
1236
1363
|
{
|
|
1237
1364
|
parentnode: {
|
|
1238
1365
|
childnode: {
|
|
@@ -1244,37 +1371,45 @@ By default, `node-soap` uses `attributes` as the key to define a nodes attribute
|
|
|
1244
1371
|
}
|
|
1245
1372
|
}
|
|
1246
1373
|
```
|
|
1374
|
+
|
|
1247
1375
|
could become
|
|
1248
|
-
|
|
1376
|
+
|
|
1377
|
+
```xml
|
|
1249
1378
|
<parentnode>
|
|
1250
1379
|
<childnode name="childsname">Value</childnode>
|
|
1251
1380
|
</parentnode>
|
|
1252
1381
|
```
|
|
1253
1382
|
|
|
1254
1383
|
However, `attributes` may be a reserved key for some systems that actually want a node called `attributes`
|
|
1384
|
+
|
|
1255
1385
|
```xml
|
|
1256
1386
|
<attributes>
|
|
1257
1387
|
</attributes>
|
|
1258
1388
|
```
|
|
1259
1389
|
|
|
1260
1390
|
You can define your own `attributesKey` by passing it in the `wsdl_options` object to the createClient call:
|
|
1391
|
+
|
|
1261
1392
|
```javascript
|
|
1262
1393
|
var wsdlOptions = {
|
|
1263
|
-
attributesKey:
|
|
1394
|
+
attributesKey: "$attributes",
|
|
1264
1395
|
};
|
|
1265
1396
|
|
|
1266
|
-
soap.createClient(
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1397
|
+
soap.createClient(
|
|
1398
|
+
__dirname + "/wsdl/default_namespace.wsdl",
|
|
1399
|
+
wsdlOptions,
|
|
1400
|
+
function (err, client) {
|
|
1401
|
+
client.method({
|
|
1402
|
+
parentnode: {
|
|
1403
|
+
childnode: {
|
|
1404
|
+
$attributes: {
|
|
1405
|
+
name: "childsname",
|
|
1406
|
+
},
|
|
1407
|
+
$value: "Value",
|
|
1272
1408
|
},
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
});
|
|
1409
|
+
},
|
|
1410
|
+
});
|
|
1411
|
+
}
|
|
1412
|
+
);
|
|
1278
1413
|
```
|
|
1279
1414
|
|
|
1280
1415
|
### Overriding imports relative paths
|
|
@@ -1311,25 +1446,30 @@ soap.createClient('https://127.0.0.1/service.wsdl', options, function(err, clien
|
|
|
1311
1446
|
```
|
|
1312
1447
|
|
|
1313
1448
|
### Specifying the exact namespace definition of the root element
|
|
1449
|
+
|
|
1314
1450
|
In rare cases, you may want to precisely control the namespace definition that is included in the root element.
|
|
1315
1451
|
|
|
1316
1452
|
You can specify the namespace definitions by setting the `overrideRootElement` key in the `wsdlOptions` like so:
|
|
1453
|
+
|
|
1317
1454
|
```javascript
|
|
1318
1455
|
var wsdlOptions = {
|
|
1319
1456
|
overrideRootElement: {
|
|
1320
|
-
namespace:
|
|
1321
|
-
xmlnsAttributes: [
|
|
1322
|
-
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1328
|
-
|
|
1457
|
+
namespace: "xmlns:tns",
|
|
1458
|
+
xmlnsAttributes: [
|
|
1459
|
+
{
|
|
1460
|
+
name: "xmlns:ns2",
|
|
1461
|
+
value: "http://tempuri.org/",
|
|
1462
|
+
},
|
|
1463
|
+
{
|
|
1464
|
+
name: "xmlns:ns3",
|
|
1465
|
+
value: "http://sillypets.com/xsd",
|
|
1466
|
+
},
|
|
1467
|
+
],
|
|
1468
|
+
},
|
|
1329
1469
|
};
|
|
1330
1470
|
```
|
|
1331
1471
|
|
|
1332
|
-
To see it in practice, have a look at the sample files in: [test/request-response-samples/
|
|
1472
|
+
To see it in practice, have a look at the sample files in: [test/request-response-samples/addPets\_\_force_namespaces](https://github.com/vpulim/node-soap/tree/master/test/request-response-samples/addPets__force_namespaces)
|
|
1333
1473
|
|
|
1334
1474
|
### Custom Deserializer
|
|
1335
1475
|
|
|
@@ -1339,6 +1479,7 @@ For example if the soap response contains dates that are not in a format recogni
|
|
|
1339
1479
|
To do so, you can pass a `customDeserializer` object in `options`. The properties of this object are the types that your deserializer handles itself.
|
|
1340
1480
|
|
|
1341
1481
|
Example :
|
|
1482
|
+
|
|
1342
1483
|
```javascript
|
|
1343
1484
|
|
|
1344
1485
|
var wsdlOptions = {
|
|
@@ -1369,53 +1510,60 @@ Example :
|
|
|
1369
1510
|
```
|
|
1370
1511
|
|
|
1371
1512
|
### Changing the tag formats to use self-closing (empty element) tags
|
|
1513
|
+
|
|
1372
1514
|
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.
|
|
1373
1515
|
|
|
1374
1516
|
```javascript
|
|
1375
1517
|
var wsdlOptions = {
|
|
1376
|
-
useEmptyTag: true
|
|
1518
|
+
useEmptyTag: true,
|
|
1377
1519
|
};
|
|
1378
1520
|
```
|
|
1379
1521
|
|
|
1380
1522
|
For example: `{ MyTag: { attributes: { MyAttr: 'value' } } }` is:
|
|
1381
1523
|
|
|
1382
|
-
|
|
1383
|
-
|
|
1524
|
+
- **Without useEmptyTag**: `<MyTag MyAttr="value"></MyTag>`
|
|
1525
|
+
- **With useEmptyTag set to true**: `<MyTag MyAttr="value" />`
|
|
1384
1526
|
|
|
1385
1527
|
## Handling "ignored" namespaces
|
|
1528
|
+
|
|
1386
1529
|
If an Element in a `schema` definition depends on an Element which is present in the same namespace, normally the `tns:`
|
|
1387
1530
|
namespace prefix is used to identify this Element. This is not much of a problem as long as you have just one `schema` defined
|
|
1388
1531
|
(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,
|
|
1389
|
-
|
|
1390
|
-
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
|
-
|
|
1404
|
-
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1412
|
-
|
|
1413
|
-
|
|
1414
|
-
|
|
1415
|
-
|
|
1416
|
-
|
|
1532
|
+
which was obviously wrong.
|
|
1533
|
+
|
|
1534
|
+
`node-soap` now handles namespace prefixes which shouldn't be resolved (because it's not necessary) as so called `ignoredNamespaces`
|
|
1535
|
+
which default to an Array of 3 Strings (`['tns', 'targetNamespace', 'typedNamespace']`).
|
|
1536
|
+
|
|
1537
|
+
If this is not sufficient for your purpose you can easily add more namespace prefixes to this Array, or override it in its entirety
|
|
1538
|
+
by passing an `ignoredNamespaces` object within the `options` you pass in `soap.createClient()` method.
|
|
1539
|
+
|
|
1540
|
+
A simple `ignoredNamespaces` object, which only adds certain namespaces could look like this:
|
|
1541
|
+
|
|
1542
|
+
```
|
|
1543
|
+
var options = {
|
|
1544
|
+
ignoredNamespaces: {
|
|
1545
|
+
namespaces: ['namespaceToIgnore', 'someOtherNamespace']
|
|
1546
|
+
}
|
|
1547
|
+
}
|
|
1548
|
+
```
|
|
1549
|
+
|
|
1550
|
+
This would extend the `ignoredNamespaces` of the `WSDL` processor to `['tns', 'targetNamespace', 'typedNamespace', 'namespaceToIgnore', 'someOtherNamespace']`.
|
|
1551
|
+
|
|
1552
|
+
If you want to override the default ignored namespaces you would simply pass the following `ignoredNamespaces` object within the `options`:
|
|
1553
|
+
|
|
1554
|
+
```
|
|
1555
|
+
var options = {
|
|
1556
|
+
ignoredNamespaces: {
|
|
1557
|
+
namespaces: ['namespaceToIgnore', 'someOtherNamespace'],
|
|
1558
|
+
override: true
|
|
1559
|
+
}
|
|
1560
|
+
}
|
|
1561
|
+
```
|
|
1562
|
+
|
|
1563
|
+
This would override the default `ignoredNamespaces` of the `WSDL` processor to `['namespaceToIgnore', 'someOtherNamespace']`. (This shouldn't be necessary, anyways).
|
|
1417
1564
|
|
|
1418
1565
|
## Handling "ignoreBaseNameSpaces" attribute
|
|
1566
|
+
|
|
1419
1567
|
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"
|
|
1420
1568
|
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
|
|
1421
1569
|
set or the webservice bring errors.
|
|
@@ -1424,6 +1572,7 @@ By default the attribute is set to true.
|
|
|
1424
1572
|
An example to use:
|
|
1425
1573
|
|
|
1426
1574
|
A simple `ignoredNamespaces` object, which only adds certain namespaces could look like this:
|
|
1575
|
+
|
|
1427
1576
|
```
|
|
1428
1577
|
var options = {
|
|
1429
1578
|
ignoredNamespaces: true
|
|
@@ -1432,7 +1581,7 @@ ignoredNamespaces: true
|
|
|
1432
1581
|
|
|
1433
1582
|
## soap-stub
|
|
1434
1583
|
|
|
1435
|
-
Unit testing services that use soap clients can be very cumbersome.
|
|
1584
|
+
Unit testing services that use soap clients can be very cumbersome. In order to get
|
|
1436
1585
|
around this you can use `soap-stub` in conjunction with `sinon` to stub soap with
|
|
1437
1586
|
your clients.
|
|
1438
1587
|
|
|
@@ -1480,20 +1629,20 @@ describe('myService', function() {
|
|
|
1480
1629
|
});
|
|
1481
1630
|
```
|
|
1482
1631
|
|
|
1483
|
-
|
|
1484
1632
|
## Contributors
|
|
1485
1633
|
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
|
-
|
|
1634
|
+
- Author: [Vinay Pulim](https://github.com/vpulim)
|
|
1635
|
+
- Active maintainers:
|
|
1636
|
+
- [Vasily Martynov](https://github.com/w666)
|
|
1637
|
+
- Previous maintainers (not active for a long time):
|
|
1638
|
+
- [Joe Spencer](https://github.com/jsdevel)
|
|
1639
|
+
- [Heinz Romirer](https://github.com/herom)
|
|
1640
|
+
- [All Contributors](https://github.com/vpulim/node-soap/graphs/contributors)
|
|
1493
1641
|
|
|
1494
1642
|
[downloads-image]: http://img.shields.io/npm/dm/soap.svg
|
|
1495
1643
|
[npm-url]: https://npmjs.org/package/soap
|
|
1496
1644
|
[npm-image]: http://img.shields.io/npm/v/soap.svg
|
|
1497
|
-
|
|
1498
1645
|
[coveralls-url]: https://coveralls.io/r/vpulim/node-soap
|
|
1499
1646
|
[coveralls-image]: http://img.shields.io/coveralls/vpulim/node-soap/master.svg
|
|
1647
|
+
[buy-me-a-coffee-url]: https://coff.ee/vasily.m
|
|
1648
|
+
[buy-me-a-coffee-image]: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png
|