Oracle Diagnostics Framework provides the infrastructure to execute diagnostic tests either for troubleshooting or for simply sanity-checking the Oracle E-Business Suite instance periodically or after applying any patch.
Oracle E-Business Suite Diagnostics provides application specific troubleshooting tools that can help shorten problem-resolution time. Oracle E-Business Diagnostics has two major components. They are:
Oracle Diagnostics Framework
Actual diagnostic tests related to individual functional areas
This guide primarily explains how to use the infrastructure. No guidance or explanation is provided about any particular diagnostics test. See My Oracle Support if you are looking for the details of a particular diagnostic test.
The target audience for this manual includes the following:
As a system administrator, running diagnostic tests allows you to check the health of your system. You can use diagnostic tests to identify and resolve problems related to:
Environment
Post-installation setup
Customization
Any other functional problems
If you cannot successfully resolve the problem on your own, you can send the report generated by the tests to Oracle Support.
When performing implementations, you are advised to run diagnostics after every installation or patching process to confirm that the environment is set up correctly and there are no outstanding issues to be resolved.
You can use this manual to learn how to extend the diagnostic tests provided by Oracle.
Features include:
Easy and user-friendly UI to diagnose issues by executing tests
Logical grouping of tests based on functionality
Simultaneous execution of multiple tests to diagnose an issue
Capability to view and download a report
Generation of reports in any format supported by Oracle XML Publisher
Scheduling of diagnostic tests
Ability to schedule test sets
Integration with Role-Based Access Control (RBAC) to execute tests securely
Ability to save and reuse test input values
Support for long-running tests
Support for large-volume reports
Tracking of execution requests using unique request names
Purging of old logs
Support for a set of applications that can be valid for a given test
Support for custom and localized applications to execute diagnostic tests
Preference profile options for setting default applications and a default report format
Performance profile options for setting collection thresholds, SQL block size, and worker thread count
With XML-type tests, no system downtime is needed
Benefits include:
Identify problems at customer's site
Suggest possible fixes to resolve the problems
Generate a detailed report which Oracle support and development teams can analyze for further troubleshooting
Here is a list of terms used in this manual.
Application refers to any application that is bundled in Oracle E-Business Suite.
An ordered set of one or more related tests based on functionality. Every application has one or more groups.
The actual program that is run to diagnose the problem.
A logical grouping of tests across applications and groups that can be used to diagnose a particular business transaction.
The architecture for the Oracle Diagnostics Framework constitutes of the following components:
Standards for diagnostic tests in Java or PL/SQL
Security layer implemented using Role-Based Access Control (RBAC) as implemented in Oracle User Management
An execution engine to execute the test
An API to generate the test report
A user interface for configuration, execution, and viewing the detailed report results
Facility to download the report
Oracle Diagnostics Framework provides a very user-friendly web based interface. The UI is secured using function security and requires a specific responsibility to access the UI namely Application Diagnostics. This responsibility has three menus:
Diagnose - To execute and schedule a test
View Reports - To view the reports of diagnostic tests
Configure - To configure diagnostics
Note: There is no other way to access the Oracle Diagnostics Framework; all other paths are disabled.
Now Diagnostics supports four types of tests, which are:
Java
PL/SQL
XML
Declarative - In this case the diagnostic logic can be configured using the user interface, so no coding is required to diagnose an issue.
The In-context Diagnostics feature uses the inline popup feature in Oracle Application Framework to enable end users to run diagnostic tests from within a product page. If this feature is enabled for a product, an end user with the proper privileges can enter input for a diagnostic test, execute the test, and view the result/report from a current product page without navigating to the Oracle Diagnostics Framework pages to run the test. Note that the user must have the Applications Diagnostics responsibility and executions privileges for the particular test to run the test.
This section describes methods on how to use Oracle Diagnostics Framework to troubleshoot an issue.
Click on the Application Diagnostics responsibility from the Oracle E-Business Suite home page. You will see three menus. Select the menu Diagnose, which will take you to a page where you can see the available diagnostic tests under each application as a hierarchy. By default, tests under an application by the name HTML Platform are displayed. You can select any other application by clicking the Select Application button, which will open up a list of values (LOV). Search using application name or application short name. Searching with wild cards is supported. Also, you can enter multiple search criteria separated by comma (,). From the list displayed, select one or more applications.
This LOV lists all the available diagnostic tests under the selected applications as a hierarchy. Only the tests under the first group of the last selected application will be expanded. You can expand the hierarchy based on your needs.
Select the diagnostic test you want to execute and click on the Execute button, which takes you to the request submission page. You are prompted for the following:
Request Name - A unique name that can be used to track this request. The system will generate a default value. The user can override it.
Indicate whether a downloadable report is needed or not by checking a check box.
Report Format - For tests written using reporting APIs in Release 12.1 and later, the report format can be specified. The Report Format dropdown list is shown only if you have selected the check box for a downloadable report; and the available formats are HTML, PDF, EXCEL and RTF. For legacy tests the report format remains HTML.
Test Inputs - Inputs for the tests if needed.
Enter the needed values and click the Submit button. The results page will be displayed, showing the progress. Click on the Refresh button if the execution is still in progress. Once the test execution is complete, you can view the report online or download it.
Sometimes it will be required to execute multiple tests across applications to diagnose an issue looking from a business perspective. You can bundle a bunch of tests and execute them as part of a single request. This is called as a Test Set. To create a test set, select multiple applications and select the needed tests from the hierarchy and click on the Add to batch button. In the next page all the selected tests will be listed. If you want to add more tests to the test set, click on the Add more tests button. You can also remove tests if they were added inadvertently.
Click on the icon in the column Test Inputs to enter input values for each test. You can enter multiple sets of inputs. You can either enter fresh set of inputs values or select from available pre-configured inputs (input values that are stored in the database for reuse; see the Configuration section for more details). Click on Apply after entering the values. Coming back to the previous page the icon in the column Inputs Available will become a green tick indicating that the inputs were entered for that particular test.
If you opt for a downloadable report then the Download Format column will appear. Enter a valid request name and submit the request. You are then redirected to the View Reports page where the details of the request are shown as a hierarchy. Click on the links available to see the progress of individual test executions. Once the request is completed, you can either view/download the report of individual execution or download the report for the entire request (See the section Reporting for more details).
Instead of executing the test, you can save the test set for future use. See the Test Set section for more details.
Selecting multiple tests every time to diagnose an issue can be cumbersome, so Oracle Diagnostics provides the facility to save the selection for reuse. It is saved as an XML file in the database and includes the input values entered. Confidential inputs (like passwords) are stored in encrypted form.
After selecting the tests and configuring the input values, click on Save Test Set, give the test set a unique name, and save it.
Test Set pages can be directly accessed through the subtab by the same name under the Diagnose tab. You can search for test sets using the name; wild card searches are supported.
You can execute the test set, edit it to add/remove tests or change the input values of any existing tests, duplicate it to create a new one with any changes needed, or delete it.
Another useful feature is to download the test set as an XML file to a local hard drive. Once downloaded the selection can be ported to another instance and can be uploaded using the Upload Test Set button.
If you want to execute a single test with multiple set of input values, you can use the test set feature. This usage is like a test set with a single test.
Execution of diagnostic tests always occurs in a separate thread. The main thread is used to update users with progress in the user interface. However, there are some tests that cannot be executed in a separate thread due to technical reasons associated with the diagnostic logic (like a dependency on an HTTP request or response). Such tests cannot be executed as part of a test set nor can the be scheduled. These tests can be executed as single tests. These tests should be marked according to development guidelines so that the Oracle Diagnostics Framework can identify them at runtime and execute them in the main thread itself.
Scheduling of tests is done via the Concurrent Processing infrastructure. The concurrent request cannot be submitted separately, it must be run only from the Oracle Diagnostics Framework UI.
Click on the Application Diagnostics responsibility from the Oracle E-Business Suite home page. From the three menus, select the menu Diagnose. Select the test and click on the Schedule button. Provide the request name and specify whether a downloadable report is needed or not. Inputs for scheduled tests cannot be given "on the fly" because the execution might happen at a future time. Therefore the engine uses pre-configured input values that are stored in the database. Clicking on the Submit button takes you to the Concurrent Processing pages where more details related to scheduling can be entered before submitting the request. Once the request is submitted, you will be redirected to the Scheduling subtab under the View Reports tab. You can monitor the progress using this page (see the section Reporting for more details). If you schedule the test to be repeated, then the system appends the Concurrent Processing request ID to the request name, making each request unique.
Scheduling of test sets is done through the Concurrent Processing infrastructure. The concurrent request to schedule test sets cannot be submitted separately; it must be run only from the Oracle Diagnostics Framework user interface.
To schedule a test set, select the Application Diagnostics responsibility from the Oracle E-Business Suite home page. From the three menu options, select the menu Diagnose. Select two or more tests and click on the Execute button or click on the Add to batch button. Provide the request name and specify whether a downloadable report is needed or not.
The system will use the test input values stored as part of the test set XML file while executing the test. If there is no input, the system will take the pre-configured inputs stored in the database. If neither of them is available, the test will be skipped during execution of the test set.
A user can create a test set, specifying inputs for the tests as required, and then schedule the test set.
Inputs for a test set can be entered when it is created or updated. A test set can be scheduled to execute immediately or at a future time. Clicking on the Save Test Set button takes you to the Test Set Details page where you can enter a name for the test set and enters a description before clicking the Apply button. Once you are on the View Test Sets page, clicking on the Schedule icon takes you to Concurrent Processing pages where more details related to scheduling can be entered before submitting the request. Once the request is submitted, you will be redirected to the Scheduling subtab under the View Reports tab. You can monitor the progress using this page (see the section Reporting for more details). If you schedule the test to be repeated, then the system appends the Concurrent Processing request ID to the request name, making each request unique.
Oracle Diagnostic Framework now makes it possible for users with custom responsibilities to run diagnostic tests. For example, applications that have been cloned from a seeded Oracle application can include these custom responsibilities. Also, customers running localizations can create a custom role and a custom grant that map to an Oracle seeded application. Once these tasks are done, the system will recognize the mapping between custom/localized applications and seeded applications. The responsibility LOV provided by the framework will show the responsibilities of the user associated with custom applications.
Setting up for the execution of tests using custom responsibility with a seeded application includes these tasks:
Create a new role one per seeded application that needs to be customized.
The Role Code uses ODF_CUSTOM_<Seeded Application Short Name>_Role format.
Note that Oracle User Management updates the role name by prepending 'UMX|' to the role code entered (when the role is created).
Create a grant to this role using the following information:
Set Grantee Type to 'Group Of Users'
Set Grantee to 'ODF_CUSTOM_<Seeded Application Short Name>_ROLE'
Set Object to 'ODF_CUSTOMIZATION_OBJ'
Set 'ODF_EXECUTION_PS'
Set Data Context Type to 'Instance'
Set Instance Primary Key to '<Custom Application Short Name>'
Once this setup is done, the system will recognize mapping between custom/localized applications and seeded applications. The responsibility LOV provided by the framework will start showing the responsibilities of the user associated with custom applications.
Click on the Application Diagnostics responsibility from the Oracle E-Business Suite home page. From the three menus, select the menu View Reports. You can search for the reports of diagnostic tests using a simple search or an advanced search. In a simple search, you use the request name. Wild card searches are not supported. In an advanced search, you can provide multiple criteria like test details, dates, status, and so on.
The results of the search are displayed as a hierarchy with different columns which show counts for total execution, success, failure, warning, in-progress and in-queue. Except for the in-queue count, you can click the count link and drill down to see the details. In-queue means the test execution has not yet started and the test is in queue. A refresh button appears if the execution is in queue or the execution/downloadable report generation is in progress.
If the search was conducted using the request name, you can download all the reports, which are part of the request, as a single ZIP file. Otherwise you have to drill down and download each report individually.
You can specifically search for scheduled tests using the Scheduling subtab under View Reports. A search can be conducted based on the dates or the concurrent request ID, as well as the request name using wildcard support. The results are shown in a table. A refresh icon is available to refresh the data. In the table are columns with diagnostics request name and the concurrent request ID. Both of these are links that can be used to drill down for details. The diagnostics request name gives you the details of the diagnostic execution and the concurrent request ID will give details on the concurrent request. In the diagnostic request name column, the link will not be enabled until the execution of the request is completed.
Use the concurrent program Delete Diagnostic Logs to purge the old logs. You can specify values for the two parameters:
Days Expire - Logs older than this will be deleted.
Application short names - Logs of the applications listed will be purged. Specify a comma-separated list of values.
Only Aborted/Long Pending - If Yes, only logs of executions in aborted status or pending status for long durations will be purged.
You can specify a value of either parameter or a combination.
Security in diagnostics is implemented at two levels, UI and data. The UI is secured using function security and the content as well as actions available within each page is controlled using data security
Using function security, only users with Application Diagnostics responsibility will be able to access the UI for diagnostics.
Data security is achieved using Role-Based Access Control (RBAC). The actions that a user can perform are grouped into different categories. Roles are created and Grants are given to each role to perform different categories of actions. The section below describes the implementation data security. We assume that the user has some basic understanding of RBAC. Please see Overview of Oracle User Management, Oracle E-Business Suite Security Guide to learn more.
Sensitivity is an attribute of the test that indicates the kind of data it is dealing with. There are three levels - High, Medium and Low.
A permission is, as the name suggests, the permission to do an action. There are four permissions in diagnostics.
Execute a test
View the report of an execution
Pre-configure inputs for a test
Configure diagnostics
This is a logical grouping of permissions. Grants are given using permission sets. There are three permission sets in diagnostics
Execution permission set
Execute a test
Pre-configure inputs
Reporting permission set
View report of an execution
Configuration permission set
Configure diagnostics
The execution permission set has the permission to execute a diagnostic test and pre-configure input values for the test.
The reporting permission set has the permission to view the detailed report of an execution. The reporting permission set is a child of execution permission set so that any user who has the latter will also get the former. It is possible to change this configuration (see the section Customizing Security).
The configuration permission set has the permission to configure diagnostics.
Diagnostics comes with three roles. A user must have any one of these roles to do diagnosis. All three roles have the Application Diagnostics responsibility attached to it so that UI access is available by default. Following are the three roles:
Diagnostics Super User - Has unrestricted execution and configuration access
Application Super User - Is able to execute any high or medium sensitivity test, if he or she has a valid responsibility either in the application under which the test is registered or in any of the application, which is configured as valid for test.
Application End User - is able to execute any medium sensitivity test, if he or she has a valid responsibility either in the application under which the test is registered or in any of the application, which is configured as valid for test.
Users with any diagnostic role can access low sensitivity tests registered under any application.
The following security matrix table below gives a detailed picture:
The following table describes how Oracle Diagnostic Framework functions can be used by different types of users.
| Function | Diagnostics Super User | Application Super User | Application End User |
| Select, Execute Tests, View Execution Results | Yes | High, medium, and low sensitivity tests if the user has a responsibility in any valid application of the test; otherwise, only low sensitivity tests. | Medium and low sensitivity tests if the user has a responsibility in any valid application of the test; otherwise, only low sensitivity tests. |
| Scheduling | Same as Execution | Same as Execution | Same as Execution |
| View Reports | Same as Execution | Same as Execution | Same as Execution |
| Configure Test Input Values | Same as Execution | Same as Execution | Same as Execution |
| View Registered Applications, Groups, and Tests | Yes | Yes | Yes |
| Register Applications, Create/Edit/Delete Tests and Groups | Yes | No | No |
Grants are used to give access to different roles. The JTF_DIAGNOSTIC_TEST table is used to give execution/reporting grants while the JTF_DIAGNOSTIC_APP table is used to give configuration grants. Diagnostics ships four grants:
Diagnostic Super User Execution Grant - Gives Execution Permission Set to all instances of JTF_DIAGNOSTIC_TEST table.
Diagnostic Super User Configuration Grant - Gives Configuration Permission Set to all instances of JTF_DIAGNOSTIC_APP.
Application Super User Execution Grant - Gives Execution Permission Set to an instance set of JTF_DIAGNOSTIC_TEST. The instance set is called Diagnostics Execution Instance Set. Its predicate takes two parameters. Parameter 1 is the sensitivities allowed for its own application. Parameter 2 is the sensitivities allowed for other applications. In this case Parameter 1 is 4 and Parameter 2 is 2. (Value 4 stands for all sensitivities. Value 3 stands for medium and low. Value 2 stands for only low.)
Application End User Execution Grant - Gives Execution Permission Set to an instance set of JTF_DIAGNOSTIC_TEST. The instance set is called Diagnostics Execution Instance Set. Its predicate takes two parameters. In this case Parameter 1 is 3 and Parameter 2 is 2.
The security model can be customized if you do not want to use the roles out of the box. To do this, perform the following steps. Note that you should follow this procedure separately for execution and for configuration; that is, create separate roles, permission sets, and grants for execution and for configuration.
Create a new role.
Attach the Application Diagnostics responsibility to this role.
Create a new permission set with all desired permissions.
Give a grant to this role using the Diagnostic Execution instance set.
Assign the role to the user.
This application is a non-secure application and all users have full access to all tests under it. This application is used to diagnose the issues related to security if security is not working properly.
This section briefly describes the tasks involved in configuring Oracle Diagnostics Framework. For more information on these tasks, see the next chapter.
Tests are owned by applications. Each application must be registered. Use the Register Application page to register applications.
It is possible to define a set of applications for which a test is valid. This task can be done using the configuration UI. This is applicable only to high- and medium- sensitivity tests. Low-sensitivity tests are valid for all applications. The values that are hardcoded in the existing tests are moved to the database by a migration concurrent program called "Diagnostics Patching CP". During an upgrade, this concurrent program is run automatically as part of the upgrade process. Once the upgrade is complete, please make sure that this concurrent program was executed successfully. The short name of this concurrent program is "DIAGPATCHINGCP". If this concurrent program has not been run, then you can run it manually.
Tests in an application can be organized into groups. Use these pages to manage your groups.
Note: Seeded groups cannot be edited or deleted by end users.
Use these pages to create, edit, delete, and re-order your tests.
Note: Seeded tests cannot be edited or deleted by end users.
Pre-configured inputs are input values for a test entered during configuration, prior to running the test.