This chapter describes how to enable logging and diagnostics features as well as how to troubleshoot possible issues from the mobile client and the server. It includes the following sections:
Troubleshooting Oracle E-Business Suite mobile apps involves the following high level options:
Server logging
Client logging
REST service auditing
To better understand these logging and auditing features, this section includes the following topics:
Oracle E-Business Suite mobile apps use the common logging and diagnostics features in Oracle E-Business Suite to enable the logging for REST services used by mobile apps. Once these features are enabled for Oracle E-Business Suite applications, administrators can use the log messages to diagnose and troubleshoot potential issues on the Oracle E-Business Suite server.
If a mobile app user reports a problem, an administrator can set the following Oracle Application Object Library (FND) profile options for that user to enable logging, control the logging level, and set the module for which logs are recorded. These profile options are also used if app users need to upload their client log files to the server.
FND: Debug Log Enabled (AFLOG_ENABLED)
FND: Debug Log Module (AFLOG_MODULE)
FND: Debug Log Level (AFLOG_LEVEL)
Note: Use the app-specific REST service module names to set the FND: Debug Log Module profile option. These module names are listed in Appendix D: Mobile App Module Names.
For information on enabling the logging and diagnostics features, refer to the Oracle E-Business Suite Maintenance Guide.
Retrieving Server Logs
To retrieve the server logs recorded for your mobile app, perform the following steps:
Log in to Oracle E-Business Suite as the SYSADMIN user. Select the System Administrator (or System Administration) responsibility and choose the Oracle Applications Manager link and then the Logs link from the navigation menu.
In the Search System Logs page, click the Advanced Search button.
Enter the following information in the Advanced Search region:
User: Enter the mobile app user name.
Module: Enter the REST service module name of the mobile app.
Run the search to retrieve and download the desired server logs.
If a user of Oracle E-Business Suite mobile apps reports a problem when using the app, and Oracle Support requests client logs, the following profile options set on the server for the server logging are also required for the client logging. These profile options enable the log upload service invoked by the mobile app to provide the upload feature.
FND: Debug Log Enabled (AFLOG_ENABLED)
Set this profile option to Yes to enable the debug logging.
FND: Debug Log Module (AFLOG_MODULE)
For Oracle E-Business Suite Mobile Foundation Release 2.1 and onwards, set this profile option to your Application Bundle Id.
For information on Application Bundle Id for each mobile app, see Appendix C: Application Definition Metadata.
For Oracle E-Business Suite Mobile Foundation Release 2.0, set this profile option to "MOBILE".
FND: Debug Log Level (AFLOG_LEVEL)
Set this profile option to the level of detail you want to record, such as STATEMENT.
Note that the same logging profile options are used to enable the server and client logging, as well as the REST service auditing. It is recommended that you use the following sequence when troubleshooting both server and client code at the same time.
Turn on the server logging to obtain log statements written by REST services. For information on setting profile options for server logging, see Enabling Server Logging.
Direct the app user to turn on diagnostics logging on the mobile client.
Direct the app user to reproduce the issue that invokes the REST services.
Log statements from the REST services should be recorded. However, the server cannot receive the client log file at this point.
Set the profile options as described in this section for the user to receive the client log file.
The client and server logging can happen at the same time when an issue is being reproduced. However, to upload the log file, the profile options should be changed to receive the log file after the issue is reproduced.
Request the mobile app user to upload the log file from the mobile client to the server.
Retrieve the REST service log statements based on the profile options set in step 1.
Retrieve the mobile client log file uploaded based on profile options set in step 4.
Uploading Client Logs to the Oracle E-Business Suite Server
If mobile app users can access to the app, direct the users to perform the following steps to collect the logs from the mobile client:
In the navigation menu of the mobile app, tap Settings and then the Diagnostics.
In the Diagnostics screen, enable the client logging feature by turning on the Logging option.
Return to the navigation menu and reproduce the reported issue.
In the menu, tap Settings and then the Diagnostics again.
In the Diagnostics screen, tap the Upload icon on the top right corner. This displays the upload screen where app users can upload the log files recorded for the app to the Oracle E-Business Suite server.
Diagnostics Screen with Upload Icon Highlighted in iOS and Android Devices
You can then download the uploaded log files from the Oracle E-Business Suite server.
To retrieve client logs, follow the steps described in Enabling Server Logging. However, use the following search criteria to locate the client logs:
User: Enter the mobile app user name.
Module: Enter your Application Bundle Id as the Module name.
For information on Application Bundle Id for each mobile app, see Appendix C: Application Definition Metadata.
Please note that if the FND: Diagnostics profile option is enabled for a user, the complete error stack from the service invocation failure appears. Otherwise, only a simple error message is shown instead.
Retrieving Client Logs Directly From Android Mobile Devices
If mobile app users are unable to access or log in to the app, the users will not be able to upload the logs to the server from the mobile client. In this situation, direct the Android users to retrieve client logs directly from their mobile devices instead.
Note: The option of retrieving client logs directly from iOS devices is not available.
Use a file browser app on Android. For example, My Files, ES File Explorer.
Look for files that start with the app name. For example, Approvals.txt
, Approvals_bak.txt
.
Attach these files to an email through your preferred email app and upload to Oracle Support.
Perform the following steps to enable auditing for REST service request and response payloads during the service invocation for Oracle E-Business Suite mobile apps:
Note: The REST service payloads can be logged for auditing only when the server logging is also enabled.
If the REST service auditing feature is not required, you can choose to enable the server logging only. See Enabling Server Logging.
Set the FND: OA Framework REST Service Audit Enabled (FND_OAF_REST_LOG_ENABLED) profile option to Yes.
This enables the REST service auditing feature. The default value is No.
Set the following server logging profile options for the app users:
FND: Debug Log Enabled (AFLOG_ENABLED)
Set this profile option to Yes to enable the debug logging.
FND: Debug Log Module (AFLOG_MODULE)
Set this profile option to fnd.framework.rest.Auditing%, <other REST service modules as applicable>
For example, to obtain logs for the Oracle Mobile Approvals for Oracle E-Business Suite app, set the profile option to the following: fnd.framework.rest.Auditing%, fnd.wf.worklist%
To retrieve logs for auditing, follow the steps described earlier in Enabling Server Logging. However, use fnd.framework.rest.Auditing
as the Module name instead of the module name of the app, along with the app user name as the search criteria to locate the logs.
FND: Debug Log Level (AFLOG_LEVEL)
Set this profile option to at least the EVENT level in order for the auditing feature to work.
If you want to use both logs and auditing to troubleshoot an issue with the underlying REST services, set the FND: Debug Log Level profile option to STATEMENT and set the FND: Debug Log Module profile option as described in this section.
This section includes the following troubleshooting information on potential problem symptoms and corresponding solutions.
For information about each app's definition metadata that may help identify the app in various troubleshooting processes, see Appendix C: Application Definition Metadata.
If you contact Oracle Support about an app, specify the associated product name for that app. See Appendix E: Associated Products in My Oracle Support.
This section describes the troubleshooting tips on the mobile client. It includes the following topics:
Directing Users to Obtain Connection Details and Download Updates from the Server
Troubleshooting Tips for Oracle E-Business Suite Mobile Apps
When trying to diagnose and troubleshoot issues encountered on the mobile client, you can direct users to obtain the server connection details from their mobile devices and check if any new updates from the server are required.
Perform the following steps to obtain the connection details and initiate server updates:
In the navigation menu of the mobile app, tap Settings and then Connection Details. The Connection Details screen appears.
The Connection Details screen displays the server URL field and the Server Configuration region.
Server URL field: This is the URL value entered by the mobile user during the initial launch of the app. This value is retrieved from the local database in the device.
If the mobile user wants to reconfigure the app to a different Oracle E-Business Suite instance after the initial setup is complete, the user can change the server URL value by tapping the Change URL button, as shown on the left. The app displays the device's Settings screen where the user can update the server URL directly.
Note: When a user reconfigures an app from one Oracle E-Business Suite instance to another, the local preferences are completely removed. After the configuration, the user is required to set the preferences again.
Connection Details Screen with "Change URL" Button Highlighted (Left) and without the Button (Right)
Note: Starting from Oracle E-Business Suite Mobile Foundation Release 8.0 and onwards, administrators can preconfigure the server URL and also determine if users can change the default URL value. If the server URL is preconfigured and users are not allowed to change the value, then Change URL will not be displayed. Instead, "Your administrator has configured the app to connect to this server URL. You cannot change this setting." message appears, as shown on the right.
For information on preconfiguring server URL, see Setup Tasks for Deploying Mobile Apps with Enterprise Mobility Management (EMM) Solutions.
The user can navigate to the device's Settings screen to change the server URL if desired:
From the iOS device's Settings screen, tap Settings, then App Name, and then Server URL.
From the Android devices with the app open, tap Settings, then Settings or Preferences, and then Server URL.
Server Configuration region: This region displays the parameter values in the configuration file downloaded from the server.
Last Updated: The date and time when the app was last updated.
Session Timeout: The number of seconds that a user can remain logged in to the app.
Idle Timeout: The number of seconds that the app can remain idle.
This field appears only when the "Apps Local Login" (previously known as "HTTP Basic") authentication type is selected for your app.
Service Endpoint: The value used to invoke Oracle E-Business Suite services. This value can either be the same as the server URL entered by the user, or a dedicated web entry point for this app.
Service Version: The internal version of the mobile services used by the app, obtained from the app's definition metadata. For example, 1.0.0.
Direct users to check if any new updates from the server are required for the app.
Starting from Oracle E-Business Suite Mobile Foundation Release 7.0 and onwards, Oracle E-Business Suite mobile apps automatically download the mobile app configuration updates from the Oracle E-Business Suite server. Users no longer need to initiate a download manually within an app. Instead, each app periodically checks for updates (once every five times the app is restarted) and downloads them to synchronize with the configuration details defined on the Oracle E-Business Suite server. However, if required, users can still initiate the manual update by tapping the Sync icon as in the previous releases.
Note: For releases earlier than Oracle E-Business Suite Mobile Foundation 7.0, users need to manually tap the Sync icon next to the Server Configuration region to check if any new updates from the server are required for the app.
Direct users to follow the instructions on the mobile device to continue the updates from the server. For example, a user must restart the app to apply the updates if either one of the following attributes from the server is different from the value in the device:
service endpoint
authentication type (Oracle E-Business Suite Mobile Foundation Release 4.0 and onwards only)
If only the timeout values need to be updated, the user can choose to continue using the app without restarting it immediately. In this case the updates will be applied the next time the app is launched.
The following table lists common issues that might occur while using Oracle E-Business Suite mobile apps as well as the corresponding solutions.
Issue | Tip |
---|---|
For a mobile app built with Oracle E-Business Suite Mobile Foundation 7.0 and onwards, when a user enters a server URL in a mobile device using HTTPS, if the TLS certificate is untrusted and cannot be recognized by the mobile app, the following error message may appear:"Unable to make a secure connection to the Oracle E-Business Suite server. Please verify the TLS setup for the app and the server." |
Ensure that your mobile app can perform a successful TLS handshake with the Oracle E-Business Suite TLS endpoint.
If the root CA that issued the certificate for Oracle E-Business Suite is not part of the mobile app, or if your Oracle E-Business Suite environment is TLS-enabled using a self-signed or certificate issued by a custom CA, make sure to import the CA's root certificate to the mobile app. For instructions on importing the CA's root certificate to Oracle E-Business Suite mobile apps, see Advanced Configurations for Secure Communication with HTTPS. |
For a mobile app built with Oracle E-Business Suite Mobile Foundation releases earlier than 7.0, when a user enters a server URL in a mobile device using HTTPS, if the TLS certificate is untrusted and cannot be recognized by the mobile app, the following error message may appear:"Unable to connect to the Oracle E-Business Suite server. Please enter a valid server URL." |
Ensure that your mobile app can perform a successful TLS handshake with the Oracle E-Business Suite TLS endpoint.
For validation instructions, see the detailed steps as described in Advanced Configurations for Secure Communication with HTTPS. For a list of root CAs trusted by the mobile client, see Migrating to New cacerts File for SSL in MAF 2.x.x, Installing Oracle Mobile Application Framework. For information on the Oracle MAF version required for your app, see Oracle E-Business Suite Mobile Apps, Release 12.1 and 12.2 Documentation Index, My Oracle Support Knowledge Document 1641772.1, and Section 1: Oracle E-Business Suite Mobile Foundation Release Update History in Oracle E-Business Suite Mobile Foundation Release Notes, Oracle Support Knowledge Document 1642431.1. |
After a user enters valid user credentials in the standard login screen, the app displays the loading indicator for a few seconds and then redirects the user back to the login screen. | Ensure that the server URL used by the user to configure the app matches the Oracle E-Business Suite web entry URL. Otherwise, Oracle E-Business Suite server might reject the REST requests from the mobile app which will result in redirecting the user to the login screen. |
When a user initiates the check for updates process by tapping Settings from the mobile app navigation menu, then tapping Connection Details, and then tapping the Sync icon in the Connection Details screen, the user is redirected to the login screen. After logging in to the app, the user is taken to the default landing screen. The same issue also occurs if a user tries to navigate to a different feature after the app has idle timed out, the user is redirected to the login screen. After the user logs in to the app, instead of taking the user to the desired screen before the timeout, the app redirects the user to the default landing screen. |
To resolve the issue, apply the following patch for your release:
It is recommended that you apply this patch after the corresponding consolidated product family patch for your app to avoid the issue. |
After a user enters valid user credentials in the standard login screen after the configuration screen, the following error occurs:The login server is not reachable. |
The cause of the issue could be either that the HTTP server is down or the login server was not installed or set up correctly during the installation of the appropriate patch on your Oracle E-Business Suite server. The URL for the login server used by mobile apps is in the following format: http(s)://<hostname>:<port>/OA_HTML/RF.jsp?function_id=mLogin Please note that this is not a URL that the app users would enter or edit. It is constructed during the app setup and loaded to the mobile app through the configuration file. If this URL value is invalid in the configuration file, the users will not be able to log in to Oracle E-Business Suite. Before allowing users to connect to Oracle E-Business Suite from mobile apps, ensure the right login server URL is set up in the configuration file, as described in Validating the Configuration. Additionally, you can test the login server URL by copying the URL and pasting it in a web browser. A pop-up window should appear for user name and password. After you successfully enter valid user credentials, an XML response should appear with the following elements: accessToken, accessTokenName, ebsVersion, and userName. Note: When an app user is authenticated, the |
A mobile user fails to log in to an app. When an administrator tests the standalone mLogin REST service by entering the URL http(s)://<hostname>:<port>OA_HTML/RF.jsp?function_id=mLogin or tests the configuration service URL http(s)://<hostname>:<port>OA_HTML/RF.jsp?function_id=mConfig&bundleId=<application bundle id>&file=ebs-mobile-config.xml , one of the following errors occurs:Resource/rest NOT found or HTTP 500 Internal server error |
Perform the following steps to resolve the issue:
|
After a user enters user credentials in the standard login screen after the configuration screen, the following error occurs:Invalid username/password. If the problem persists, please contact your system administrator |
To resolve the issue, ensure that the user enters a valid user name and password. Verify the user name is still valid in the system and reset the password if required. |
After a user enters valid user credentials in the standard login screen after the configuration screen, the following error occurs:One or more parameters downloaded from the server are invalid. The same error can also occur after the user initiates the check for updates process by tapping Settings from the mobile app navigation menu, then tapping Connection Details and then tapping the Sync icon in the Connection Details screen. |
This is due to invalid configuration data, such as invalid service endpoint, in the downloaded configuration file. To resolve the issue, ensure that a valid service endpoint is specified in the Configure Mobile Applications page while setting up the mobile app. |
After a user enters valid user credentials in the standard login screen after the configuration screen, the following error occurs:An error occurred when downloading updates from the server. The same error can also occur after the user initiates the check for updates process as described above. |
To resolve the issue, ensure that there is no server or network connection issue. |
After a user logs in to an app, while on the landing page of the app, the user leaves the device idle for a period of time beyond the value set in the Idle Timeout parameter (default value is 7200 seconds). When the user attempts to open the Springboard from the landing page, a blank page appears with a lock. | This issue is a known limitation in Oracle MAF, where after the idle period exceeds the value set in the Idle Timeout parameter, when the user accesses the Springboard, the app does not automatically display the login screen. To resolve the issue, close the Springboard and access other links in the landing page. The user should be redirected to the login screen. |
A mobile user may find that the date and time information in the mobile device is different from that in the desktop pages. | This difference occurs because the mobile app displays the time zone and date and time information based on the settings specified in the mobile client's Settings screen. Tap Settings, then General, and then Date & Time in the iOS mobile Settings screen or tap Settings and then Date & Time in the Android Settings screen to set your preferences. |
After modifying the Server URL through the iOS mobile Settings screen (tap Settings, then App Name, and then Server URL) or the Android device's Settings screen (tap Settings, then Settings or Preferences, and then Server URL), the user closes and restarts the app. The app displays the page with the message "The server URL has changed.", but the Server URL field is blank. | If the user removed the previous URL in the device settings but did not enter a new URL, then no value is shown for the Server URL field. |
During the initial configuration of an app, after a mobile user enters a server URL and taps Get Started, the following error message appears:Please enter a valid URL. |
Ensure the server URL is valid by performing the following steps:
|
During the initial configuration of an app, after a mobile user enters a server URL and taps Get Started, the following error message appears:This mobile application is not currently configured on this server. |
This message appears because the required Oracle E-Business Suite Mobile Foundation patches have not been applied on the Oracle E-Business Suite server to which the app is connecting. Apply the patches described in Applying Prerequisite Patches in order for the user to proceed through the page where the server URL value is entered. |
After a user enters valid user credentials in the standard login screen after the configuration screen, the following error occurs:Configuration Error - This mobile application is not currently enabled on this server. Please close the application. |
The app may be already configured but the status is set to "Disabled". In order for the apps to successfully access the configuration files, set the status of the app to "Enabled". For information on configuring Oracle E-Business Suite mobile apps, see Configuring the Mobile Apps on the Oracle E-Business Suite Server. |
After entering a new server URL through the Connection Details page in Oracle E-Business Suite Mobile Foundation Release 3.0 or later releases, or through the mobile Settings screen (tap Settings, then App Name, and then Server URL from the iOS Settings screen or tap Settings, then Settings or Preferences, and then Server URL from the Android Settings screen), the user returns to the app. The app still connects to the previous Oracle E-Business Suite instance. | After changing the server URL, the user must restart the app to initiate the reconfiguration flow. |
After a user enters valid user credentials in the standard login screen after the configuration screen, the following error occurs:Configuration Error - This mobile application is not currently configured on this server. Please close the application. |
This error indicates that the app's status is "Not Configured". This means the administrator has not yet configured the app with appropriate configuration parameters or has not completed a mandatory setup required to use the mobile app. For information on setting the configuration parameters for your mobile app, see Configuring the Mobile Apps on the Oracle E-Business Suite Server. |
This section describes the troubleshooting tips on the Oracle E-Business Suite server. It includes the following topics:
The following table describes common issues that might occur on the Oracle E-Business Suite server as well as the corresponding solutions.
Issue | Tip |
---|---|
For Oracle E-Business Suite Mobile Foundation 8.0 and onwards, if administrators preconfigure Server URL in an Enterprise Mobility Management (EMM) console through the Server_URL property or in ebs.properties when EMM is not used, after an app user launches the app, the following error may appear:Unable to connect to the Oracle E-Business Suite server. The server URL may be invalid. |
To resolve this issue, perform the following steps to verify the preconfigured Server URL in ebs.properties or an EMM console to make sure:
|
After applying the appropriate patch for your Oracle E-Business Suite release, the Mobile Applications Manager responsibility is still not visible for SYSADMIN user by default. | Perform the following steps to resolve the issue:
|
Users need to access the Mobile Applications Manager responsibility. | The SYSADMIN user is granted the Mobile Applications Manager responsibility by default. The SYSADMIN user can assign the responsibility to other users through the "Mobile Application Administrator" user role in User Management. |
After you select the Mobile Applications Manager responsibility and the Applications link from the navigation menu and perform a search in the Search Mobile Applications page, no mobile applications are listed in the search result table. | Ensure all the prerequisite patches required for your mobile apps are applied. If the desired applications still do not appear in the search result table, contact Oracle Support. |
A configuration parameter such as Timeout was modified on the server and the configuration file is regenerated. The current app users do not have the parameters updated. | To resolve this issue, a mobile user can initiate the server updates from the mobile device. See Directing Users to Obtain Connection Details and Download Updates from the Server. |
This section describes the troubleshooting tips that are particularly related to configure mobile apps with the Apps SSO Login (previously known as "Web SSO") authentication type.
For information about configuring apps with the Apps SSO Login authentication type, see:
Troubleshooting Tips
Perform the following tasks to validate and troubleshoot potential issues for configuring mobile apps with the Apps SSO Login type:
Verify prerequisite configuration for Oracle E-Business Suite, Oracle Access Manager (OAM), and Oracle Directory Services integration
Navigate to the application login page through a web browser. Verify the login redirects to Oracle Access Manager as configured during the Oracle E-Business Suite integration with Oracle Access Manager, and the same LDAP user that will be using a mobile app can log in successfully to Oracle E-Business Suite framework based applications.
Verify after successful login and rendering of the Oracle E-Business Suite Home page, the user has Oracle E-Business Suite responsibilities assigned.
Ensure the administrator has configured the specific configuration tasks, as described in Prerequisites for Setting Up Mobile Apps with Single Sign-On and Mobile Specific Setup Tasks to Enable Apps SSO Login Authentication Security.
Test the configured "SSO Login URL", "SSO Login Success URL", and "SSO Logout URL" parameters
Navigate to the configured SSO Login URL through a web browser. After the login, the browser should return a protected page successfully (Status 200 OK
). The URL for this page must be the same as the configured SSO Login Success URL.
Note: The "SSO Login URL" and "SSO Login Success URL" parameters relate to each other. The values of these two parameters can be the same.
Do not configure a URL, such as http://<hostname>:<port>/OA_HTML/AppsLogin
, as the SSO Login URL because this page would unnecessarily redirect to the Oracle E-Business Suite Home page after the login. Use the default SSO Login URL http://<hostname>:<port>/accessgate/login/sso
instead.
Navigate to the configured SSO Login URL through a web browser. For example, http://<hostname>:<port>/accessgate/login/sso
.
Note: When you test the login/sso
or login/apps
(as described later in step 3 for "EBS Session Service") service standalone from a web browser, it is recommended sending the X-Ebs-Wep request parameter that is supported in Oracle E-Business Suite AccessGate (EAG) 1.3.2.1 and above with Oracle E-Business Suite web entry URL (http(s)://<hostname>:<port>
).
If EAG does not receive this parameter, the login/apps
service may fail and an "Initialization failed -1
" error is captured in EAG logs. In this situation, ensure you pass this X-Ebs-Wep request parameter while testing the service standalone from a browser.
Expected result: Redirect to the OAM login page. Login successful after specifying the LDAP user name and password.
After the login, the resource http://<hostname>:<port>/accessgate/login/sso
shows with no error message. This resource must be the configured "SSO Login Success URL" parameter value.
Note: The "SSO Login URL" and "SSO Login Success URL" parameter values can be the same.
The browser shows a blank page successfully.
Navigate to the configured SSO Logout URL. For example, http://<hostname>:<port>/accessgate/logout/sso
.
Expected result: User logged out successfully.
Perform the same tests using your mobile device browser.
Test the configured "EBS Session Service" parameter
Navigate to the configured EBS Session Service through a web browser. For example, http://<hostname>:<port>/accessgate/login/apps
.
Expected result: Redirect to the OAM login page. Login successful after specifying the LDAP user name and password.
After the login, the browser returns an xml file containing an access token and the user name for the user that just logged in. For example:
<response> <data> <accessToken>xxxxxxxxxxxxxxxxxxxxxxxxxx</accessToken> <accessTokenName>emsxxxxx</accessTokenName> <ebsVersion>12.2.5</ebsVersion> <userName>xxxxx</userName> </data> </response>
Perform the same test using your mobile device browser.
Collect HTTP header traces and logs
Collect HTTP Header traces during the implementation of the above test points.
Collect log files for Oracle E-Business Suite AccessGate, Oracle E-Business Suite oacore, and the OAM server.
Refer to My Oracle Support Knowledge Document 1077460.1, Troubleshooting Oracle Access Manager and Oracle E-Business Suite AccessGate, on how to generate Oracle E-Business Suite AccessGate logs.
If you have enabled push notifications for the supported mobile apps, you would want to troubleshoot setup and processing of push notifications if users report that they are not receiving push notifications. This section includes the following topics:
Troubleshooting Tips for Enabling Push Notifications on the Mobile Client
Troubleshooting Tips for Common Setup Issues on the Oracle E-Business Suite Server
For more information about push notifications, see Setting Up Push Notifications for Mobile Apps.
The following table lists the troubleshooting tips for enabling push notifications on the mobile client:
Issue | Tip |
---|---|
A mobile app user is not able to receive push notifications in the mobile device, while other users of the same app do not have this issue. | Provide the following instructions to the mobile user to change the device settings:
|
The following table describes the common setup issues, possible causes, and corresponding solutions in the Oracle E-Business Suite Mobile Foundation Push Notification System:
Note: Oracle E-Business Suite Mobile Foundation uses Oracle Mobile Hub (OMH) or Oracle Mobile Cloud Service (MCS) to provide support for push notifications.
Issue | Root Cause | Resolution |
---|---|---|
A mobile user has installed the mobile app that supports push notifications. When the user signs in to the app, no record is created in the FND_MBL_NOTIF_REGISTRATIONS table for the user's appFor a mobile app to receive push notifications, the push token (iOS) or registration ID (Android) should be stored in Oracle E-Business Suite. |
Possible Cause 1: For the mobile app developed using Oracle Mobile Application Framework and Oracle E-Business Suite Mobile Foundation Login Component, the push plug-in is not enabled. | Before deploying the mobile app, a developer needs to enable the push plug-in by selecting the PushPlugin check box in the associated maf-application.xml file. See: Enabling the Push Plug-in, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.Once the push plug-in is enabled, deploy the app and test it again. |
Same issue as the described above | Possible Cause 2: When the mobile device is launched, the device is not connected to the Internet. | If the device is not connected to the Internet, the mobile device cannot connect to its corresponding push notification service. For example, an iOS device connects to APNs to receive push token and an Android device connects to FCM to receive registration ID. To resolve this issue, perform the following tasks:
|
Same issue as the described above | Possible Cause 3: When the mobile app invokes the Oracle E-Business Suite REST API mPushRegister after the user signs in, it fails. |
You can invoke the Oracle E-Business Suite REST API mPushRegister from a REST client, such as Advanced REST Client, to verify if it can successfully create a record in the FND_MBL_NOTIF_REGISTRATIONS table.For instructions on invoking this API, see Checking the mPushRegister REST API. |
Same issue as the described above | Possible Cause 4: The Push Notification System is not enabled and configured with valid Oracle Mobile Hub (OMH) or Oracle Mobile Cloud Service (MCS) credentials. If this configuration is not completed, push notification registrations are not synchronized with OMH or MCS. As a result, push notifications are not sent to users. | You need to ensure the Push Notification System is configured properly.
For information on configuring global push notifications, see Configuring Oracle E-Business Suite Mobile Foundation Push Notification System. |
A mobile user has installed the mobile app that supports push notifications. When the user signs in to the app, no record is created in the FND_MBL_NOTIF_REGISTRATIONS table for the user's Android app |
Android Sender ID and Server Key are not set up correctly. | To resolve the issue, perform the following tasks:
|
When you submit the Mobile Push Notification Configuration page with user credentials, an error occurs indicating that the credentials are invalid. | This issue may occur due to either one of the following:
|
Use the following steps to resolve this issue:
|
Push notification registration STATUS for a user in the FND_MBL_NOTIF_REGISTRATIONS table is "READY". However, it is not changing to "REGISTERED". |
Possible Cause 1: This issue may occur due to either one of the following:
|
To resolve this issue, ensure the following tasks are in place:
|
Same issue as described above. | Possible Cause 2: This issue could also be caused by either of the following:
|
Although the business event oracle.apps.mobile.foundation.push.synch for synchronization is enabled by default, ensure that the event and the subscription are enabled using the Oracle Workflow Business Event user interface through the Workflow Administrator Web Applications responsibility.Additionally, the business event is processed through the WF_JAVA_DEFERRED queue. You need to log in to Oracle E-Business Suite, select the Oracle Applications Manager link, and then Workflow Manager to ensure the Workflow Java Deferred Agent Listener is running. |
Same issue as described above. | Possible Cause 3:The invocation of MCS or OMH REST service from Oracle E-Business Suite to register the mobile device failed because there is no client registered on MCS or OMH corresponding to the Oracle E-Business Suite mobile app distribution. | Use the following steps to ensure the correct distribution is selected for the mobile app:
|
A push registration with status REGISTERED is found for a user, but the push notifications are not delivered to the mobile device. | Possible Cause 1: The possible root causes can be:
|
You can check the notification status:
|
Same issue as the described above | Possible Cause 2: The possible causes can be:
|
To resolve the issue, you need to log in to the Oracle Workflow Business Event user interface through the Workflow Administrator Web Applications responsibility.
|
Same issue as the described above | Possible Cause 3: The user uninstalled the app and then reinstalled it again. However, for the new installation, the registration is not yet created in Oracle E-Business Suite. | Although a valid registration appears in the FND_MBL_NOTIF_REGISTRATIONS table, if the user uninstalled the app that created this registration, Oracle E-Business Suite does not know the app has been uninstalled, so the registration remains in the table.If the user reinstalled the app, then a new push token for iOS or registration ID for Android is issued to the app which is stored in Oracle E-Business Suite again and synchronized with MCS or OMH. |
Same issue as the described above | Possible Cause 4: OMH or MCS is unable to deliver the push notifications. | For each valid record in the FND_MBL_NOTIF_REGISTRATIONS table with status REGISTERED, the corresponding registration should be found in OMH or MCS. Use the following steps to validate:
|
A push registration with status REGISTERED is found for a user, but it is not found in the OMH or MCS's Manage Devices page. | OMH or MCS removed the entry from its registration because it was unable to deliver notifications to the device. | A push notification will not be delivered to the device if the user uninstalled the app after the registration was created earlier. In this situation, there is an entry in the FND_MBL_NOTIF_REGISTRATIONS table, but the corresponding entry is removed by OMH or MCS in its registry. This is expected. The old record in the table is obsolete if OMH or MCS removed the corresponding registration from its registry.To resolve this issue, the user can reinstall the app. The new registration will be created for that user and push notifications can be sent to the device. Note: Currently Oracle E-Business Suite does not remove the registration automatically from the table after OMH or MCS removes it from its registry. |
Push notification is delivered to the device, but it is not translated to the preferred language set in the user's mobile device. | Possible causes for this issue can be:
|
When a registration is created in the FND_MBL_NOTIF_REGISTRATIONS table, the user's device locale is captured in the DEVICE_LANG column in ISO format, such as en-US , ko-KR , etc. It can be translated to the languages supported by Oracle E-Business Suite mobile apps and the notification messages can be translated by the server code that triggers the push notification messages.If the user has multiple devices registered for the same app, the language from the last registration is used to translate the messages. To resolve this issue, set the same language preference in multiple mobile devices. |
In addition to the troubleshooting tips described earlier, this section provides detailed steps to troubleshoot push notifications on the mobile app and the Oracle E-Business Suite server.
If a mobile app does not register for push notifications, you should first review the mobile application log. The mobile app log provides the following details:
Configuration service XML downloaded from the server
The push token received during the launch of the app
Any errors when registering the push token with Oracle E-Business Suite
When a user signs in to an app, as the first step to receive push notifications, the app registers with Oracle E-Business Suite using a REST API. Perform the following tasks to validate the Oracle E-Business Suite REST API:
Use the following steps to authenticate and obtain required token for Oracle E-Business Suite:
Enter the following URL in a web browser and log in with local user name and password to obtain the authentication token.
http://<hostname>:<port>/OA_HTML/RF.jsp?function_id=mLogin
In the response XML, note the following values:
<accessTokenName>ebstest</accessTokenName>
<accessToken>xxxxxxxxxxxxxxxxxxxxxxxxxx</accessToken>
Use these values to form the Cookie header to be used in subsequent REST requests. For example,
Cookie: ebstest=xxxxxxxxxxxxxxxxxxxxxxxxxx
Use this step to check if the mPushRegister
REST API works and stores data in the FND_MBL_NOTIF_REGISTRATIONS
table.
Note: To invoke the REST API directly, install a browser extension, such as Advanced REST Client (ARC) or Postman. You can use any GUI-based REST client to test the REST service.
REST API Details and Payload
HTTP Operation: POST
REST Endpoint: http://<hostname>:<port>/OA_HTML/RF.jsp?function_id=mPushRegister
HTTP Headers:
The content type is: application/xml
Cookie: ebstest=xxxxxxxxxxxxxxxxxxxxxxxxxx
HTTP Payload:
<params> <param name=”Action”>REGISTER</param> <param name=”Platform”>ANDROID</param> <param name=”App Bundle Id”>com.oracle.ebs.atg.owf.Approvals</param> <param name=”Push Token”>xxxxxxxxxxxxxxxxxxxxxxxxxxx-dummy</param> <param name=”Device Lang”>en-US</param> </params>
Note: The "App Bundle Id" parameter should be the same as the one used to register the mobile app in the Mobile Applications Manager UI page. This is the same value used in the Id field of maf-application.xml
in the MAF application.
Invoking the REST API to REGISTER
The following steps describe an example of invoking the REST service directly from the REST client:
Invoke the REST service using the REST Client.
Invocation of the REST API to Register an App in the REST Client
In the HTTP response of REGISTER action, note the JSESSIONID
cookie in the Set-Cookie
header.
This will be passed later in the REST request to remove the registration to make sure the HTTP session is reclaimed on the server.
Check in the FND_MBL_NOTIF_REGISTRATIONS
table for the registration entry for the user entered in the Step 1: Authenticating and Obtaining Required Authentication Token for Oracle E-Business Suite.
Note that the initial status of the registration is "READY". After this registration is synchronized with Oracle Mobile Hub or Oracle Mobile Cloud Service, the status is changed to "REGISTERED".
This step checks if the same mPushRegister
REST API will remove the registration for the app you registered earlier.
REST API Details and Payload
HTTP Operation: POST
REST Endpoint: http://<hostname>:<port>/OA_HTML/RF.jsp?function_id=mPushRegister
HTTP Headers:
The content type is: application/xml
Cookie: ebstest=xxxxxxxxxxxxxxxxxxxxxxxxxxx
JSESSIONID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HTTP Payload:
<params> <param name=”Action”>DEREGISTER</param> <param name=”Platform”>ANDROID</param> <param name=”App Bundle Id”>com.oracle.ebs.atg.owf.Approvals</param> <param name=”Push Token”>xxxxxxxxxxxxxxxxxxxxxxxxxxx-dummy</param> <param name=”Device Lang”>en-US</param> </params>
Invoking the REST API to Remove the Registration
The following steps describe an example of invoking the REST service directly from the REST client:
Invoke the REST service using the Advanced REST Client.
Invocation of the REST API to Remove the Registration in the REST Client
Note that the JSESSIONID
cookie from the REGISTER
action is used here.
Validate the FND_MBL_NOTIF_REGISTRATIONS table that the registration is removed.
If this mPushRegister
API works, the mobile app with the given App Bundle Id should be able to register successfully.
Perform the following tasks to validate the setup in Oracle Mobile Hub or Oracle Mobile Cloud Service:
After a mobile app registers with Oracle E-Business Suite, if the setup tasks performed in Oracle Mobile Hub or Oracle Mobile Cloud Service are successful, the status of the registration should be changed from "READY" to "REGISTERED". If it is not changed to "REGISTERED", you need to check if there is any issue when Oracle E-Business Suite attempts to synchronize with Oracle Mobile Hub or Oracle Mobile Cloud Service. See: Troubleshooting Tips for Common Setup Issues on the Oracle E-Business Suite Server.
Enable the STATEMENT level logging for the Workflow Java Deferred Agent Listener and verify that the business event oracle.apps.mobile.foundation.push.synch
is processed successfully.
Note: The business event to synchronize the registration from Oracle E-Business Suite to Oracle Mobile Hub or Oracle Mobile Cloud Service carries information about the user, app's bundle Id, and mobile platform that you can check for issues with the specific user.
Following are possible errors reported by Oracle Mobile Hub or Oracle Mobile Cloud Service when the registration is synchronized from Oracle E-Business Suite to Oracle Mobile Hub or Oracle Mobile Cloud Service.
HTTP 401
Check the user name and password registered in Oracle E-Business Suite.
The user credentials are validated at the time of configuration. Most likely the credentials are still valid.
Check if the user has the "Mobile Notifications" and "Default – (MCS backend realm)" roles assigned.
HTTP 400
Check if the mobile client is registered on Oracle Mobile Hub or Oracle Mobile Cloud Service with appropriate deployment bundle Id.
HTTP 500
Check if the Oracle Mobile Hub or Oracle Mobile Cloud Service instance is accessible.
SSL handshake error with the following exception:
sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
Make sure to import the OMH or MCS REST endpoint certificates into the truststore in Oracle E-Business Suite.
Perform the following steps to download the OMH or MCS REST endpoint's CA certificate and import to the truststore in Oracle E-Business Suite:
Access the Oracle Mobile Hub or Oracle Mobile Cloud Service endpoint URL in a web browser. For example,
http://<hostname>:<port>
Note: This is the same value entered in the Backend URL field when configuring the Push Notification System. See: Configuring Oracle E-Business Suite Mobile Foundation Push Notification System.
Click the Padlock icon next to the URL in a web browser (such as in Firefox) or use browser-specific steps to export the CA certificate for the OMH or MCS endpoint to a local certificate file.
Export the CA certificate from the browser.
Certificate Viewer Screen with Export Button Highlighted
Import the certificate to the truststore in Oracle E-Business Suite.
keytool -import -trustcacerts -keystore $AF_JRE_TOP/lib/security/cacerts -storepass password -alias verisignclass3g5ca -file verisign.crt
Every device registered in Oracle E-Business Suite is synchronized with Oracle Mobile Hub or Oracle Mobile Cloud Service using the following REST API. It is important that you run this API standalone to make sure the REST API works fine.
MCS REST API Details and Payload Example
HTTP Operation: POST
REST Endpoint: http://<hostname>:<port>/mobile/platform/devices/register
HTTP Headers:
The content type is: application/json
The charset is: UTF-8
Oracle-Mobile-Backend-ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Authorization: Basic <MCS credentials>
HTTP Payload:
{ "notificationToken":"xxxxxxxxxx-xxxxxxxxxx-xx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "notificationProvider":"GCM", "user":"xxxxxx@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxx", "mobileClient":{ "id":"com.oracle.ebs.atg.wf.Approvals", "version":"1.5.0", "platform":"ANDROID" } }
Note: The "user
" attribute could be any string value when testing this API directly. Oracle Mobile Hub or Oracle Mobile Cloud Service does not validate the "user
" attribute against any user repository.
The "mobileClient
" and "id
" attributes should be the same values used to create the mobile client in Oracle Mobile Hub or Oracle Mobile Cloud Service.
The following steps describe an example of invoking the MCS REST service directly using Advanced REST Client:
Invoke the Oracle Mobile Cloud Service REST API from the REST client.
Use the same user name and password registered with Oracle E-Business Suite.
Enter the payload information. Make sure to use the correct Backend ID (Oracle-Mobile-Backend-ID
) that is used to configure the Oracle E-Business Suite Mobile Foundation Push Notification System.
See: Configuring Oracle E-Business Suite Mobile Foundation Push Notification System.
Example of an Oracle Mobile Cloud Service REST Service Invocation in the Advanced REST Client
In the Advanced REST Client, you can click the Edit icon for the Authorization header to enter the Basic Auth user name and password. The tool automatically encodes it to Base64
.
Basic Authentication User Name and Password Directly Entered to the Advanced REST Client
This should return HTTP 201 Created
to indicate the device registration with Oracle Mobile Cloud Service was successful.
Note if you used a dummy value, you could clear it from Oracle Mobile Cloud Service or leave it as is.