Worklight Adapters and the Worklight to Microsoft .NET: request-response pattern

Worklight adapters are the server-side code of applications deployed on and serviced by the Worklight Mobile Application Platform. Adapters connect Worklight Server to enterprise applications such as those running in WebSphere Message Broker. The following steps describe a typical flow of data between a mobile application and a Microsoft .NET web service running in Message Broker:

  1. The adapter exposes a set of services, called procedures. The adapter and mobile application are deployed to Worklight Server.
  2. The mobile application invokes procedures by issuing Ajax requests (WL.Client.invokeProcedure). Parameters for the procedure are passed as JSON-formatted data.
  3. The procedure converts the JSON parameters into an XML SOAP request message.
  4. The procedure uses the Microsoft .NET web service running in Message Broker.
  5. The Microsoft .NET web service returns data as an XML SOAP response.
  6. The XML-formatted data is converted to JSON by Worklight Server.
  7. The JSON data is sent back to the originating mobile application.

This pattern generates a Worklight adapter that can use each selected method on your .NET class. The adapter converts JSON requests from mobile applications into web service requests on your Microsoft .NET class. For example, assuming the following C# methods are in a class called RetailBank and you have selected them for a pattern instance called MyBank:

        public static string GetBalance(string accountNumber, out string lastUpdated);
        public static string TransferMoney(string sourceAccountNumber, string targetAccountNumber, string value);
        public static string FindMissingAccount(string name, ref string lastKnownAccountNumber);

The following snippet of JavaScript shows how a mobile application can invoke the GetBalance method:

        var invocationData = {
                adapter : "MyBank",
                procedure : "GetBalance",
                parameters : [ accountNo ]};
        
        var options = {
            onSuccess:lang.hitch(this, this.onResult),
            onFailure:lang.hitch(this, this.onError)};

        WL.Client.invokeProcedure(invocationData, options);

For testing purposes, the deployed Worklight adapter can be checked by using a web browser with the following URL:

http://localhost:8080/dev/invoke?adapter=MyBank&procedure=GetBalance&parameters=%5B123456789%5D

Generated Files

This section describes the files that are generated for the Worklight adapter.

Worklight Adapter

The pattern creates a Worklight adapter with two configuration files. The first configuration file (MyBank.xml) is the adapter XML file. The adapter XML file is used to configure the connectivity to Message Broker and to declare the procedures that are made available by the adapter to mobile applications and to other adapters. The example below shows the generated adapter XML configuration file:

    <?xml version="1.0" encoding="UTF-8"?>
    <wl:adapter name="MyBank"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:wl="http://www.worklight.com/integration"
        xmlns:http="http://www.worklight.com/integration/http">
    
        <displayName>MyBank</displayName>
        <description>Worklight integration adapter for the Microsoft .NET service</description>
        <connectivity>
            <connectionPolicy xsi:type="http:HTTPConnectionPolicyType">
                <protocol>http</protocol>
                <domain>localhost</domain>
                <port>7800</port>
            </connectionPolicy>
            <loadConstraints maxConcurrentConnectionsPerNode="99" />
        </connectivity>
    
        <procedure name="GetBalance"/>
        <procedure name="TransferMoney"/>
        <procedure name="FindMissingAccount"/>
    </wl:adapter>

Many of the values in this adapter XML file are configured from pattern parameters (for example displayName, domain and port). A procedure has been configured for each .NET method. Procedures define a process for accessing the operations exposed by the Microsoft .NET web service. There is one procedure for each operation in the web service.

The pattern also generates a JavaScript file (MyBank-impl.js) that contains the implementation functions for each procedure:

    var targetNamespace = "urn://bankingapplication/retailbank_V1";
    
    function PrepareWebService(method, parameters, path) {
        var request =
            '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="' + targetNamespace + '">' +
                '<soap:Header/>' +
                '<soap:Body>' +
                    '<tns:' + method + '>';
    
        for (var key in parameters) {
            request += '<' + key + '>' + parameters[key] + '</' + key + '>';
        }
    
        request += '</tns:' + method + '>' +
                '</soap:Body>' +
            '</soap:Envelope>';
    
        var input = {
            method : 'post',
            returnedContentType : 'xml',
            path : path,
            body : {
                contentType: 'application/xml; charset=utf-8',
                content: request
            }
        };
        return input;
    }
    
    var targetPath = "/retailbank";
    
    function sendRequest(name, input) {
        var response = WL.Server.invokeHttp(input);
        WL.Logger.log(response);
    
        if (response.Envelope) {
            var data = response.Envelope.Body;
            data = data[name];
            response.result = data;
            delete response.Envelope;
            WL.Logger.log(response);
        }
        return response;
    }

    function GetBalance(accountNumber) {
        var parameters = new Object();
        parameters['accountNumber'] = accountNumber;
        var input = PrepareWebService('GetBalance', parameters, targetPath);
        WL.Logger.debug('SOAP request: ' + input.body.content);
        return sendRequest('GetBalanceResponse', input);
    }
    
    function TransferMoney(sourceAccountNumber, targetAccountNumber, value) {
        var parameters = new Object();
        parameters['sourceAccountNumber'] = sourceAccountNumber;
        parameters['targetAccountNumber'] = targetAccountNumber;
        parameters['value'] = value;
        var input = PrepareWebService('TransferMoney', parameters, targetPath);
        WL.Logger.debug('SOAP request: ' + input.body.content);
        return sendRequest('TransferMoneyResponse', input);
    }
    
    function FindMissingAccount(name, lastKnownAccountNumber) {
        var parameters = new Object();
        parameters['name'] = name;
        parameters['lastKnownAccountNumber'] = lastKnownAccountNumber;
        var input = PrepareWebService('FindMissingAccount', parameters, targetPath);
        WL.Logger.debug('SOAP request: ' + input.body.content);
        return sendRequest('FindMissingAccountResponse', input);
    }

The generated JavaScript code converts the parameters provided in a JSON request into an XML SOAP message. The JSON to SOAP conversion is implemented in the PrepareWebService function. The SOAP request is passed to Worklight which invokes your Microsoft .NET web service in the WL.Server.invokeHttp function.

Example Messages

The XML SOAP request message for a call to the GetBalance operation that is implemented by the Microsoft .NET web service, with an account number of 123456789, looks like this:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="urn://bankingapplication/retailbank_V1">
        <soap:Header/>
        <soap:Body>
            <tns:GetBalance>
                <accountNumber>123456789</accountNumber>
            </tns:GetBalance>
        </soap:Body>
    </soap:Envelope>

Worklight Server automatically converts the XML SOAP response from the Microsoft .NET web service into JSON for the originating mobile application:

    {
      "errors": [],
      "info": [],
      "isSuccessful": true,
      "result": {
        "NS1": "urn://bankingapplication/retailbank_V1",
        "lastUpdated": "20/06/2012 11:46:52",
        "returnValue": "1000.00"
      },
      "statusCode": 200,
      "statusReason": "OK",
      "warnings": []
    }

Back to the Worklight to Microsoft .NET: request-response pattern specification