Implementing Push Notifications

Overview

Oracle E-Business Suite provides support for push notifications from Oracle E-Business Suite Mobile Foundation Release 7.0 and onwards. In order for users of the supported mobile apps to receive push notifications on their mobile devices, besides the setup tasks completed by administrators, as described in the Setting Up and Enabling Push Notifications for Oracle E-Business Suite Mobile Apps, Oracle E-Business Suite Mobile Apps Administrator's Guide, Release 12.1 and 12.2, you need to perform some tasks both on the Oracle E-Business Suite server and on the mobile client.

Important: Standard Oracle E-Business Suite mobile apps installed directly from the Apple App Store or Google Play do not support push notifications. Push notifications are supported when using Oracle Mobile Hub (OMH) or Oracle Mobile Cloud Service (MCS) in the following apps. Note that in addition to MCS, from Oracle E-Business Suite Mobile Foundation Release 9.0 and onwards, Oracle Mobile Hub provides support for push notifications through Patch 33404902:R12.FND.C for Oracle E-Business Suite 12.2, and Patch 33404902:R12.FND.B for Oracle E-Business Suite 12.1.3.

Oracle Mobile Approvals for Oracle E-Business Suite, when provided to users through enterprise distribution
Custom Oracle E-Business Suite mobile apps developed using the Login component from Oracle E-Business Suite Mobile Foundation

See: Using the Login Component to Develop Mobile Apps.

Push notifications require enterprise distribution due to iOS requirements. The provisioning profile used to build the iOS app and the certificate and private key presented by the Oracle E-Business Suite server to send the push notifications are specific to the iOS app to be used in your organization; therefore, you must obtain your own profile and certificate from the Apple Developer Program. You can then use these to build and deploy the iOS app through enterprise distribution.

For information on replacing bundle ID or package name in the platform-specific deployment profile, see Modifying an Existing Deployment Profile (Conditional).
For more information about push notifications, see Understanding Oracle E-Business Suite Mobile Foundation Push Notification System, Oracle E-Business Suite Mobile Apps Administrator's Guide, Release 12.1 and 12.2.
For more information on enterprise distribution, see Using Mobile Application Archives for Enterprise Distribution.

For information on troubleshooting issues related to the setup or processing of push notifications, see Troubleshooting Tips for Push Notifications, Oracle E-Business Suite Mobile Apps Administrator's Guide, Release 12.1 and 12.2.

Performing Server-Side Tasks to Send Push Notifications to Mobile Apps

In order for the Oracle E-Business Suite server to send push notifications to the supported mobile apps, you must complete the following tasks:

Creating Push Notification Business Events

Push notification messages are delivered to mobile devices by Oracle E-Business Suite application code through the use of business events. Each mobile app is associated with its own business event to trigger push notifications. Oracle E-Business Suite application code raises the app-specific business event based on which the Oracle E-Business Suite Mobile Foundation Push Notification System processes the notifications and delivers them to the mobile devices.

To create the push notification business event for an app, you need to log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility. For information on creating a business event, refer to the Oracle Workflow Developer Guide.

The business event you defined in Oracle Workflow will be used as the "Push Notification Business Event" parameter, one of the configuration parameters for the "Push Notifications" category when configuring a mobile app in the Configuration Categories region or registering the application definition metadata in the Configuration Details page through the Mobile Applications Manager responsibility.

Configuration Details Page with "Push Notification Business Event" Parameter Highlighted

the picture is described in the document text

For example, the enterprise version of the Approvals app (Oracle Mobile Approvals for Oracle E-Business Suite) uses the standard business event oracle.apps.mobile.approvals.push.event to trigger push notifications. Note that this event is already seeded and included in the seeded event group for the Push Notification System. You do not need to create the event when enabling push notifications for the enterprise-distributed Approvals app.

Adding the Push Notification Business Events to the Push Notification System's Event Group

After successfully creating the push notification business event corresponding to the supported mobile app, you need to add the newly-created event to the seeded Push Notification System's event group oracle.apps.mobile.foundation.push.group as part of the Oracle E-Business Suite Mobile Foundation Push Notification System to which all push notification business events should be added.

Note: This seeded event group already includes the app-specific standard push notification business event, such as oracle.apps.mobile.approvals.push.event for Oracle Mobile Approvals for Oracle E-Business Suite.

To add a business event to a group, you need to log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility. For more information, refer to the Oracle Workflow Developer Guide.

Sending Push Notifications to Mobile Devices

Oracle E-Business Suite Mobile Foundation Push Notification System provides a PL/SQL API to send push notifications to a given mobile app user. The Push Notification System identifies all the mobile devices that the user has registered to receive push notifications and then sends the same notifications to all registered devices.

For example, if a mobile user <FIRST_NAME>.<LAST_NAME> has installed an enterprise-distributed Approval app that is enabled with push notifications on two iOS devices and one Android device. All the three devices are connected to the same Oracle E-Business Suite server. If a push notification is sent to the enterprise-distributed Approvals app for the user, it is delivered to all the three devices by the Push Notification System.

The PL/SQL API signature is as follows:

procedure Send (p_event_name in VARCHAR2,
                  p_recipient in VARCHAR2,
                  p_subject in VARCHAR2,
                  p_title in VARCHAR2,
                  p_sound in VARCHAR2 default null,
                  p_badge in VARCHAR2 default null,
                  p_params in wf_parameter_list_t)

The following code snippet shows the sample usage of sending push notifications to the enterprise-distributed Approvals app:

declare
  -- Replace the text <FIRST_NAME>.<LAST_NAME> with actual recipient of Push Notification
  l_recipient_role varchar2(320) := '<FIRST_NAME>.<LAST_NAME>';
  -- Replace the number 111111 with actual notification ID
  l_nid number := 111111;

  -- Push Notification event used while registering the App in Mobile Applications 
  -- Manager. 
  l_event_name varchar2(100):= 'oracle.apps.mobile.approvals.push.event';
  l_parameterlist wf_parameter_list_t := wf_parameter_list_t();
  l_subject varchar2(1000);
  l_status varchar2(100);
    
  l_orig_lang varchar2(64); 
  l_orig_terr varchar2(64); 
  l_orig_chrs varchar2(64); 
  l_orig_date_format varchar2(64); 
  l_orig_date_language varchar2(64); 
  l_orig_calendar varchar2(64); 
  l_orig_numeric_characters varchar2(64); 
  l_orig_sort varchar2(64); 
  l_orig_currency varchar2(64); 
  l_orig_client_timezone varchar2(64);
  l_recip_lang  varchar2(64);
  l_recip_terr varchar2(100); 

begin

       select status 
       into l_status
       from wf_events 
       where name=l_event_name;
    
      if (l_status <> 'ENABLED') then 
        return; 
      end if;
      
      -- Sending translated push notification message
      -- Step 1 - Retain original NLS context 
      wf_notification_util.getNLSContext(p_nlsLanguage => l_orig_lang, 
                                         p_nlsTerritory => l_orig_terr, 
                                         p_nlsCode => l_orig_chrs, 
                                         p_nlsDateFormat => l_orig_date_format, 
                                         p_nlsDateLanguage => l_orig_date_language, 
                                         p_nlsNumericCharacters => l_orig_numeric_characters, 
                                         p_nlsSort => l_orig_sort, 
                                         p_nlsCalendar => l_orig_calendar,
                                                                                                                 p_clientTimezone => l_orig_client_timezone);

      -- Find out mobile user's device language and territory preference
      l_recip_lang := fnd_mbl_notification.GetDeviceLang(l_recipient_role, l_event_name); 
      l_recip_terr := fnd_mbl_notification.GetDeviceTerr(l_recipient_role, l_event_name); 
          
      -- Set NLS context to that of the push notification recipient. Only  language and
      -- territory are available from device registration, for rest of the NLS context,leave it to DB default    
      wf_notification_util.SetNLSContext(p_nlsLanguage => l_recip_lang,
                                         p_nlsTerritory => l_recip_terr);
                                                                                 
      -- Get subject in recipient's NLS context          
      l_subject := wf_notification.GetSubject(l_nid, 'text/html');
                 
      -- Reset to original NLS context 
      wf_notification_util.SetNLSContext(p_nlsLanguage => l_orig_lang, 
                                         p_nlsTerritory => l_orig_terr, 
                                         p_nlsDateFormat => l_orig_date_format, 
                                         p_nlsDateLanguage => l_orig_date_language, 
                                         p_nlsNumericCharacters => l_orig_numeric_characters, 
                                         p_nlsSort => l_orig_sort, 
                                         p_nlsCalendar => l_orig_calendar,
                                                                                                                 p_clientTimezone => l_orig_client_timezone);
                                        
      wf_event.AddParameterToList('WF_NOTIFICATION_ID', to_char(l_nid), l_parameterlist);
      fnd_mbl_notification.Send(p_event_name => l_event_name, 
                                p_recipient => l_recipient_role, 
                                p_subject => l_subject,
                                p_title => null,
                                p_params => l_parameterlist);
end;
/
commit;

Note: In this sample code, the NLS context is changed to the language of the mobile app user's device locale to translate the message. If the mobile app user's language is not supported by Oracle E-Business Suite, then the message is sent in the base language.

Sending Notification Identifier

When a push notification is sent to a mobile device, in addition to displaying the notification subject shown as the message to the mobile user, you can send internal values regarding that specific notification that can be used by the mobile app code for further processing. For example:

For the enterprise-distributed Approvals app, when a push notification is sent for an approval request, the Workflow Notification ID (WF_NOTIFICATION_ID as shown in the sample code) corresponding to that approval can be sent along with the push notification message. This allows the app to use that ID to fetch the notification details and then in turn allows the user to drill down to the notification details page.
For an offline mobile app, such as Oracle Mobile Field Service, if data is updated on the server, a signal can be sent through the push notification message to trigger the mobile app to redownload the data from the server.

Performing Client-Side Tasks to Receive Push Notifications in Mobile Apps

In order for Oracle E-Business Suite mobile apps to receive push notifications, you must complete the following tasks on the mobile client:

Enabling the Push Plug-in

Push notifications are currently supported when using Oracle Mobile Hub (OMH) from Release 9.0 and onwards with a patch applied or using Oracle Mobile Cloud Service (MCS) for custom mobile apps developed using Oracle E-Business Mobile Foundation as well as for the Approvals app when provided to users through enterprise distribution.

For information about the patch of using Oracle Mobile Hub from Oracle E-Business Suite Mobile Foundation Release 9.0, see Implementing Push Notifications.

To allow these mobile apps to receive push notifications on the mobile devices, you should enable the Push plug-in for the corresponding Mobile Application Framework (MAF) project.

Instructions to Enable the Push Plug-in

After you have created the MAF project for your mobile app, perform the following tasks to enable the Push plug-in:

Open Oracle JDeveloper.
In the Applications Navigator, expand the Application Resources panel, then the Descriptors folder, and then the ADF META-INF folder.

Double-click the maf-application.xml file to open the overview editor for the maf-application.xml file.
Select the Plugins navigation tab.
In the Core Plugins region, select the PushPlugin check box to enable the Push plug-in.

Note: The PushPlugin check box is unselected by default in the Mobile Application Archive (MAA) file.

Plugins Tab: Core Plugins Region with PushPlugin Selected
Save your work.

This enables the MAF application to first register for push notifications with Oracle E-Business Suite and then receive push notifications.

Migrating to Firebase Cloud Messaging (Android Only)

For push notifications on Android, Oracle E-Business Suite mobile apps use Firebase Cloud Messaging (FCM) to replace Google Cloud Messaging (GCM), which has been deprecated by Google. To migrate to FCM, follow the instructions provided by Google at https://developers.google.com/cloud-messaging/android/android-migrate-fcm. After completing the migration or creating a new FCM app, download the generated google-services.json file to the root directory of your mobile app (parallel to the ViewController and ApplicationController directories), as demonstrated by the following example.

MAFappRootDirectory
  MAFapp.jws
  ApplicationController
  ViewController
  google-services.json
  ....

This completes the migration of your Oracle E-Business Suite mobile apps to use FCM.

Handling Push Notifications (Optional)

When a push notification arrives on a mobile device, the mobile device's user can view the notifications in the notification center. When the user selects the notification from the notification center, the device opens the mobile app corresponding to that notification. When the mobile app is launched through a selection of a push notification, instead of launching the app in a regular way through the landing page, you can optionally choose to perform some notification handling tasks to let the app directly launch the mobile app page where it displays the appropriate details corresponding to that push notification.

Take an enterprise-distributed Approvals app as an example. A manager receives a push notification "Expense Report W1234 for $500.00 is submitted for approval". When the manager selects that notification from the notification center, the Approvals app displays the Expense Report approval notification details. If you choose not to handle the notifications, the app will be launched normally by taking the user to the regular landing page.

Although handling push notifications is an optional task, from the user experience perspective, it is important for a user to quickly navigate to an appropriate page to obtain the message details when the app is launched through a push notification.

Instructions to Handle Push Notifications

Perform the following tasks to allow your mobile app to handle the push notifications and guide the app users to an appropriate mobile page:

Note: Oracle E-Business Suite mobile apps that implement push notifications using enterprise distribution from the associated MAA files have already completed this optional task. The instructions described here only apply for the custom smartphone apps.

Note: Push notifications cannot be tested in iOS simulator or Android emulator. Instead, you need to install the app on a mobile device to test push notifications.

Implementing the PushEventListener Interface

The PushEventListener interface provides method onMessage(Event) that should be implemented by the mobile app to handle push notifications. The push notification message is available in the Event object.

The following code snippet shows the sample implementation of the enterprise-distributed Approvals app:

package oracle.apps.fnd.mobile.approvals;

import oracle.adf.model.datacontrols.device.DeviceManagerFactory;
import oracle.adfmf.framework.api.AdfmfContainerUtilities;
import oracle.adfmf.framework.event.Event;
import oracle.adfmf.json.JSONException;
import oracle.adfmf.json.JSONObject;
import oracle.apps.fnd.mobile.common.notifications.PushEventListener;
import oracle.apps.fnd.mobile.common.utils.AppLogger;
import oracle.apps.fnd.mobile.common.utils.AppsUtil;

public class ApprovalsPushMsgLsnr implements PushEventListener {
    
    public ApprovalsPushMsgLsnr() {
        super();
    }

    @Override
    public void onMessage(Event event) {
        JSONObject obj;
        try {
            obj = new JSONObject(event.getPayload());
            String deviceOS = DeviceManagerFactory.getDeviceManager().getOs();
            String subject = "";

            // Read push notification message
            if ("iOS".equals(deviceOS)){
                subject = obj.getJSONObject("alert").getString("body");
            }else{
                subject = obj.getString("alert");
            }

            // Read the notification identifier associated to the push notification
            String notificationID = obj.getJSONObject("data").getString("WF_NOTIFICATION_ID");

            // App feature to go to when notification is pressed. Take user to approval details page.
            // Implementation to navigate to a given page can differ from app to app.
            // Set required input param values to application scope that can be used for navigation later.
            AppsUtil.setELString("#{applicationScope.notificationID}", notificationID);
            AppsUtil.setELString("#{applicationScope.subject}", subject);

            // Navigate to required app feature corresponding to the notification identifier
            if(event.getApplicationState() != Event.APPLICATION_STATE_FOREGROUND){
                AdfmfContainerUtilities.resetFeature("oracle.apps.fnd.mobile.approvals.Approvals", false);
                AdfmfContainerUtilities.gotoFeature("oracle.apps.fnd.mobile.approvals.Approvals");
            }            
        } catch (JSONException e) {
            AppLogger.logError(ApprovalsPushMsgLsnr.class, "onMessage", AppsUtil.message(e));
        }
    }
}

Instantiating the PushEventListener Object

Once the PushEventListener interface is implemented, instantiate the PushEventListener object in your app's lifecycle listener.

package oracle.apps.fnd.mobile.approvals;
import oracle.apps.fnd.mobile.common.login.CCLoginLifeCycleListenerImpl;
import oracle.apps.fnd.mobile.common.notifications.PushEventListener;
import oracle.apps.fnd.mobile.common.utils.AppLogger;

public class ApprovalsLifeCycleListener extends CCLoginLifeCycleListenerImpl {

    public ApprovalsLifeCycleListener() {
    }
    public void start() {
        super.start();
    }
    public void stop() {
        // Add code here...
    }
    public void activate() {
        // Add code here...
    }
    public void deactivate() {
        // Add code here...
    }
    public PushEventListener registerPushListener() {
        return new ApprovalsPushMsgLsnr();
    }
}

The application lifecycle listener described above extends the Oracle E-Business Suite Mobile Foundation Login Component's oracle.apps.fnd.mobile.common.login.CCLoginLifeCycleListenerImpl; and should be configured in your app's maf-application.xml file.