Oracle E-Business Suite Mobile Apps - 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:

Server logging
Client logging
REST service auditing

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.

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

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.

Retrieving Client Logs

Direct mobile app 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.
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 appropriate information based on the Oracle E-Business Suite Mobile Foundation release:
  - For Oracle E-Business Suite Mobile Foundation Release 2.0, enter "MOBILE" as the Module name.
  - For Oracle E-Business Suite Mobile Foundation Release 2.1 and onwards, 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 is displayed. Otherwise, only a simple error message is shown instead.

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.

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.

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 Initiate Server Updates

In Oracle E-Business Suite Mobile Foundation Release 2.1 or later releases, while 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.
  Please note that 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 URLbutton. 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.
  
  Note: The Change URL button is available in Oracle E-Business Suite Mobile Foundation Release 3.0 and onwards.
  To initiate the reconfiguration process in Oracle E-Business Suite Mobile Foundation Release 2.1, mobile users must manually navigate to the iOS device's Settings screen to update the URL value.
  
  Additionally, 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.
  - 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.
To check if any new updates from the server are required for the app, tap the Sync icon next to the Server Configuration region in the Connection Details screen. 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
When a user enters a server URL in a mobile device using HTTPS, if the SSL certificate is invalid or untrusted and cannot be recognized by the mobile app, the following error message may appear: "Please enter a valid URL."	Ensure that your mobile app can perform a successful SSL handshake with the Oracle E-Business Suite SSL endpoint. Validate that the JDK 8 client can connect to the Oracle E-Business Suite SSL endpoint. Validate that the Oracle E-Business Suite SSL endpoint presents the complete certificate chain. For validation instructions, see the detailed steps as described in 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, Oracle Mobile Application Framework Installing Oracle Mobile Application Framework. For information on the Oracle MAF version required for your app, see Section 1: Oracle E-Business Suite Mobile Foundation Release Update History, 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 tappingConnection 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.
The configuration server URL is not accessible when tested from a web browser. An HTTP 404 error appears. (For Oracle E-Business Suite Mobile Foundation Release 3.0 and earlier)	Verify that AutoConfig was run after you applied the appropriate consolidated patch for your Oracle E-Business Suite release.
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 and set up during 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 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.
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: 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. 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. Run AutoConfig and ensure there is no error. 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: Check if the user has entered http:// or https:// as appropriate for accessing your Oracle E-Business Suite server. Make sure that the user has entered the correct host name and domain. 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.
A user taps Settings from the mobile app navigation menu, then taps Connection Details to display the Connection Details screen. However, the Sync icon is not shown.	If the app is connected to Oracle E-Business Suite Mobile Foundation releases earlier than Release 2.1, the Sync icon is automatically hidden. This Sync icon is shown only if the server is configured for Oracle E-Business Suite Mobile Foundation Release 2.1 or later releases.
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. (For Oracle E-Business Suite Mobile Foundation Release 2.1 or later)	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.
After a mobile user enters a valid server URL in the Server URL screen, and then enters his or her user name and password in the login screen, the following message appears: Configuration Error - This mobile application is not currently configured on this server. Please close the application. (For Oracle E-Business Suite Mobile Foundation Release 2.0 only)	This message indicates that the app is unable to access the configuration service URL. Perform the following steps to resolve the issue: Verify if the configuration service URL is accessible through a web browser by performing the following steps: Construct the configuration service URL in the following format: http(s)://<hostname>:<port>/OA_HTML/config/<application bundle id>/connections.xml For the Application Bundle Id information for each mobile app, see Appendix C: Application Definition Metadata. Copy the configuration service URL you just constructed and paste it into a browser window. When prompted, enter the Oracle E-Business Suite user name and password. The browser loads the configuration file connections.xml. The file is loaded only if the app is configured and enabled on the server. Verify the content to ensure that the configuration file for your mobile app is valid, well-formed XML, and validate that the configuration parameter values are the same values as configured from the Mobile Applications Manager UI pages. Verify if the app is enabled by performing the following steps: Log in to Oracle E-Business Suite as SYSADMIN user. Select the Mobile Applications Manager responsibility and choose the Applications link. Search and locate your mobile app. Ensure the status of your app is set to "Enabled".

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
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: Make sure the concurrent manager is running. 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. 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.	In Oracle E-Business Suite Mobile Foundation releases earlier than Release 2.1, the configuration file is not updated to the client automatically when it is changed. To obtain the updated configuration file, users must uninstall the mobile app and then install it again. In Oracle E-Business Suite Mobile Foundation Release 2.1 and onwards, a mobile user can initiate the server updates from the mobile device. See Directing Users to Obtain Connection Details and Initiate Server Updates.

Learning Oracle

Pages

Wednesday, May 4, 2016