Worklight adapters and the Worklight: push notification from WebSphere MQ 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 the delivery of notifications starting with a provider application and ending with a mobile application:

  1. The provider application puts a notification message onto the queue.
  2. The Worklight adapter starts and uses the service on WebSphere Message Broker to request the next available notification message waiting on the message queue.
  3. If a notification message is returned, the adapter converts the XML SOAP response into a JSON notification object for Worklight.
  4. The adapter retrieves the subscription for the user identified in the notification message.
  5. If the subscription exists, the adapter instructs Worklight to deliver the notification message.
  6. If the subscription does not exist, the adapter logs the event and discards the message.
  7. Worklight sends the notification message to the relevant notification server (for example, APN).
  8. The push notification server arranges for the notification to be delivered to the mobile device.
  9. The mobile application receives the notification (this depends on several platform specific factors).

Generated Files

This section describes the files generated for the Worklight adapter.

Worklight Adapter

The pattern creates a Worklight adapter with two configuration files. The first configuration file is the adapter XML file. The adapter XML file is used to configure the connectivity to Message Broker. The example below shows the generated adapter XML configuration file:

    <?xml version="1.0" encoding="UTF-8"?>
    <wl:adapter name="PushAdapter"
        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>PushAdapter</displayName>
        <description>Worklight: push notifications adapter</description>
        <connectivity>
            <connectionPolicy xsi:type="http:HTTPConnectionPolicyType">
                <protocol>http</protocol>
                <domain>localhost</domain>
                <port>7800</port>
            </connectionPolicy>
            <loadConstraints maxConcurrentConnectionsPerNode="1" />
        </connectivity>
    </wl:adapter>

Many of the values in this adapter XML file are configured from pattern parameters (for example displayName, domain and port).

The pattern also generates a JavaScript file that contains the notification adapter implementation. The key section in this generated file is at the top where the adapter configures the event source. The event source name must match with the event source name that the mobile application subscribes to.

    WL.Server.createEventSource({
        name : "PushEventSource",
        onDeviceSubscribe : "deviceSubscribeFunc",
        onDeviceUnsubscribe : "deviceUnsubscribeFunc",
        poll : {
            interval : 30,
            onPoll: "getNotifications"
        }
    });     

XML Schema

The XML schema shown below specifies the format of notification messages put on the queue and returned by the web service.

    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" attributeFormDefault="qualified" elementFormDefault="qualified" xmlns:tns="urn://patterns/worklight" targetNamespace="urn://patterns/worklight">
    
        <xsd:element name="GetNotification">
            <xsd:annotation>
                <xsd:documentation xml:lang="en">Request message to get the next available pending notification.</xsd:documentation>
            </xsd:annotation>
            <xsd:complexType>
                <xsd:sequence>
                    <xsd:element name="AdapterName" type="xsd:string"/>
                    <xsd:element name="EventSource" type="xsd:string"/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
    
        <xsd:element name="GetNotificationResponse">
            <xsd:annotation>
                <xsd:documentation xml:lang="en">Response message for next available pending notification.</xsd:documentation>
            </xsd:annotation>
            <xsd:complexType>
                <xsd:sequence>
                    <xsd:element name="Notification" type="tns:Notification"/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
    
        <xsd:element name="PutNotification">
            <xsd:annotation>
                <xsd:documentation xml:lang="en">Request message to add a pending notification message.</xsd:documentation>
            </xsd:annotation>
            <xsd:complexType>
                <xsd:sequence>
                    <xsd:element name="Notification" type="tns:Notification"/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
    
        <xsd:element name="PutNotificationResponse">
            <xsd:annotation>
                <xsd:documentation xml:lang="en">Response message for putting a pending notification messages.</xsd:documentation>
            </xsd:annotation>
            <xsd:complexType>
                <xsd:sequence>
                    <xsd:element name="AdapterName" type="xsd:string"/>
                    <xsd:element name="EventSource" type="xsd:string"/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
        
        <xsd:complexType name="Payload">
            <xsd:annotation>
                <xsd:documentation xml:lang="en">Application specific data in the notification messages.</xsd:documentation>
            </xsd:annotation>
            <xsd:sequence>
            </xsd:sequence>
        </xsd:complexType>
        
        <xsd:complexType name="Notification">
            <xsd:annotation>
                <xsd:documentation xml:lang="en">Data definition for notification messages.</xsd:documentation>
            </xsd:annotation>
               <xsd:sequence>
                  <xsd:element name="UserId" type="xsd:string"/>
                  <xsd:element minOccurs="0" name="Badge" type="xsd:string"/>
                  <xsd:element minOccurs="0" name="Sound" type="xsd:string"/>
                  <xsd:element minOccurs="0" name="ActivateButtonLabel" type="xsd:string"/>
                  <xsd:element minOccurs="0" name="NotificationText" type="xsd:string"/>
                  <xsd:element minOccurs="0" name="Payload" type="tns:Payload"/>
               </xsd:sequence>
        </xsd:complexType>
    </xsd:schema>

The Payload element is completed by the pattern with the names of any additional application specific fields.

An extract from the push notification web service WSDL is shown below.

    <wsdl:definitions name="Notification" targetNamespace="urn://patterns/worklight" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn://patterns/worklight" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <wsdl:types>
            <xsd:schema targetNamespace="urn://patterns/worklight" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
                <xsd:include schemaLocation="Notification.xsd"/>
            </xsd:schema>
        </wsdl:types>
        <wsdl:message name="GetNotification">
            <wsdl:part element="tns:GetNotification" name="GetNotification"/>
        </wsdl:message>
        <wsdl:message name="GetNotificationResponse">
            <wsdl:part element="tns:GetNotificationResponse" name="GetNotificationResponse"/>
        </wsdl:message>
        <wsdl:message name="PutNotification">
            <wsdl:part element="tns:PutNotification" name="PutNotification"/>
        </wsdl:message>
        <wsdl:message name="PutNotificationResponse">
            <wsdl:part element="tns:PutNotificationResponse" name="PutNotificationResponse"/>
        </wsdl:message>
        <wsdl:portType name="NotificationPortType">
            <wsdl:operation name="GetNotification">
                <wsdl:input message="tns:GetNotification"/>
                <wsdl:output message="tns:GetNotificationResponse"/>
            </wsdl:operation>
            <wsdl:operation name="PutNotification">
                <wsdl:input message="tns:PutNotification"/>
                <wsdl:output message="tns:PutNotificationResponse"/>
            </wsdl:operation>
        </wsdl:portType>
        <wsdl:binding name="NotificationSOAPBinding" type="tns:NotificationPortType">
            <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
            <wsdl:operation name="GetNotification">
                <soap:operation soapAction="http://notification/get"/>
                <wsdl:input>
                    <soap:body use="literal"/>
                </wsdl:input>
                <wsdl:output>
                    <soap:body use="literal"/>
                </wsdl:output>
            </wsdl:operation>
            <wsdl:operation name="PutNotification">
                <soap:operation soapAction="http://notification/put"/>
                <wsdl:input>
                    <soap:body use="literal"/>
                </wsdl:input>
                <wsdl:output>
                    <soap:body use="literal"/>
                </wsdl:output>
            </wsdl:operation>
        </wsdl:binding>
    </wsdl:definitions>

The adapter that is generated by this pattern uses the GetNotification operation to retrieve pending push notifications from Message Broker. The web service also provides a PutNotification operation. This operation is for provider applications that queue notifications with Message Broker by calling a web service instead of writing a message to a queue.

Back to the Worklight: push notification from WebSphere MQ pattern specification