loopback-connector-soap



The SOAP connector enables LoopBack applications to interact with
SOAP-based web services described using
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 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.
- 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.

<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_options: {
  rejectUnauthorized: false,
  strictSSL: false,
  requestCert: true,
}

wsdl_headers: {
  Authorization: "Basic UGVyc29uYWwgYWNjb3VudDpORVdsazIwMTVAKSEl"
}

<Model>.<method>.shared = true | false;

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: {
  "custom-header": "value of custom-header",
  "custom-header-2": "value of custom-header-2"
}

$3

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);
`

$3

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'
}
`

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.