Posted Apr 12 by Rhys Evans.
Updated Jun 20.

Native push notifications were introduced in version 16 of the AppWorks platform. The AppWorks Gateway can send notifications to registered clients, and the Android and iOS AppWorks mobile clients can receive and process them. This functionality leverages Google Cloud Messaging Services (GCM) to deliver notifications across both platforms seamlessly.

Last activity Jun 20 by Rhys Evans.
2293 views. 0 comments.

OpenText AppWorks 16 Notifications

Native push notifications were introduced in version 16 of the AppWorks platform. The AppWorks Gateway can send notifications to registered clients, and the Android and iOS AppWorks mobile clients can receive and process them. This functionality leverages Google Cloud Messaging Services (GCM) to deliver notifications across both platforms seamlessly.

Support for publication of notifications is provided by RESTful APIs exposed by the AppWorks Gateway and the AppWorks SDK. Support for client side (mobile) handling of notifications within AppWorks apps is provided by the appworks.js library. This document will cover both the creation and consumption of the native push notifications.

Who should read this?

This documentation can be used by AppWorks service developers to learn how to create and publish notifications via the AppWorks Gateway.

This documentation can be used by AppWorks app developers to learn how to respond to custom push notifications inside apps.

This documentation can be used by AppWorks Gateway administrators to provide an overview of the functionality, and its configuration.

This documentation can be used be integrators wishing the make use of the Gateway administration APIs for creating targeted push notifications.

AppWorks Notifications

The following diagram provides an overview of the AppWorks push notification implementation. As mentioned the feature is built on top of the public GCM service. The AppWorks Gateway fulfils the role of the GCM server, and the Android and iOS AppWorks mobile clients are the AppWorks GCM clients.

The GCM server is responsible for managing registered client's GCM tokens, it knows how to send native push notifications to the clients via the GCM service. The Gateway therefore offers the means to direct requests received at its APIs to the native clients. As AppWorks mobile clients are really containers for hybrid HTML+JS applications we allow push data to be targeted at specific AppWorks apps, this data can then be handled by developer's callback implementations via the appworks.js framework.

Creating notifications

The AppWorks Gateway exposes two RESTful endpoints for publishing push notifications. They actually appear in separate sections of the overall Gateway API, the 'administration API' and the 'deployments service API'.

  • The 'administration API' can be used by admin level Gateway users, usually via the AppWorks Gateway Administration Console, but could be used by an independent collaborating service that implemented its own client.
  • The 'deployments service API' is used exclusively by AppWorks services that use the AppWorks SDK and are deployed and managed within an AppWorks Gateway. AppWorks services are server side components that can be deployed and managed by the Gateway. They are structured Java web applications. The SDK library supplies and manages clients for working with this API from AppWorks services.

The AppWorks SDK provides a specific class and method to use the 'deployment service API' notifications endpoint

com.opentext.otag.sdk.client.v3.NotificationsClient#sendPushNotification

Both REST endpoints mentioned accept the SDK type

com.opentext.otag.sdk.types.v3.notification.ClientPushNotificationRequest

Publishing Routes

In integration scenarios we will usually see one of two approaches taken.

For the 'administration API' approach a collaborating system will retain a set of admin level credentials. Reusing these to establish an admin level session with the Gateway via a client they create. Re-authentication and retry mechanisms are usually employed by these clients as admin level tokens have a limited life span.

For the 'deployments service API' integrators will simply write a new AppWorks service that makes use of the AppWorks SDK tooling, programmatically making method calls via our supplied SDK clients. Full documentation for the AppWorks SDK is available.

Client Push Notification Request

As mentioned the ClientPushNotificationRequest is the request type the Gateway APIs expect to receive. It allows you to specify a notification/alert (title, message, to appear in the device's tray), some JSON data (max 4kb), and then recipients via a number of available fields.

It can be broken down into two sections as seen in the JSON example below. The notification section (title and summary) contains the native data as described in the section Native Alert Data. The second part is the “data” section, it allows us to “target” specific apps, passing them a “message” payload. The data section of AppWorks notifications is described more fully in the section AppWorks Notification Data.

{
   "title": "Alert Title",
   "summary": "Native tray message",
   "clientIds": [
     "b72715fc-3ae7-4191-b6b9-7e2ecdf7cdde",
     "3de0a166-da1d-4da7-b5ae-d5662afde9c9"
   ],
   "data": {
     "target": "activeDocuments",
     "created": 1459996759896,
     "message": "{ \"action\": \"doSyncData\"}"
  }
}

Example of a typical request using clientIds

Recipients

The above example only shows one way of identifying users, clientIds. There are actually many more options as described next. We also cover how to retrieve some of this data via the Gateway APIs later on.

Depending on the user data your admin API client or AppWorks service has access to you may have to use a specific recipient field. You can also use multiple recipient fields, apart from broadcast which overrides the individual entries found in the other recipient related fields.

The recipient fields are as follows:

  • Client identifiers: clientIds identify specific clients
  • Runtimes: runtimes identify users of specific AppWorks mobile clients
  • User identifiers: users resolved against OTDS
  • OTDS Group identifiers: otdsGroups
  • A broadcast Boolean flag: broadcast is available

Clients represent a specific user connected to the Gateway via a specific mobile Runtime, the Gateway stores Client details when a login request is authenticated. Runtimes pass client data with the login request, and include the GCM registration token if they have one.

Note:
Only Client rows which have a valid GCM token are eligible for push notifications.

All recipients (despite the different recipient fields) are actually retrieved from the clients table in the Gateway database. A clientId is the unique identifier on the Client table, so the list of client ids can be used to perform a direct lookup. See Getting Client Ids for more details on how these can be retrieved.

Runtimes are specific client applications of the Gateway, they identify their users to the Gateway as part of the login request they form on behalf of a user, inserting their unique Runtime identifier into the Client data. An example of a Runtime is our AppWorks iOS client, the Android client is also a Runtime. We can specify in the notification request that all users of a specific Runtime should receive a push notification. Retrieval of Runtimes is detailed here.

Specific user identifiers for known Gateway users can be supplied, and should contain the Open Text Directory Services (OTDS) partition i.e. user@partition, as this is how Client data is recorded on authentication. Finally the OTDS Groups found via the request (we do the OTDS search server side) will have each of their users queried to see if they have an eligible row in the Client table via their user id.

Backup of notification data

Once sent by the Gateway all notification requests are written to persistent storage. This means clients can poll for this notification data if they need to via a notifications Gateway endpoint (not exposed via REST). The AppWorks mobile clients actually use both long polling and GCM to give a consistent view of the data. This also provides consistency across the platform allowing non-GCM-enabled vendor devices to consume AppWorks notifications. The Gateway does not retain the notification data indefinitely and periodically removes data once we accumulate a large enough data set.

Gateway API flow

Once you have an AppWorks Gateway setup hit http://yourhost:port/apidocs to see the Swagger documentation. Note, the 'administration API' as denoted by adminAPI seen in the section title. The 'deployments service API' is denoted by deploymentsServiceAPI in the Swagger docs.

Getting client Ids

adminAPI/clients

As an admin level user you can use the client search to get back the clientId for a user directly as shown below. The term parameter can contain the users userId, firstName or lastName, and can include the wildcard character * to refine the search.

Getting Runtimes

adminAPI/runtimes

You can search for Runtimes to send a notification to, note this also available to the AppWorks Services via the supplied SDK com.opentext.otag.sdk.client.v3.RuntimesClient. The Runtime name shown in the response model can be used in the ClientPushNotificationRequest.

OTDS groups

adminAPI/useradmin

The administration API also offers group search as below. Set the search type parameter to group to limit the results. The group id recipient field of the ClientPushNotificationRequest allows us to hit a wide number of targeted users at once.

Push Notification Request

adminAPI/push

As mentioned this route is also available via the SDK com.opentext.otag.sdk.client.v3.NotificationsClient. The broadcast flag can be seen here, when used ALL clients (that have a GCM token) that have connected within the last 6 months will be sent the message.

Gateway Console Notifications Testing

The Gateway administration console also supplies push notification testing features. It provides a page that will send a ClientPushNotificationRequest using data entered into a test form. The form itself is split into two distinct sections, data handled outside of the AppWorks client, and data handled inside and potentially by AppWorks apps.

This division was apparent when we first looked at the structure of the push notification request the Gateway accepts.

Native Alert Data

The information entered in this section will be visible on the notification that is shown in the hosting mobile devices notification tray, via the native alerting mechanism (banners on iOS for instance), or on connected peripherals such Apple Watches.


Admin Console Push Notification Testing


Delivery of the native part of the notification on iOS

AppWorks Notification Data

This section offers the AppWorks specific functionality. The data is processed inside the AppWorks mobile client. This content is described in detail in the request structure. The test form features are described next.

A Data Payload can be included which can be an arbitrary JSON object understood by an AppWorks app. More on this is in the client side developer section.

A Target AppWorks App, when used this will indicate that the notification is intended for the selected app. When the notification is opened by the AppWorks mobile client upon pressing it the user will be taken to the AppWorks app and any data payload will be passed to any handlers implemented within the app using appworks.js.

The form also provides features to find notification recipients. The search by username/first name/last name will return users client entries that have a valid GCM token, and will order them by last connect. We also allow multi-selection (see screenshot below) and include the device type to let you differentiate between clients.


Test Form AppWorks Data Section


Select a specific app to deliver your notification to


Notification recipient search with multi-selection


Using the Starter App we can get notification data sent from the test form

Processing Notifications in AppWorks Apps

In order to process AppWorks notifications the appworks.js library must be used. The full documentation on the notifications management can be found here. The AWNotificationManager is offered by appworks.js for this specific purpose.

When a targeted notification is received it can be actioned from the native tray or from within the notifications areas of the AppWorks mobile client. Upon doing so the AppWorks mobile client should open the target app, and offer data to it if any was contained in the notification.

Operations include:

  • enablePushNotifications: enable real-time notifications in app
  • disablePushNotifications: turn off real time notifications
  • getNotifications: get all notifications for the app
  • openListener: create a listener to handle times when an actioned notification opens the app
  • getOpeningNotification: get the data that was passed when a notification opened the app

AWNotificationManager basics

Here are some of the basics of working with the AWNotificationManager.

Getting the AWNotificationManager for your app

This is provided by the main AppWorks appworks.js object.

var notificationManager = new Appworks.AWNotificationManager();

Getting existing notification data for your app.

Manually retrieve any notifications that are waiting for the app in the AppWorks clients native layer. Notifications can be delivered when the target app is closed, once started these notifications can be accessed.

notificationManager.getNotifications(function (notifications) {
  console.log(notifications);
  _this.notifications = notifications;
});

Handling notification data.

To handle notifications call the managers enablePushNotifications function passing your success and error handling functions. The data contained in the message section of the request the Gateway received will be passed to the success function.

notificationManager.enablePushNotifications(
  function (notification) {
    // handle the new notification
    console.log(notification);
  }, errorHandler);

GCM Configuration

The AppWorks Gateway provides a configuration screen to store the Google project details for particular Runtimes. The Runtimes represent specific variations of the AppWorks mobile client that can make use of the GCM features, they are linked to a specific project registered with Google. We need to store certain details at the Gateway so it can recognize client:runtime associations and send the messages to the client using the correct GCM API key, the mobile clients also need to know some of these details.

Note:
GCM is handled automatically for you when using the standard AppWorks mobile clients - a default set of values is shipped with the Gateway.

In the screenshot of the AppWorks Gateway Administration Console below we can see three values, one each for the standard Android and iOS AppWorks mobile clients, and then an enterprise version of the iOS client. These are provided by default and are supplied in the awg-keystore JKS file included with the AppWorks Gateway zip. These values can be reinstated if removed by using the file that came with the Gateway, just stop the Gateway, overwrite the file and restart. Please note any changes you made previously will be lost.

New values can be added for new versions of the clients, such as the single app variants produced by the client packager service. New Google project details will be required and the mobile client should have a unique Bundle/Package Id. See below for Google project setup, and more details on this.

GCM Token Rotation

GCM tokens are issued to clients from the central GCM service, this is known as registration. They use specific Google project information to request a token for use with a particular GCM server, the Gateway in this case. These tokens do not last forever and for security reasons we rotate them regularly forcing the client to re-register. This can however be performed manually via the AppWorksGCM tokens are issued to clients from the central GCM service, this is known as registration. They use specific Google project information to request a token for use with a particular GCM server, the Gateway in this case. These tokens do not last forever and for security reasons we rotate them regularly forcing the client to re-register. This can however be performed manually via the AppWorks Gateway Administration Console as shown in the screen shot.

Note:
The GCM Token rotation UI is revealed by enabling the AppWorks Gateway Console Developer Mode via the Settings administration area of the AppWorks Gateway Console. It can be found on the General Settings tab.


Gateway GCM Configuration Screen

Google Project Setup

The Google Developer Console is used to configure a project for GCM. A regular Google account is all that is required.

Once inside the console new projects can be setup very easily. As mentioned this is usually part of the custom client build process that is orchestrated by the client packager service. This service as well as the Gateway will require the project details. Google Cloud Messaging will also need to be enabled for the project.

We are interested in the Project Name, Project Number, API Key and the bundle id. The bundle id is configured via the packaging service and is a unique identifier for the AppWorks mobile client variant. Some of these values are embedded in the client in the custom packaging process enabling the push notification communications. Android and iOS are supported by the client packaging service.

The following screen shots show key areas of the Google developer console that contain the information we need.


Google Developer Console, select Google Cloud Messaging


GCM credentials (API key)


Access Project Information


Project Information

About OpenText

OpenText™ (NASDAQ: OTEX, TSX: OTC) is a global leader in Enterprise Information Management (EIM). OpenText is enabling the digital world by creating a better way for organizations to work with information and achieve-actionable results.

OpenText is driving the digital transformation our customers need to better manage information, better integrate their business networks and make better business decisions with analytics. The OpenText EIM strategy enables organizations to discover and manage information to spur growth and innovation, and decrease time to competitive advantage. OpenText is enabling the digital world for more than 100,000 customers, with the OpenText Cloud processes over 18 billion transactions per year for more than 64,000 customers around the world. OpenText solutions consist of four on-premises suites representing the next generation of innovation in Enterprise Content Management (ECM), Business Process Management (BPM), Customer Experience Management (CEM) and Analytics.

OpenText's next generation of Enterprise Information Management (EIM) solutions address key business goals that drive digital transformation, and are designed for deployment in the cloud, on-premises and in hybrid (cloud and on-premises) environments.

Contact information

OpenText Corporation

275 Frank Tompa Drive
Waterloo, Ontario
Canada, N2L 0A1

Support: https://support.opentext.com

Knowledge Center: https://knowledge.opentext.com

For more information, visit www.opentext.com

Copyright © 2016 Open Text SA and/or Open Text ULC. All Rights Reserved.


Table of Contents