Soap for SRD
A SOAP client and server for node.js for establishing a connexion with SRD.
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:
```javascript
var wsdlOptions = {
valueKey: 'theVal'
};
soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
// your code
});
```
### Overriding the `xml` key
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.
For example :
```javascript
{
dom: {
nodeone: {
$xml: '
',
siblingnode: 'Cant see me.'
},
nodetwo: {
parentnode: {
attributes: {
type: 'type'
},
childnode: ''
}
}
}
};
```
could become
```xml
```
You can define your own `xmlKey` by passing it in the `wsdl_options` object to the createClient call:
```javascript
var wsdlOptions = {
xmlKey: 'theXml'
};
soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
// your code
});
```
### Overriding the `attributes` key
By default, `node-soap` uses `attributes` as the key to define a nodes attributes.
``` javascript
{
parentnode: {
childnode: {
attributes: {
name: 'childsname'
},
$value: 'Value'
}
}
}
```
could become
``` xml
Value
```
However, `attributes` may be a reserved key for some systems that actually want a node called `attributes`
```xml
```
You can define your own `attributesKey` by passing it in the `wsdl_options` object to the createClient call:
```javascript
var wsdlOptions = {
attributesKey: '$attributes'
};
soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
client.method({
parentnode: {
childnode: {
$attributes: {
name: 'childsname'
},
$value: 'Value'
}
}
});
});
```
### Specifying the exact namespace definition of the root element
In rare cases, you may want to precisely control the namespace definition that is included in the root element.
You can specify the namespace definitions by setting the `overrideRootElement` key in the `wsdlOptions` like so:
```javascript
var wsdlOptions = {
overrideRootElement: {
namespace: 'xmlns:tns',
xmlnsAttributes: [{
name: 'xmlns:ns2',
value: "http://tempuri.org/"
}, {
name: 'xmlns:ns3',
value: "http://sillypets.com/xsd"
}]
}
};
```
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)
### 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.
Example :
```javascript
var wsdlOptions = {
customDeserializer: {
// this function will be used to any date found in soap responses
date: function (text, context) {
/* text is the value of the xml element.
context contains the name of the xml element and other infos :
{
name: 'lastUpdatedDate',
object: {},
schema: 'xsd:date',
id: undefined,
nil: false
}
*/
return text;
}
}
};
soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
...
});
```
### Changing the tag formats to use self-closing (empty element) tags
The XML specification specifies that there is no semantic difference between `
` and `
`, and node-soap defaults to using the `
` 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 `
` format instead.
```javascript
var wsdlOptions = {
useEmptyTag: true
};
```
For example: `{ MyTag: { attributes: { MyAttr: 'value' } } }` is:
* **Without useEmptyTag**: `
`
* **With useEmptyTag set to true**: `
`
## 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:
```
var options = {
ignoredNamespaces: {
namespaces: ['namespaceToIgnore', 'someOtherNamespace']
}
}
```
This would extend the `ignoredNamespaces` of the `WSDL` processor to `['tns', 'targetNamespace', 'typedNamespace', 'namespaceToIgnore', 'someOtherNamespace']`.
If you want to override the default ignored namespaces you would simply pass the following `ignoredNamespaces` object within the `options`:
```
var options = {
ignoredNamespaces: {
namespaces: ['namespaceToIgnore', 'someOtherNamespace'],
override: true
}
}
```
This would override the default `ignoredNamespaces` of the `WSDL` processor to `['namespaceToIgnore', 'someOtherNamespace']`. (This shouldn't be necessary, anyways).
If you want to override the default ignored namespaces you would simply pass the following `ignoredNamespaces` object within the `options`:
```
var options = {
ignoredNamespaces: {
namespaces: ['namespaceToIgnore', 'someOtherNamespace'],
override: true
}
}
```
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:
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.
### Example
```javascript
// test-initialization-script.js
var sinon = require('sinon');
var soapStub = require('soap/soap-stub');
var urlMyApplicationWillUseWithCreateClient = 'http://path-to-my-wsdl';
var clientStub = {
SomeOperation: sinon.stub()
};
clientStub.SomeOperation.respondWithError = soapStub.createErroringStub({..error json...});
clientStub.SomeOperation.respondWithSuccess = soapStub.createRespondingStub({..success json...});
soapStub.registerClient('my client alias', urlMyApplicationWillUseWithCreateClient, clientStub);
// test.js
var soapStub = require('soap/soap-stub');
describe('myService', function() {
var clientStub;
var myService;
beforeEach(function() {
clientStub = soapStub.getStub('my client alias');
soapStub.reset();
myService.init(clientStub);
});
describe('failures', function() {
beforeEach(function() {
clientStub.SomeOperation.respondWithError();
});
it('should handle error responses', function() {
myService.somethingThatCallsSomeOperation(function(err, response) {
// handle the error response.
});
});
});
});
```
## Contributors
* Author: [Vinay Pulim](https://github.com/vpulim)
* Maintainers:
- [Joe Spencer](https://github.com/jsdevel)
- [Heinz Romirer](https://github.com/herom)
* [All Contributors](https://github.com/vpulim/node-soap/graphs/contributors)
[downloads-image]: http://img.shields.io/npm/dm/soap.svg
[npm-url]: https://npmjs.org/package/soap
[npm-image]: http://img.shields.io/npm/v/soap.svg
[travis-url]: https://travis-ci.org/vpulim/node-soap
[travis-image]: http://img.shields.io/travis/vpulim/node-soap.svg
[gitter-url]: https://gitter.im/vpulim/node-soap
[gitter-image]: https://badges.gitter.im/vpulim/node-soap.png
[coveralls-url]: https://coveralls.io/r/vpulim/node-soap
[coveralls-image]: http://img.shields.io/coveralls/vpulim/node-soap/master.svg -->