The SOAP connector enables LoopBack applications to interact with SOAP-based web services described using WSDL.

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.

Creating a data source

Use the Data source generator to add a REST data source to your application.

$ slc loopback:datasource

Choose REST as the data source type when prompted.

SOAP data source properties

The following table describes the SOAP data source properties you can set in datasources.json.

PropertyTypeDescription
urlString

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:

<wsdl:service name="Weather"> <wsdl:port name="WeatherSoap" binding="tns:WeatherSoap"> <soap:address location="http://wsf.cdyne.com/WeatherWS/Weather.asmx" /> </wsdl:port> ... </wsdl:service>

wsdlStringHTTP URL or local file system path to the WSDL file, if not present, defaults to ?wsdl.
remotingEnabledBoolean

Indicates whether the operations are exposed as REST APIs.

To expose or hide a specific method, you can override this with:

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

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

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:

PropertyTypeDescription
serviceStringWSDL service name
portStringWSDL port name
operationString

WSDL operation name

REVIEW COMMENT from $paramName
Below--Why is the port a symbol( 'StockQuoteSoap')? Where is the numeric value defined? Is it possible to use a number directly?

Here is an example operations property for the stock quote service:

operations: {
  // The key is the method name
  stockQuote: {
    service: 'StockQuote', // The WSDL service name
    port: 'StockQuoteSoap', // The WSDL port name
    operation: 'GetQuote' // The WSDL operation name
  },
  stockQuote12: {
    service: 'StockQuote', 
    port: 'StockQuoteSoap12', 
    operation: 'GetQuote' 
  }
}

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:

ds.once('connected', function () {
   // Create the model
   var WeatherService = ds.createModel('WeatherService', {});
   ...
}

Extending a model to wrap and mediate SOAP operations

Once you define the model, you can extend it to wrap or mediate SOAP operations and define new methods. The following example simplifies the GetCityForecastByZIP operation to a method that takes zip and returns an array of forecasts.

// Refine the methods
WeatherService.forecast = function (zip, cb) {
    WeatherService.GetCityForecastByZIP({ZIP: zip || '94555'}, function (err, response) {
        console.log('Forecast: %j', response);
        var result = (!err && response.GetCityForecastByZIPResult.Success) ?
        response.GetCityForecastByZIPResult.ForecastResult.Forecast : [];
        cb(err, result);
    });
};

The custom method on the model can be exposed as REST APIs. It uses the loopback.remoteMethod to define the mappings.

// Map to REST/HTTP
loopback.remoteMethod(
    WeatherService.forecast, {
       accepts: [
         {arg: 'zip', type: 'string', required: true, http: {source: 'query'}}
       ],
       returns: {arg: 'result', type: 'object', root: true},
       http: {verb: 'get', path: '/forecast'}
    }
);

Examples

The loopback-connector-soap repository provides several examples:

Get stock quotes by symbols: stock-ws.js.  Run with the command:

$ node example/stock-ws

Get weather and forecast information for a given zip code: weather-ws.js.  Run with the command:

$ node example/weather-ws

Expose REST APIs to proxy the SOAP web services:  weather-rest.js.    Run with the command:

$ node example/weather-rest

View the results at http://localhost:3000/explorer.