Setting Up Push Notifications for Mobile Apps

Overview

This chapter explains the concept and architecture of Oracle E-Business Suite Mobile Foundation Push Notification System (or the Push Notification System thereafter) and the required configuration tasks to enable this feature for the supported mobile apps. Specifically, this chapter includes the following topics:

• Understanding Oracle E-Business Suite Mobile Foundation Push Notification System

• Setting Up and Enabling Push Notifications for Oracle E-Business Suite Mobile Apps

Understanding Oracle E-Business Suite Mobile Foundation Push Notification System

What is a push notification?

Push notifications are messages that a server can send to the mobile devices to inform the mobile app users of some events. For example, when a new expense report is submitted to an approver for approval, the Oracle E-Business Suite server can send a push notification to the approver's mobile device where the Approvals mobile app is installed. This helps to inform the approver of the new expense report for timely approval. These notifications can appear as alerts or banners based on the state of the app and the notification settings.

Starting from Oracle E-Business Suite Mobile Foundation 7.0 and onwards, you can optionally set up and enable push notifications for supported Oracle E-Business Suite mobile apps.

Important: 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, starting 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, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.

Standard Oracle E-Business Suite mobile apps installed directly from the Apple App Store or Google Play do not support push notifications.

Note that 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 editing application bundle ID or package name in the platform-specific deployment profile, see Modifying an Existing Deployment Profile (Conditional), Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.

• For information about enterprise distribution, see Using Mobile Application Archives for Enterprise Distribution, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.

What is Oracle E-Business Suite Mobile Foundation Push Notification System?

In order for the Oracle E-Business Suite server to send push notifications to the mobile devices of designated mobile app users, the server must have a way to identify those users and to deliver the notifications whenever there is a need. To achieve this goal, Oracle E-Business Suite Mobile Foundation Push Notification System provides the underlying components allowing the supported mobile apps to register the mobile devices and receive push notifications.

Specifically, the Push Notification System contains the following essential components:

• Push Notification Client - Login Component

  The Login component is used to develop the mobile apps and implement the ability to receive the push notifications from the server.

• Push Notification Server

  Push notification server contains the data model to store information about mobile users and the unique IDs (iOS push tokens and Android registration IDs) from their mobile apps to which push notifications should be sent, plus the components to send push notifications to the mobile apps.

  Push notification server uses Oracle Mobile Hub, from Oracle E-Business Suite Mobile Foundation 9.0 and onwards, or Oracle Mobile Cloud Service to send the notifications. OMH or MCS serves as an intermediary between the push notification server and client to manage the device registrations as well as connect to the following platform-specific push notification services to send the notifications.

  • iOS - Apple Push Notification service (APNs)

  • Android - Firebase Cloud Messaging (FCM), new version of Google Cloud Messaging (GCM)

  Important: Oracle E-Business Suite Mobile Foundation Push Notification System requires Oracle Mobile Hub or Oracle Mobile Cloud Service subscription to enable push notifications for mobile apps. OMH or MCS handles platform-specific delivery of push notifications and provides monitoring and error handling capabilities for administrators. If you have already subscribed to OMH or MCS for your enterprise mobile app requirements, you can use the same subscription to enable push notifications for Oracle E-Business Suite. Otherwise, you must obtain a new OMH subscription to use push notifications. In order to use Oracle E-Business Suite Mobile Foundation Push Notification System, the OMH or MCS instance should be set up and registered with Oracle E-Business Suite Mobile Foundation. See: Setting Up an Oracle Mobile Hub or Oracle Mobile Cloud Service Instance.

To better understand these components and how the system works to deliver push notifications, the following diagram illustrates the high level architecture of the Push Notifications System:

Oracle E-Business Suite Mobile Foundation Push Notifications System High Level Architecture

Push notifications can be sent from the server to supported mobile apps using the following flows:

Note: Although Oracle Mobile Hub (OMH) is used in this diagram to explain the architecture components, push notifications are supported when using Oracle Mobile Hub or Oracle Mobile Cloud Service.

• A Mobile App Registers to Receive Push Notifications

  In order for the Oracle E-Business Suite server to send push notifications to mobile devices, it needs a list of mobile users, the apps that those users have installed, and the unique IDs corresponding to the apps on each user's device where the notifications will be sent.

  • Step 1: A mobile user launches a mobile app.

  • Step 2: The mobile app connects to the corresponding platform's push notification service (APNs or FCM) to receive a unique ID known as a push token on iOS or registration ID on Android for that app.

    The unique ID is the address to which the push notification will be delivered. The mobile app registers that unique ID with the server from which it would receive push notifications. For example, the server sends iOS push notifications to APNs and Android push notifications to FCM.

  • Step 3: When the user signs in to the app, the mobile app invokes the Oracle E-Business Suite REST API called "Push Register" (mPushRegister) to register the push token or registration ID with Oracle E-Business Suite Mobile Foundation for that user and the mobile app.

  • Step 4: Oracle E-Business Suite invokes the OMH "Register Device" REST API (/mobile/platform/devices/register) to propagate the push token or registration ID from Oracle E-Business Suite to Oracle Mobile Hub through Workflow Java Deferred Agent Listener.

  The same user can install the same app on multiple devices. A registration is created for each installation of the app to receive push notifications.

• Oracle E-Business Suite Server Sends Push Notifications to Mobile Apps

  Once the Oracle E-Business Suite server receives the list of users registered to receive push notifications, push notifications are delivered to the users.

  • Step 5: Oracle E-Business Suite application product code calls the PL/SQL API FND_MBL_NOTIFICATION.Send which internally raises the push notification business event to send a notification to the user of a given mobile app.

  • Step 6: The Push Notification System builds the notification payload targeted for that user and the app, and enqueues the payload to the FND_MBL_NOTIFICATION_OUT queue.

  • Step 7: Generic Service Component (GSC) OMH Push Notification Agent retrieves the push notification from the queue, builds the OMH payload, and delivers the payload to Oracle Mobile Hub using the "Notification" REST API (/mobile/system/notifications/notifications/) for the user.

  • Step 8: Oracle Mobile Hub delivers the notification to all registered devices for that Oracle E-Business Suite user through the corresponding platform's push notification service, such as APNs for iOS and FCM for Android.

  Note that Oracle E-Business Suite only delivers one push notification for the user of a given app to Oracle Mobile Hub. If the user had installed the same app on multiple devices, Oracle Mobile Hub delivers the same notification to all the devices for that user.

Setting Up and Enabling Push Notifications for Oracle E-Business Suite Mobile Apps

To set up the Push Notification System and enable the mobile apps, you need to perform the following setup tasks:

1. Setting Up a FCM Project for Android Push Notifications Only (Optional)

2. Setting Up an Oracle Mobile Cloud Service Instance

3. Configuring Oracle E-Business Suite for Push Notifications

   • Configuring Oracle E-Business Suite Mobile Foundation Push Notification System

   • Configuring Supported Mobile Apps with Push Notifications

In addition to the above administrative tasks performed on the server, a mobile applications developer needs to complete the following tasks to implement push notifications for the supported mobile apps. For more information, refer to:

• Adding Push Notifications to App Configuration, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2

• Implementing Push Notifications, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2

For information on troubleshooting issues related to the setup or processing of push notifications, see Troubleshooting Tips for Push Notifications.

Setting Up a FCM Project for Android Push Notifications (Optional)

Android push notifications sent from Oracle E-Business Suite are delivered to Android devices through Firebase Cloud Messaging (FCM). In order for FCM to recognize the Oracle E-Business Suite server from where the notifications are sent and the Android apps that receive them, you are required to create a Firebase project.

Perform the following steps to set up a FCM project:

1. Go to the Firebase console (https://console.firebase.google.com) and create a project.

2. In the Project Settings, record the values of the Server Key and Sender ID for Cloud Messaging.

   You will use the Sender ID and Server Key you recorded here when creating the Android mobile client in Oracle Mobile Hub for Oracle E-Business Suite Mobile Foundation 9.0 and onwards or in Oracle Mobile Cloud Service. See: Creating Mobile Clients.

   You will use the same Sender ID when configuring the Push Notification System in the Mobile Push Notification Configuration page. See: Configuring Oracle E-Business Suite Mobile Foundation Push Notification System.

For more information, refer to the Firebase documentation at https://firebase.google.com/docs/cloud-messaging/.

Setting Up an Oracle Mobile Hub or Oracle Mobile Cloud Service Instance

In order for the Oracle E-Business Suite Mobile Foundation Push Notification System to connect to Oracle Mobile Hub or Oracle Mobile Cloud Service to deliver push notifications, complete the following setup tasks on the Oracle Mobile Hub or the Oracle Mobile Cloud Service instance first:

Note: You must use a single Oracle Mobile Hub or Oracle Mobile Cloud Service instance for a given Oracle E-Business Suite. If the instance is changed after the initial setup, the earlier registrations for Oracle E-Business Suite mobile apps will not be automatically synchronized.

1. Creating a Mobile Backend

2. Creating Mobile Clients

3. Creating an Oracle Mobile Hub or Oracle Mobile Cloud Service User Account

4. Enabling HTTP Basic Authentication

Creating a Mobile Backend

To create a mobile backend on the Oracle Mobile Hub or Oracle Mobile Cloud Service instance, perform the following tasks:

1. Log in to your Oracle Mobile Hub instance or your Oracle Mobile Cloud Service instance.

2. Create a mobile backend to be used specifically for Oracle E-Business Suite push notifications.

   For more information, refer to the following documents:

   • For Oracle Mobile Hub, see Backend in Developing Applications with Oracle Mobile Hub (https://docs.oracle.com/en/cloud/paas/mobile-hub/develop/index.html).

   • For Oracle Mobile Cloud Service, see Mobile Backends in Using Oracle Mobile Cloud Service (https://docs.oracle.com/en/cloud/paas/mobile-cloud/mcsua/index.html).

Creating Mobile Clients

In order for Oracle Mobile Hub or Oracle Mobile Cloud Service to deliver push notifications on behalf of the Oracle E-Business Suite Mobile Foundation Push Notification System, the Oracle E-Business Suite mobile apps to which push notifications should be delivered need to be registered on the Oracle Mobile Hub or Oracle Mobile Cloud Service instance.

1. Log in to your Oracle Mobile Hub or Oracle Mobile Cloud Service instance.

2. In your instance, click the menu icon to open the side menu.

   • For Oracle Mobile Hub, select Development, and then Notification Profiles. Create a client for each Oracle E-Business Suite mobile app distribution.

   • For Oracle Mobile Cloud Service, select Application, and then Client Management. Create a client for each Oracle E-Business Suite mobile app distribution.

   For example, if you would like to receive push notifications for both iOS and Android distributions of an enterprise-distributed Approvals app, you have to register one client each for each platform.

3. When creating a client, use correct Bundle ID or Package Name that has been used to deploy your mobile app.

   • Bundle ID (iOS): The Bundle ID registered with Apple to receive the iOS provisioning profile. This is the bundle ID used in the deployment profile to create the iOS app.

     For information on the platform-specific deployment profile, see Modifying an Existing Deployment Profile (Conditional), Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.

   • Package Name (Android): The Package Name used in the deployment profile to create the Android app.

4. For each client, create a required push notification profile.

   • iOS: Use the APNs certificate issued by Apple.

   • Android: Use the values of Sender ID and Server Key you recorded earlier for the Firebase project.

     For information on obtaining the project number and the Server Key, see: Setting Up a FCM Project for Android Push Notifications Only (Optional).

5. Associate each client with the mobile backend that you created earlier for Oracle E-Business Suite.

   See: Creating a Mobile Backend.

For more information about client management, see the following documents:

• For Oracle Mobile Hub, see "Set Up a Mobile App for Notifications" section in "Notifications" chapter from Developing Applications with Oracle Mobile Hub (https://docs.oracle.com/en/cloud/paas/mobile-hub/develop/index.html).

• For Oracle Mobile Cloud Service, see Client Management in Using Oracle Mobile Cloud Service (https://docs.oracle.com/en/cloud/paas/mobilecloud/mcsua/index.html).

Creating an Oracle Mobile Hub or Oracle Mobile Cloud Service User Account

In order for the Oracle E-Business Suite Mobile Foundation Push Notification System to connect to Oracle Mobile Hub or Oracle Mobile Cloud Service to deliver push notifications, you should create a user account on Oracle Mobile Hub or Oracle Mobile Cloud Service, assign required roles to that account, and then configure it in the Push Notification System.

Steps to create an Oracle Mobile Hub user account:

Use the following steps to create an Oracle Mobile Hub user account:

1. Log in to Oracle Identity Cloud Service (IDCS) and click Users or click the Users tab in Oracle Cloud My Services.

2. Click Add.

3. Enter the first name and last name of the user in the corresponding fields.

   • If the user is going to log in with a user name, enter the user name in the User Name field and enter the user's email address in the Email field. Be sure to clear the Use the email address as the user name option, which makes the user name the same as the user's email address.

   • If the user is going to log in using an email address, make sure the Use the email address as the user name option is checked and enter the email address for the user account in the User Name/Email field.

4. Click Next if you want to assign the user to a group or click Finish. To assign a group, select the groups that you want to assign to this user account and click Finish.

5. From the Details page displayed for the new user, click the Access tab.

6. Search for your Mobile Hub mobile core application and click Assign.

For more information, see "Mobile Users and Roles" in Developing Applications with Oracle Mobile Hub (https://docs.oracle.com/en/cloud/paas/mobile-hub/develop/index.html).

Steps to create an Oracle Mobile Cloud Service user account:

Use the following steps to create an Oracle Mobile Cloud Service user account:

1. Log in to your Oracle Mobile Cloud Service instance.

2. Click the menu icon to open the side menu. Select Application, and then Mobile User Management.

3. Either create a new realm or use a default realm.

4. Create a user who will be used to register this backend with Oracle E-Business Suite.

5. Go to Oracle Cloud My Services, and select the Users page.

6. The user created in the backend appears with a default role associated with the MCS instance.

   For example, the default role is Default (mcsinst_MobileEnvironment_Default_1_0_Realm).

7. Assign the "Mobile Notifications" role to this user.

   For example, the role is mcsinst Mobile Notifications.

These two roles described here are important for Oracle E-Business Suite to connect to this Oracle Mobile Cloud Service instance to deliver push notifications.

For more information, see Mobile User Management in Using Oracle Mobile Cloud Service (https://docs.oracle.com/en/cloud/paas/mobile-cloud/mcsua/index.html).

Enabling HTTP Basic Authentication

Oracle E-Business Suite uses the HTTP Basic authentication to connect to Oracle Mobile Hub or Oracle Mobile Cloud Service. Enable the HTPP Basic authentication and record required connection details for the Oracle Mobile Hub or Oracle Mobile Cloud Service instance to be registered in the Oracle E-Business Suite Mobile Foundation Push Notification System.

1. Log in to your Oracle Mobile Hub or Oracle Mobile Cloud Service instance.

2. Open the mobile backend you created earlier for Oracle E-Business Suite. Select the Settings page.

3. Under Access Keys, enable the "HTTP Basic" authentication by turning the switch to ON.

   When switched to ON, the access keys that you need are displayed.

4. Record the following information that will be used later in Configuring Oracle E-Business Suite Mobile Foundation Push Notification System.

   • Mobile Backend ID under HTTP Basic

   • Base URL under Environment URLs

   • Username (created earlier)

   • Password for this user

Once the setup is complete, you are ready to configure the Push Notification System to connect to Oracle Mobile Hub or Oracle Mobile Cloud Service.

Configuring Oracle E-Business Suite for Push Notifications

Besides the setup tasks on Oracle Mobile Cloud Service, you need to perform required configuration on Oracle E-Business Suite so that Oracle E-Business Suite can accept push notification registrations from mobile users and send push notifications to the registered devices. These setup tasks on Oracle E-Business Suite include:

• Configuring Oracle E-Business Suite Mobile Foundation Push Notification System

• Configuring Supported Mobile Apps with Push Notifications

Configuring Oracle E-Business Suite Mobile Foundation Push Notification System

To configure the Push Notification System from Oracle E-Business Suite Mobile Foundation, select the Mobile Applications Manager responsibility and choose the Applications link from the navigator. The Search Mobile Applications page appears.

Click Push Configuration on the upper right corner to access the Mobile Push Notification Configuration page.

Mobile Push Notification Configuration Page

Perform the following tasks to configure the Push Notification System and required component parameters:

1. Specify the following information to enable the Push Notification System:

   • Push Notification System: Enabled

2. In the Oracle Cloud Service Parameters region, enter the following information:

   Note: For the Backend ID, URL, Username, and Password fields, use the information you recorded earlier while enabling the HTTP Basic authentication in Oracle Mobile Cloud Service or Oracle Mobile Hub, see: Enabling HTTP Basic Authentication.

   • Backend ID: Enter the value that you recorded earlier when creating the backend for Oracle E-Business Suite push notifications.

     See: Creating a Mobile Backend.

   • Backend URL: Specify the desired URL for Oracle Mobile Cloud Service or Oracle Mobile Hub.

   • Username: Enter the Oracle Mobile Cloud Service or Oracle Mobile Hub user who has appropriate notification user roles.

     The username credentials are used by the Push Notifications System to connect to Oracle Mobile Cloud Service or Oracle Mobile Hub to register devices and send push notifications. The user must have the following roles assigned:

     • Mobile Notifications (mcsinst Mobile Notifications)

     • Default (mcsinst_MobileEnvironment_Default_1_0_Realm)

     If the credentials are invalid or if required roles are not granted to the user in Oracle Mobile Cloud Service or Oracle Mobile Hub, the configuration will fail.

     For information on creating a mobile user with credentials, see: Creating an Oracle Mobile Hub or Oracle Mobile Cloud Service User Account.

   • Password: Enter the associated user password.

   • Android Sender ID: Enter the Sender ID used to create the Android push notification profile when creating the Android client in Oracle Mobile Cloud Service or Oracle Mobile Hub. See: Creating Mobile Clients.

     Note: Sender ID is used to register the Android client in Oracle Mobile Cloud Service or Oracle Mobile Hub; Android Sender ID is used in the Mobile Push Notification Configuration page here. These two values should be the same.

     Android Sender ID is downloaded to Oracle E-Business Suite Android mobile apps through the configuration service. Android apps then use this Android Sender ID to register for push notifications with FCM.

     See: Setting Up a FCM Project for Android Push Notifications Only (Optional).

3. In the Push Service Component region, notice the following information:

   • Component Status: This displays the current component status, such as Running.

4. Click Apply to save the configuration.

In order for the Push Notification System to work correctly, the following Service Components should be running.

• Workflow Java Deferred Agent Listener - Processes business events to synchronize device registrations for push notifications from Oracle E-Business Suite to Oracle Mobile Cloud Service or Oracle Mobile Hub.

• Push Notification Provider - Processes push notifications triggered by Oracle E-Business Suite application code to its corresponding mobile app. It connects to Oracle Mobile Cloud Service or Oracle Mobile Hub to send the push notifications.

Log in to Oracle E-Business Suite as a user who has the System Administrator responsibility. Select the Oracle Applications Manager link, and then Workflow Manager to ensure these two components are running.

Configuring Supported Mobile Apps with Push Notifications

After the setup for the Push Notification System is complete, it is important to configure each supported mobile app that should receive push notifications from the Oracle E-Business Suite server.

Important: Starting from Oracle E-Business Suite Mobile Foundation Release 7.0 and onwards, push notifications are supported in the following apps when using Oracle Mobile Cloud Service or using Oracle Mobile Hub, from Release 9.0 when an appropriate patch is applied:

• 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

Standard Oracle E-Business Suite mobile apps installed directly from the Apple App Store or Google Play do not support push notifications.

Note: If an app can be enabled with push notifications, during the app registration, a developer can define the application definition metadata by adding the "Push Notifications" category along with the relevant parameters in the Configuration Details page for the app. See: Registering Your Mobile App, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.

After the registration, you can enable the app and update the push notifications parameters if desired in the Configure Mobile Applications page.

Perform the following steps to configure a mobile app that supports push notifications:

1. Log in to Oracle E-Business Suite as a user who has the Mobile Applications Administrator role. For example, log in as SYSADMIN.

2. Select the Mobile Applications Manager responsibility and choose the Applications link from the navigator.

   The Search Mobile Applications page appears.

3. Search for the app that supports push notifications. For example, select the enterprise-distributed Approvals app called XXX_APPROVALS.

4. Click the Configure icon for the selected app XXX_APPROVALS that you want to configure with push notifications from the search result table.

   The Configure Mobile Applications page appears.

5. Select Yes for the "Push Notifications" category.

   Configure Mobile Applications Page with "Push Notifications" Selected

   

6. Expand the "Push Notifications" category by clicking the Details icon. Enter the following values:

   Configuration Details Page to Configure Parameters for Push Notifications

   

   • iOS Deployment Bundle ID (IOS_DEPLOYMENT_BUNDLE_ID): Enter the same bundle ID used to create the iOS client on Oracle Mobile Cloud Service or Oracle Mobile Hub for this selected mobile app.

   • Android Deployment Bundle ID (ANDROID_DEPLOYMENT_BUNDLE_ID): Enter the same Package Name used to create the Android client on Oracle Mobile Cloud Service or Oracle Mobile Hub for this selected mobile app.

   • Push Notifications Business Event (NOTIFICATION_BUSINESS_EVENT): Enter the app-specific business event used to trigger push notifications when the event is raised. For example, enter oracle.apps.mobile.approvals.push.event for the enterprise-distributed Approvals app.

     This business event along with other app-specific events are included in an event group called oracle.apps.mobile.foundation.push.group. Oracle E-Business Suite Mobile Foundation uses the event group that has the default event subscription to process the push notifications.

7. Save your mobile app configuration.

Additionally, after configuring the mobile app, you can invoke the configuration service corresponding to that mobile app and confirm the following values:

• Android Sender ID

  This value is the same as the following:

  • Sender ID: It is used to create the Android push notification profile in Oracle Mobile Cloud Service or Oracle Mobile Hub. See: Creating Mobile Clients.

  • Android Sender ID: It is used to set up the Oracle E-Business Suite Mobile Foundation Push Notification System. See: Configuring Oracle E-Business Suite Mobile Foundation Push Notification System.

• Push Status

  This should be ENABLED for the mobile app to successfully receive push notifications.

For information on invoking the configuration service, see Validating the Configuration.