Diagnostics and Troubleshooting

Overview

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:

Enabling the Logging and Diagnostics Features

Troubleshooting Oracle E-Business Suite mobile apps involves the following high level options:

To better understand these logging and auditing features, this section includes the following topics:

Enabling Server Logging

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.

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:

  1. 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.

  2. In the Search System Logs page, click the Advanced Search button.

  3. 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.

  4. Run the search to retrieve and download the desired server logs.

Enabling Client Logging

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.

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.

  1. 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.

  2. Direct the app user to turn on diagnostics logging on the mobile client.

  3. 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.

  4. 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.

  5. Request the mobile app user to upload the log file from the mobile client to the server.

  6. Retrieve the REST service log statements based on the profile options set in step 1.

  7. 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:

  1. 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.

  2. Return to the navigation menu and reproduce the reported issue.

  3. In the menu, tap Settings and then the Diagnostics again.

  4. 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

    the picture is described in the document text

  5. 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:

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.

  1. Use a file browser app on Android. For example, My Files, ES File Explorer.

  2. Look for files that start with the app name. For example, Approvals.txt, Approvals_bak.txt.

  3. Attach these files to an email through your preferred email app and upload to Oracle Support.

Enabling REST Service Auditing

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.

  1. 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.

  2. 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.

Troubleshooting Tips

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.

Troubleshooting Tips on the Mobile Client

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

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:

  1. In the navigation menu of the mobile app, tap Settings and then Connection Details. The Connection Details screen appears.

  2. 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)

      the picture is described in the document text

      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.

  3. 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.

Troubleshooting Tips for Oracle E-Business Suite Mobile Apps

The following table lists common issues that might occur while using Oracle E-Business Suite mobile apps as well as the corresponding solutions.

Troubleshooting Tips on the Mobile Client
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.

  1. Validate that the JDK 8 client can connect to the Oracle E-Business Suite TLS endpoint.

  2. Check the list of root CAs trusted by the mobile client.

    • For apps built with Oracle E-Business Suite Mobile Foundation 9.1 and 9.0, refer to "Migrating to New cacerts File for SSL in MAF 2.6.0", Installing Oracle Mobile Application Framework, plus the following migration motes:

      • For Release 9.1- Oracle Mobile Application Framework 2.6.3 Migration Notes (https://www.oracle.com/applicationdevelopment/ technologies/maf/maf263migration.htm)

      • For Release 9.0 - Oracle Mobile Application Framework 2.6.2 Migration Notes (https://www.oracle.com/applicationdevelopment/ technologies/maf/maf262migration.htm)

    • For apps built with Oracle E-Business Suite Mobile Foundation 8.0 and 7.0, refer to Migrating to New cacerts File for SSL in MAF 2.5.0 and Migrating to New cacerts File for SSL in MAF 2.4.0 respectively.

    To locate the Oracle MAF documentation for the apps built with the MAF version earlier than 2.6.3, see "Previous releases of Oracle Mobile Application Framework Documentation" (https://www.oracle.com/application-development/technologies/maf/maf-prev-rel. html).


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.

  1. Validate that the JDK 8 client can connect to the Oracle E-Business Suite TLS endpoint.

  2. Validate that the Oracle E-Business Suite TLS endpoint presents the complete certificate chain.


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:

  • For Oracle E-Business Suite 12.1.3, apply patch 21643419:R12.FND.B

  • For Oracle E-Business Suite 12.2, apply patch 22046560:R12.FND.C


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.
test for PID

Note: When an app user is authenticated, the mLogin REST service creates an Oracle E-Business Suite session for that user along with an XML response with authentication token (cookie) which uniquely identifies that session. To secure each user session, a profile option "FND: Authn Service Token Scope (FND_AUTHN_SRVC_TOKEN_SCOPE)" is introduced in the January 2023 Critical Patch Update with the default value "Header Only" at the Site level. This default value sets the ICX cookie only in the response header of the mLogin REST service, and will not return the cookie details in the response payload. If you have custom code that calls the mLogin REST service and requires the cookie details in the response payload, then you can optionally change the value to "Header and Body". In this case, the mLogin service sets the ICX cookie in the header and also returns the cookie name and value in the payload.
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:

  1. Verify if AOLJRestServlet exists in the following file:

    • For Oracle E-Business Suite Release 12.2.x, locate the servlet in the $OA_HTML/WEB-INF/web.xml file.

    • For Oracle E-Business Suite Release 12.1.3, locate the servlet in the INST_TOP/ora/10.1.3/j2ee/oacore/application-deployments/oacore/html/orion-web.xml file.

  2. If AOLJRestServlet does not exist, then verify if the app uses a custom template.

    • If a custom template is used, the custom template must be synchronized with the seeded templates. See Section 4.2: Implementing AutoConfig Customizations, My Oracle Support Knowledge Document 387859.1.

    • If a custom template is not used, continue to the next step.

  3. Run AutoConfig and ensure there is no error.

  4. Stop and restart the application tier server and then verify 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:

  1. Check if the user has entered http:// or https:// as appropriate for accessing your Oracle E-Business Suite server.

  2. Make sure that the user has entered the correct host name and domain.

  3. Make sure that the port number if used is valid.
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.

Troubleshooting Tips 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:

Troubleshooting Tips on the Oracle E-Business Suite Server

The following table describes common issues that might occur on the Oracle E-Business Suite server as well as the corresponding solutions.

Troubleshooting Tips on the Oracle E-Business Suite Server
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:

  • This preconfigured URL has a valid format: http(s)://<host>:<port>

  • Enter the URL in a web browser and make sure that you are able to access the Oracle E-Business Suite home page successfully.

  • From a web browser, invoke the login service as http(s)://<host>:<port>/OA_HTML/RF.jsp?function_id=mLogin and verify that it prompts for user name and password.
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:

  1. Make sure the concurrent manager is running.

  2. Submit a concurrent request for the "Workflow Directory Services User/Role Validation" concurrent program (FNDWFDSURV).

    Ensure that you set the "Add missing user/role assignments" parameter to Yes. You can leave the other parameters set to the default values.

  3. Submit a concurrent request for the "Compile Security" concurrent program.
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.

Troubleshooting Tips on Configuring Apps With the Apps SSO Login Authentication Type

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:

  1. Verify prerequisite configuration for Oracle E-Business Suite, Oracle Access Manager (OAM), and Oracle Directory Services integration

    1. 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.

    2. Verify after successful login and rendering of the Oracle E-Business Suite Home page, the user has Oracle E-Business Suite responsibilities assigned.

    3. 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.

  2. Test the configured "SSO Login URL", "SSO Login Success URL", and "SSO Logout URL" parameters

    1. 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.

    2. 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.

    3. Navigate to the configured SSO Logout URL. For example, http://<hostname>:<port>/accessgate/logout/sso.

      Expected result: User logged out successfully.

    4. Perform the same tests using your mobile device browser.

  3. Test the configured "EBS Session Service" parameter

    1. 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>

    2. Perform the same test using your mobile device browser.

  4. Collect HTTP header traces and logs

    1. Collect HTTP Header traces during the implementation of the above test points.

    2. 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.

Troubleshooting Tips for Push Notifications

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:

For more information about push notifications, see Setting Up Push Notifications for Mobile Apps.

Troubleshooting Tips for Enabling Push Notifications on the Mobile Client

The following table lists the troubleshooting tips for enabling push notifications on the mobile client:

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:

  • For the iOS devices

    1. Tap Settings.

    2. Open the mobile app enabled with push notifications.

    3. Enable the Allow Notifications option.

  • For the Android devices

    1. Tap Settings.

    2. Navigate to Application Manager.

    3. Open the mobile app enabled with push notifications.

    4. Tap Notifications, and then enable the Allow Notifications option.

Troubleshooting Tips for Common Setup Issues on the Oracle E-Business Suite Server

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.

Troubleshooting Tips for Common Setup Issues in the Oracle E-Business Suite Mobile Foundation Push Notifications System
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 app
For 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:

  1. Make sure the device is connected to the Internet.

  2. Restart the app.

  3. Sign in to Oracle E-Business Suite and check again.
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.

  1. Log in to Oracle E-Business Suite as a user who has the Mobile Applications Manager responsibility. Click the Push Configuration button to open the Mobile Push Notification Configuration page.

  2. Verify if the Push Notification System field is set to "ENABLED" in the Mobile Push Notification Configuration page.

  3. Verify if the setup for Oracle Mobile Hub or Oracle Mobile Cloud Service is completed with valid credentials.

  4. To support Android push notifications, make sure you enter a valid Android Sender ID value.


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:

  1. Go to the Firebase console (https://console.firebase.google.com). Open the project created for the Android push notifications and record the Sender ID and Server Key values.

  2. Make sure these values are entered correctly in the following setup 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:

  • The user name, password, backend ID, or URL is invalid.

  • The user does not have the "Default" and "Mobile Notifications" roles assigned in the Oracle Cloud My Services portal.

  • Oracle E-Business Suite to MCS or OMH REST service invocation failed due to TLS handshake.

 Use the following steps to resolve this issue:

  1. Check the OACORE logs to see if the REST service invocation failed with TLS handshake when Oracle E-Business Suite invoked the MCS or OMH URL for validation.

  2. If yes, download the MCS or OMH URL's CA certificate and import the certificate to the truststore in Oracle E-Business Suite.

    For instructions on importing the certificates to the truststore in Oracle E-Business Suite, see Fixing the SSL Handshake Error.
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:

  • The Push Notification System is not enabled and configured with valid user credentials.

  • Oracle E-Business Suite to MCS or OMH REST service invocation failed due to TLS handshake.

 To resolve this issue, ensure the following tasks are in place:

  • The Push Notification System is configured properly.

    1. Log in to Oracle E-Business Suite as a user who has the Mobile Applications Manager responsibility. Click the Push Configuration button.

    2. Verify if the Push Notification System field is set to "ENABLED" in the Mobile Push Notification Configuration page.

    3. Verify if the setup for Oracle Mobile Hub or Oracle Mobile Cloud Service is completed with valid credentials.

    4. To support Android push notifications, make sure you enter a valid Android Sender ID value.

  • Oracle E-Business Suite can successfully invoke the MCS or OMH REST service.

    Download the MCS or OMH URL's CA certificate and import the certificate to the truststore in Oracle E-Business Suite. See Fixing the SSL Handshake Error.
Same issue as described above. Possible Cause 2: This issue could also be caused by either of the following:

  • The business event used to synchronize the registration from Oracle E-Business Suite to Oracle Mobile Hub or Oracle Mobile Cloud Service is not enabled.

  • The Workflow Java Deferred Agent Listener is not running.

 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:

  1. Log in to Oracle E-Business Suite as a user who has the Mobile Applications Manager responsibility.

  2. Locate the mobile app and click Configure.

  3. Under the "Push Notifications" configuration category, make sure the following parameters are valid:

    • Android Deployment Bundle ID: Enter the same Package Name used to package the Android app. Make sure in MCS or OMH, an Android client is created with the same Package Name.

    • iOS Deployment Bundle Id: Enter the same Application Bundle ID used to package the iOS app. Make sure in MCS or OMH, an iOS client is created with the same Application Bundle ID.
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:

  • On Oracle E-Business Suite, the Push Notification Agent service component is not running.

  • On MCS or OMH, the notification could not be delivered to APNs or FCM for delivery to the mobile device.

 You can check the notification status:

  • If the notification status is "QUEUED" in the FND_MBL_NOTIFICATIONS table, verify and ensure that the service component Push Notification Agent is running.

  • If the status is "SENT" indicating that Oracle E-Business Suite has sent the notification to MCS or OMH, log in to MCS or OMH to check the API log and confirm MCS or OMH has delivered the notification to APNs for an iOS device, and FCM for an Android device.

    Please note that after the Push Notification Agent successfully sent the notification to MCS or OMH and changed the status to "SENT", it is the responsibility of MCS or OMH to deliver the notifications to the user's devices.
Same issue as the described above Possible Cause 2: The possible causes can be:

  • The push notification business event associated with the mobile app is not enabled.

    Each app has its own business event. For example, the Approvals app with enterprise distribution uses business event oracle.apps.mobile.approvals.push.event.

    For information on creating an event for your app, see Creating Push Notification Business Events, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.

  • The push notification business event is not added to the Push Notification System's business event group oracle.apps.mobile.foundation.push.group.

    For information on adding an event to the event group, see Adding the Push Notification Business Events to the Push Notification System's Event Group, Oracle E-Business Suite Mobile Apps Developer's Guide, Release 12.1 and 12.2.

 To resolve the issue, you need to log in to the Oracle Workflow Business Event user interface through the Workflow Administrator Web Applications responsibility.

  • Verify the push notification business event for the mobile app is Enabled.

  • Verify the business event is added to the business event group.

  • Verify the subscription to the business event group is Enabled. The subscription processes the push notifications and enqueues them to the FND_MBL_NOTIFICATION_OUT queue.
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:

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

  2. Click the menu icon to open the side menu.

    • For OMH, select Development, and then Mobile Backends.

    • For MCS, select Applications, and then Mobile Backends

  3. Select your mobile backend and click Open.

  4. Select Notifications, then TEST, and then Manage Devices.

  5. Check if you can find a valid OMH or MCS registration for the corresponding record in the FND_MBL_NOTIF_REGISTRATIONS table.

    Please note that push registrations are stored in the following format:

    • Service: iOS or Android

    • Username: <EBS username>@<EBS system guid>.<EBS DB SID>

    • Application Id: iOS Application Bundle Id or Android Package Name used to create the mobile client.
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:

  • The user's mobile device language preference is not installed or supported by Oracle E-Business Suite mobile apps.

  • The user has installed the same app in multiple devices and each device has a different language setting.

 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.

Steps to Troubleshoot Push Notification Issues

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.

  1. Checking the Mobile Application Log

  2. Checking the Oracle E-Business Suite REST API

  3. Checking the Oracle Mobile Hub or Oracle Mobile Cloud Service Setup

Step 1: Checking the Mobile Application Log

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:

Step 2: Checking the Oracle E-Business Suite REST API

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:

  1. Authenticating and Obtaining Required Authentication Token for Oracle E-Business Suite

  2. Checking the mPushRegister REST API

  3. Removing the Registration Using the mPushRegister REST API

Step 1: Authenticating and Obtaining Required Authentication Token for Oracle E-Business Suite

Use the following steps to authenticate and obtain required token for Oracle E-Business Suite:

  1. 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

  2. In the response XML, note the following values:

    • <accessTokenName>ebstest</accessTokenName>

    • <accessToken>xxxxxxxxxxxxxxxxxxxxxxxxxx</accessToken>

  3. Use these values to form the Cookie header to be used in subsequent REST requests. For example,

    Cookie: ebstest=xxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Checking the mPushRegister REST API

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

Invoking the REST API to REGISTER

The following steps describe an example of invoking the REST service directly from the REST client:

  1. Invoke the REST service using the REST Client.

    Invocation of the REST API to Register an App in the REST Client

    the picture is described in the document text

  2. 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.

  3. 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".

Step 3: Removing the Registration Using the mPushRegister REST API

This step checks if the same mPushRegister REST API will remove the registration for the app you registered earlier.

REST API Details and Payload

Invoking the REST API to Remove the Registration

The following steps describe an example of invoking the REST service directly from the REST client:

  1. Invoke the REST service using the Advanced REST Client.

    Invocation of the REST API to Remove the Registration in the REST Client

    the picture is described in the document text

  2. Note that the JSESSIONID cookie from the REGISTER action is used here.

  3. 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.

Step 3: Checking the Oracle Mobile Hub or Oracle Mobile Cloud Service Setup

Perform the following tasks to validate the setup in Oracle Mobile Hub or Oracle Mobile Cloud Service:

  1. Examining Any Synchronization Issues from Oracle E-Business Suite to Oracle Mobile Hub or Oracle Mobile Cloud Service

  2. Fixing the SSL Handshake Error

  3. Checking the Oracle Mobile Hub REST API or Oracle Mobile Cloud Service REST API

Step 1: Examining Any Synchronization Issues from Oracle E-Business Suite to 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.

  1. 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.

  2. 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

Step 2: Fixing the SSL Handshake Error

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:

  1. 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.

  2. 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.

  3. Export the CA certificate from the browser.

    Certificate Viewer Screen with Export Button Highlighted

    the picture is described in the document text

  4. 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

Step 3: Checking the Oracle Mobile Hub or Oracle Mobile Cloud Service REST API

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

The following steps describe an example of invoking the MCS REST service directly using Advanced REST Client:

  1. Invoke the Oracle Mobile Cloud Service REST API from the REST client.

  2. Use the same user name and password registered with Oracle E-Business Suite.

  3. 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

    the picture is described in the document text

  4. 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

    the picture is described in the document text

  5. 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.