Configuring Push Notification to Run within Oracle Mobile Application Framework

This topic provides an overview and describes the tasks to complete to enable push notifications to run within the Oracle Mobile Application Framework (MAF) on mobile devices, such as smartphones and tablets.

PeopleTools enables the Push Notification Framework to allow the PeopleSoft server runtime to push real-time notifications to MAF applications running on Android and iOS devices. The following example depicts the sequence of interaction for mobile devices configured for MAF and the PeopleSoft system.

Image: Push Notification using MAF

This example illustrates the sequence of events for establishing push notifications on a mobile device. The high level steps are described below.

Push Notification and MAF Architecture

Field or Control

Definition
1

MAF application registers with the push notification provider: Google Could Messaging (GCM) for Android or Apple Push Notification service (APNs) for iOS.
2

MAF application receives the registration ID (or device token) from the provider.
3

Mobile device passes registration ID to the PeopleSoft server.
4

When a defined server event occurs, PeopleSoft server runtime sends notification to the push notification providers.
5

Push notification provider pushes the notification to the MAF application.

Before you get started configuring push notifications for PeopleSoft on mobile devices, you need to:

  • Enable Integration Broker.

    See PeopleSoft Integration Broker Administration Overview.

    Note: If the application server is running inside a secure private network (such as VPN), the proxy server host and port needs to be configured in the Integration Broker Gateway configuration properties file. This is essential for the PeopleSoft server runtime to connect to the APNs server, which listens on particular port numbers that may be blocked by the internal firewall.

  • Install the MAF elements provided with your PeopleTools license.

    See Understanding Mobile Application Framework Support for PeopleSoft.

Depending on your mobile device operating system, you will need a set of attributes related to your MAF application to configure push notification for your PeopleSoft application.

Required Attributes for Android

For the Android device, you need to provide these MAF application attributes:

  • Application Name

  • GCM Project Number

  • GCM API Key

The GCM Project Number for a MAF application is embedded into the application when it is packaged. The GCM API Key is used to establish connection to the provider. These attribute values are generated through Google API Console.

Required Attributes for iOS

For the iOS device, you need to provide these MAF application attributes:

  • Application Name

  • APNs Bundle ID

  • APNs Certificate (.p12 file)

  • APNs Certificate password

The APNs Bundle ID is a unique identifier provided by Apple for the MAF application, which is embedded into the application when it is packaged. PeopleSoft server runtime requires the APNs SSL Certificate (.p12 file) and the Certificate password to establish connection to the APNs server to send the notification. The APNs SSL Certificate is generated through iOS provisioning portal.

Access the Configure MAF Applications page to register your MAF applications within PeopleSoft.

PeopleTools > Push Notifications > Mobile Notifications > Configure MAF Applications

Image: Configure MAF Application page

This example illustrates the fields and controls of the Configure MAF Application page.

Configure MAF Application page

Add the MAF Application Name for your application, and also add the required attributes for the provider through which you will receive push notifications on your MAF application running on a device.

If your MAF application is running on an android device, then you need to configure the GCM (Google Cloud Messaging) attributes for the MAF application, such as, GCM Project Number and GCM API Key.

If your MAF application is running on an iOS device, then you need to configure the APNs (Apple Push Notification service) attributes for the MAF application, such as, APN Bundle ID, APN Private Key File Name, and APN Private Key Password.

Note: The GCM settings, discussed earlier, are also applicable if you are using Firebase Cloud Messaging (FCM), which is the new version of GCM.

See Gathering Push Notification Provider Information.

Use the Push Notification administrator credentials to configure MAF applications: user ID PTPNADMIN with password PTPNADMIN. The PTPNADMIN user ID has as one of its roles, PN Administrator (Push Notification Administrator).

The Push Notification administrator can enable or disable push notifications to the configured MAF application by selecting or deselecting the Enabled check box.

For APNs registration, you need to update the Integration Broker gateway properties file also. The exact path where the APNs Private key file is stored should be assigned to the ig.apnKeyStorePath property. For example:

ig.apnKeyStorePath=/usr/opt/APN

Configuring Push Notifications to Google Cloud Messaging (GCM) Through An HTTPS Connection

PeopleSoft provides an Integration Broker service operation — PTPN_GCM_OPERATION_POST — to post push notifications to the Google Cloud Messaging (GCM) server.

To configure an HTTPS connection, complete the following steps:

  1. Select PeopleTools > Integration Broker > Integration Setup > Service Operations, and select the PTPN_GCM_OPERATION_POST service operation.

  2. On the Service Operations page, in the REST Resource Definition area, set the REST Base URL field to https://gcm-http.googleapis.com.

  3. Add a certificate in the Integration Gateway key store that validates the GCM SSL certificate because Integration Gateway needs to validate the SSL certificate of the GCM server.

    • Navigate to the location where the Integration Gateway key store is located — (PS_CFG_HOME/webserv/peoplesoft/piaconfig/keystore).

    • Use the keytool utility to import the certificate into the key store. For example, if the certificate name is geotrustca.cer, your command will be similar to the following.

      keytool -import -alias geotrust -file geotrustca.cer -keystore pskey

The PeopleSoft server runtime sends push notifications to MAF applications using adapters. An adapter is a PeopleCode application class that uses delivered Push Notification Framework application classes to send push notifications to MAF applications.

For more information on Push Notification Framework PeopleCode, see Understanding the PSEvent Class.

The following example illustrates an adapter class implemented for a PeopleSoft push notification event named SENDNOTE. Extensive comments are given in this example so that it can be used as a reference for writing adapter classes.

<* This is an example adapter class for pushing event: SENDNOTE to
MAF application. 

Developers can use this class as a reference to implement custom adapter
classes for their events. 

A custom adapter class extending from "MAFApplicationAdapter" should
have a constructor and implement the method "onNotification".  *> 

import PTPN_ADAPTERS:MAFApplicationAdapter; 

class SendNoteAdapter extends PTPN_ADAPTERS:MAFApplicationAdapter 

    method SendNoteAdapter(); 

    method onNotification(&eventObject As PSEvent); 

end-class; 

 

<* Invoke MAFApplicationAdapter constructor by passing the MAF application
name, to which push notifications for SENDNOTE event is to be sent
and the fully qualified  name of the adapter class.  *> 

method SendNoteAdapter

    %Super = create PTPN_ADAPTERS:MAFApplicationAdapter("PeopleSoft",
"PTPN_ADAPTERS:SendNoteAdapter");
end-method; 

 

<* onNotification method will receive the published event instance:
eventObject. 

Developers can use methods in PSEvent class to retrieve data from
the published event instance. 

Use MAFApplicationAdapter methods and properties to set notification
data and send the push notification to the MAF application. 

SendNotification method will return an error text incase of failures.
Refer PeopleBooks for methods and properties of PSEvent class. *> 

method onNotification      /+ &eventObject as PSEvent +/;       Local
string &alert;      Local string &eventDataKey = "DETAIL";      Local
string &response;      &alert = &eventObject.GetValueOfKey(&eventDataKey);
 %Super.SetAlert(&alert);      &response = %Super.SendNotification(); 

end-method;

The MAFApplicationAdapter class provides the following methods to construct a push notification to a MAF application.

API

Description

SetAlert(alert_text)

Alert text will be displayed as an alert message on the device receiving the notification.

SetSound(sound_file)

Plays an alert sound on the device receiving the notification.

For example:

SetSound("default")

SetIOSBadge(badge_number)

Displays the badge-number on the device, which receives the notification (works only on iOS devices).

For example:

SetIOSBadge(1)

SetUrl(url)

Sends a URL as part of the notification payload in the case where the user may have to navigate to a page to perform a task based on the notification.

PeopleTools > Push Notifications > Define Server Events > Click the Adapter icon

Image: Associating an Adapter to an Event

This example illustrates the fields and controls on the page used to associate adapters to events.

Associating an adapter to an event

After clicking the Adapter icon for the desired event, use the Adapter drop-down to select the appropriate adapter. Add rows as needed.

The adapter will be executed when a selected event occurs in the PeopleSoft application server run-time.

To enable notifications to a device use the Enable Notifications page.

PeopleTools > Push Notifications > Mobile Notifications > Enable Notifications

Image: Enable Notifications Page

This example illustrates the fields and controls on the Enable Notifications page.

Enable Notifications page

PeopleSoft administrators can configure which push notification events can send notifications to the MAF application.

After each user downloads the MAF application and registers for push notifications, their provider sends a device token and device information, which is passed to the PeopleSoft system when the user signs in. The device token and device information is stored in the PeopleSoft system and is displayed on the Register Device page.

Access PeopleTools > Push Notifications > Mobile Notifications > MAF Register Device

Image: Register Device Page

This example illustrates the fields and controls of the Register Device page.

Register Device page