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:

$ 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"
}

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:

Here is an example operations property for the periodic table service:

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:

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:

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:

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.

...
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.