https://github.com/loopbackio/loopback-connector-soap
LoopBack's SOAP based Web Services Connector
https://github.com/loopbackio/loopback-connector-soap
Last synced: 9 months ago
JSON representation
LoopBack's SOAP based Web Services Connector
- Host: GitHub
- URL: https://github.com/loopbackio/loopback-connector-soap
- Owner: loopbackio
- License: other
- Created: 2013-04-20T03:16:04.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2025-05-14T21:00:53.000Z (9 months ago)
- Last Synced: 2025-05-14T22:18:53.910Z (9 months ago)
- Language: JavaScript
- Homepage:
- Size: 1.09 MB
- Stars: 82
- Watchers: 52
- Forks: 46
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# loopback-connector-soap
[](https://github.com/loopbackio/loopback-connector-soap/actions/workflows/continuous-integration.yml)
[](https://app.travis-ci.com/loopbackio/loopback-connector-soap)
[](https://coveralls.io/github/loopbackio/loopback-connector-soap?branch=master)
The SOAP connector enables LoopBack applications to interact with
[SOAP](http://www.w3.org/TR/soap)-based web services described using
[WSDL](http://www.w3.org/TR/wsdl).
For more information, see the
LoopBack documentation.
## Installation
In your application root directory, enter:
```shell
$ npm install loopback-connector-soap --save
```
This will install the module from npm and add it as a dependency to the application's
[package.json](http://loopback.io/doc/en/lb2/package.json.html) file.
## Overview
There are two ways to use the SOAP connector:
- Use the LoopBack CLI `lb soap` command to automatically create a set of models based on a SOAP service WSDL file. Often, this will be the easiest way to connect to a SOAP web service, but may not be suitable for all applications. For more information, see [SOAP generator](http://loopback.io/doc/en/lb3/SOAP-generator.html).
- Write the code manually, calling the `loopback-connector-soap` and data source APIs directly. **This is the approach illustrated here**.
While both approaches use the `loopback-connector-soap` data source connector, they appear quite different.
## SOAP data source properties
The following table describes the SOAP data source properties you can set in `datasources.json`.
Property
Type
Description
url
String
URL to the SOAP web service endpoint. If not present, defaults to the
location attribute of the SOAP address for the service/port
from the WSDL document; for example below it is http://www.webservicex.net/periodictable.asmx:
<wsdl:service name="periodictable">
<wsdl:port name="periodictableSoap" binding="tns:periodictableSoap">
<soap:address location="http://www.webservicex.net/periodictable.asmx"/>
</wsdl:port>
</wsdl:service>
wsdl
String
HTTP URL or local file system path to the WSDL file. Default is ?wsdl.
In the example above, it would be http://www.webservicex.net/periodictable.asmx?wsdl.
wsdl_options
Object
Indicates additonal options to pass to the SOAP connector, for example allowing self signed certificates.
For example:
wsdl_options: {
rejectUnauthorized: false,
strictSSL: false,
requestCert: true,
}
wsdl_headers
Object
Indicates additonal headers to pass to the SOAP connector, for example for sending http authorizations header.
For example:
wsdl_headers: {
Authorization: "Basic UGVyc29uYWwgYWNjb3VudDpORVdsazIwMTVAKSEl"
}
remotingEnabled
Boolean
Indicates whether the operations are exposed as REST APIs. To expose or hide a specific method, override with:
<Model>.<method>.shared = true | false;
operations
Object
Maps WSDL binding operations to Node.js methods. Each key in the JSON
object becomes the name of a method on the model.
See operations property below.
security
Object
security configuration.
See security property below.
soapHeaders
Array of objects.
Custom SOAP headers. An array of header properties.
For example:
soapHeaders: [{
element: {myHeader: 'XYZ'}, // The XML element in JSON object format
prefix: 'p1', // The XML namespace prefix for the header
namespace: 'http://ns1' // The XML namespace URI for the header
}]
httpHeaders
Object
Custom HTTP headers. An object of header properties.
For example:
httpHeaders: {
"custom-header": "value of custom-header",
"custom-header-2": "value of custom-header-2"
}
### operations property
The `operations` property value is a JSON object that has a property (key) for each
method being defined for the model. The corresponding value is an object with the
following properties:
| Property | Type | Description |
|---|---|---|
| service | String | WSDL service name |
| port | String | WSDL port name |
| operation | String | WSDL operation name |
Here is an example operations property for the periodic table service:
```javascript
operations: {
// The key is the method name
periodicTable: {
service: 'periodictable', // The WSDL service name
port: 'periodictableSoap', // The WSDL port name
operation: 'GetAtomicNumber' // The WSDL operation name
}
}
```
**IMPORTANT**: When using the CLI data source generator, you must supply the "stringified JSON" value for this property.
For example:
```
{"getAtomicWeight":{"service":"periodictable","port":"periodictableSoap","operation":"GetAtomicWeight"},"getAtomicNumber":{"service":"periodictable","port":"periodictableSoap","operation":"GetAtomicNumber"}}
```
To generate the stringified value, you can use the following code (for example):
```
var operations = {
"operations": {
"getAtomicWeight": {
"service": "periodictable",
"port": "periodictableSoap",
"operation": "GetAtomicWeight"
},
"getAtomicNumber": {
"service": "periodictable",
"port": "periodictableSoap",
"operation": "GetAtomicNumber"
}
}
};
var stringifiedOps = JSON.stringify (operations);
console.log(stringifiedOps);
```
### security property
The `security` property value is a JSON object with a `scheme` property.
The other properties of the object depend on the value of `scheme`. For example:
```javascript
security: {
scheme: 'WS',
username: 'test',
password: 'testpass',
passwordType: 'PasswordDigest'
}
```
Scheme
Description
Other properties
WS
WSSecurity scheme
- username: the user name
- password: the password
- passwordType: default is 'PasswordText'
BasicAuth1
Basic auth scheme
- username: the user name
- password: the password
ClientSSL
ClientSSL scheme
- keyPath: path to the private key file
- certPath: path to the certificate file
1 **currently unsupported**, use `"wsdl_headers": { "Authorization": "Basic …" },` instead, details: issue #92.
## Creating a model from a SOAP data source
Instead of defining a data source with `datasources.json`, you can define a data source in code; for example:
```js
ds.once('connected', function () {
// Create the model
var PeriodictableService = ds.createModel('PeriodictableService', {});
// External PeriodTable WebService operation exposed as REST APIs through LoopBack
PeriodictableService.atomicnumber = function (elementName, cb) {
PeriodictableService.GetAtomicNumber({ElementName: elementName || 'Copper'}, function (err, response) {
var result = response;
cb(err, result);
});
};
...
}
```
## Extending a model to wrap and mediate SOAP operations
You can extend a LoopBack model to wrap or mediate SOAP operations
and define new methods.
The following example simplifies the `GetAtomicNumber` operation:
```javascript
periodictableperiodictableSoap.GetAtomicNumber = function(GetAtomicNumber, callback) {
periodictableperiodictableSoap.GetAtomicNumber(GetAtomicNumber, function (err, response) {
var result = response;
callback(err, result);
});
}
```
## Creating a model from a SOAP data source
The SOAP connector loads WSDL documents asynchronously.
As a result, the data source won't be ready to create models until it's connected.
The recommended way is to use an event handler for the 'connected' event; for example
as shown below.
Once you define the model, you can extend it to wrap or mediate SOAP operations
and define new methods. The example below shows adding a LoopBack remote method
for the SOAP service's `GetAtomicNumber` operation.
```javascript
...
ds.once('connected', function () {
// Create the model
var PeriodictableService = ds.createModel('PeriodictableService', {});
// External PeriodTable WebService operation exposed as REST APIs through LoopBack
PeriodictableService.atomicnumber = function (elementName, cb) {
PeriodictableService.GetAtomicNumber({ElementName: elementName || 'Copper'}, function (err, response) {
var result = response;
cb(err, result);
});
};
// Map to REST/HTTP
loopback.remoteMethod(
PeriodictableService.atomicnumber, {
accepts: [
{arg: 'elementName', type: 'string', required: true,
http: {source: 'query'}}
],
returns: {arg: 'result', type: 'object', root: true},
http: {verb: 'get', path: '/GetAtomicNumber'}
}
);
})
...
```
## Example
For a complete example using the LoopBack SOAP connector in LoopBack 4, see [SOAP calculator tutorial](https://loopback.io/doc/en/lb4/soap-calculator-tutorial.html).