Oracle Workflow Diagnostic Tests

This appendix describes the diagnostic tests that workflow administrators can run to check the setup of Oracle Workflow in an Oracle Applications installation.

This appendix covers the following topics:

Oracle Workflow Diagnostic Tests

Oracle Workflow Diagnostic Tests

Oracle Diagnostics provides a mechanism which makes Oracle Applications more supportable and robust by providing predefined tests to check for key setup requirements. Oracle Workflow provides several tests through Oracle Diagnostics that you can use to check the setup of Oracle Workflow in an Oracle Applications installation and review debugging information.

You can access Oracle Diagnostics through several different user interfaces, including Oracle Applications Manager as well as other administrative consoles. For more information, see: Launching Oracle Diagnostics, Oracle Applications Supportability Guide.

The Oracle Workflow tests are available in Oracle Diagnostics under the Application Object Library application.

Workflow Tests

The following tests are available in the Workflow Tests group.

Duplicate User Test

This test checks the Oracle Workflow directory service to verify that there are no roles in the WF_LOCAL_ROLES table with the same internal name, originating system, and originating system ID. This test does not require any input parameters.

If any duplicate roles are found, the test reports the internal name, display name, originating system, and originating system ID of those roles. Use this information to investigate and remove any invalid roles from your directory service. Otherwise, users may encounter errors when accessing their workflow processes and notifications. See: Setting Up an Oracle Workflow Directory Service.

Notification Preference Validation Test

This test checks the Oracle Workflow directory service to ensure that all roles with a notification preference for receiving e-mail notifications have an e-mail address defined. This test does not require any input parameters.

If any roles with a notification preference for e-mail do not have an e-mail address defined, the test reports the internal name, display name, originating system, originating system ID, and notification preference of those roles. Enter e-mail addresses for these roles in the Oracle Workflow directory service to enable notification mailers to send them e-mail notifications. If any roles should not receive e-mail notifications, change the notification preference for those roles to QUERY ("Do not send me mail"). See: Implementing Notification Mailers, Setting Up an Oracle Workflow Directory Service, Setting Global User Preferences, and Preferences, Oracle Applications User's Guide.

Rule Function Validation Test

This test checks the rule functions defined for subscriptions and the generate functions defined for events in the Business Event System. For PL/SQL functions, the test verifies that the package and function exist in the database and are valid. For Java functions, the test verifies that the Java class exists in the classpath. This test does not require any input parameters. See: Event Subscriptions, Oracle Workflow Developer's Guide and Events, Oracle Workflow Developer's Guide.

If any subscription rule functions or event generate functions are missing or invalid, the test reports the name and problem status for each function. You must make these functions available for the Business Event System to execute the corresponding subscriptions or generate the event data for the corresponding events. For PL/SQL functions, load the appropriate packages and standalone functions to the database, and recompile the schema that owns them. For Java functions, ensure that your classpath includes the JAR files containing the appropriate classes.

GSM Setup Test

This test checks the Generic Service Management (GSM) setup required for Oracle Workflow in Oracle Applications Manager (OAM). Oracle Workflow implements service component containers for its Generic Service Component Framework as GSM service instances. The test verifies that GSM and the Oracle Workflow service instances are enabled. It also checks whether a high number of operating system processes have been created for a service instance in the last few minutes, which may indicate an error. This test does not require any input parameters.

The test reports the status of GSM and of the Oracle Workflow service instances.

If GSM is disabled, set the Concurrent: GSM Enabled profile option to Y. See: Overview of Setting User Profiles, Oracle Applications System Administrator's Guide.
If an Oracle Workflow service instance is disabled, enable it using OAM. Navigate to the Service Components page in Oracle Workflow Manager, and choose the appropriate service instance link in the Container column. In the Service Instances for Generic Service Component Container page, select the service instance, and select the Edit button. In the Edit page, select the Enabled check box. For more information, see the Oracle Applications Manager online help.
OAM creates new operating system processes for a service instance each time the service instance is started. If a high number of operating system processes have been created for a particular service instance in the last few minutes, there may be an error that is causing that service instance to become continually deactivated and then restarted by OAM. Use the service instance log to investigate any possible errors. To view the log, navigate to the Service Components page in Oracle Workflow Manager, select a service component belonging to the appropriate service instance, and choose the View Log button. You can also choose the service instance link in the Container column to review the current number of actual and target processes in the Service Instances for Generic Service Component Container page. For more information, see the Oracle Applications Manager online help.

BES Clone Test

This test checks certain standard agents and subscriptions required for internal Business Event System and notification mailer processing to verify that they are enabled and that their definitions include the correct local system. You can use this test after cloning or migrating an Oracle Applications instance to ensure that the local system references have been updated correctly for the new instance. This test does not require any input parameters.

The test reports the name of the local system currently defined in the global workflow preferences, as well as the standard agents and subscriptions to events required for internal processing. For each agent, the report shows the agent name, system name, and status. For each subscription, the report shows the event name, subscription rule function together with the subscribing system, out agent, and status.

If the local system name is incorrect, use the Workflow Configuration page to update the Local System preference. See: To Set Global Preferences for Oracle Workflow Embedded in Oracle Applications.
If any agent is assigned to an incorrect system or is disabled, use the Update Agent page to update that agent definition. See: Agents, Oracle Workflow Developer's Guide.
If any subscription has an incorrect subscribing system, has an out agent assigned to an incorrect system, or is disabled, use the Update Event Subscriptions page to update that subscription definition. See: Event Subscriptions, Oracle Workflow Developer's Guide.

GSC Control Queue Test

This test verifies that the Workflow control queue, WF_CONTROL, is properly accessible. The Generic Service Component Framework uses this queue to handle control events for containers and service components. This test does not require any input parameters.

The test reports whether it was able to establish a JMS connection to the WF_CONTROL queue and dequeue a message from the queue.

If the required JMS libraries are not included in the appsborg2.zip file referenced in your AF_CLASSPATH, perform the following steps:
- Verify that JDK (Java Development Kit) 1.3 is installed on the concurrent processing node, patch 2356331 has been applied, and you have performed all post-installation steps described in OracleMetaLink note 130091.1, "Upgrading to JDK 1.3 with Oracle Applications 11i". Ensure that the environment variables AF_JRE_TOP, AF_CLASSPATH, and AFJVAPRG are set correctly in adovars.env. The AF_CLASSPATH must include the appsborg2.zip file.
  
  For example, on Unix:
```
AF_CLASSPATH=[JDK13_TOP]/lib/dt.jar:[JDK13_TOP]/lib/tools.jar:
[JDK13_TOP]/jre/lib/rt.jar:[JDK13_TOP]/jre/lib/i18n.jar:
$JAVA_TOP/appsborg2.zip:$JAVA_TOP/apps.zip:
$ORACLE_HOME/forms60/java:$JAVA_TOP
```
  where [JDK13_TOP] is the full path to the JDK 1.3 installation top directory on Unix.
  
  On Windows:
```
AF_CLASSPATH=[JDK13_TOP]\lib\dt.jar;[JDK13_TOP]\lib\tools.jar;
[JDK13_TOP]\jre\lib\rt.jar;[JDK13_TOP]\jre\lib\i18n.jar;
[JAVA_TOP]\appsborg2.zip;[JAVA_TOP]\apps.zip;
[8.0.6 ORACLE_HOME]\forms60\java;[JAVA_TOP]
```
  where [JDK13_TOP] is the full path to the JDK 1.3 installation top directory, [JAVA_TOP] is the full path to %JAVA_TOP%, and [8.0.6 ORACLE_HOME] is the full path to %ORACLE_HOME%.
- Verify that the appsborg2.zip file contains the required JMS classes. Execute the following command:
```
unzip -l $JAVA_TOP/appsborg2.zip | grep -i jms | wc -l
```
  This command should return the count 128 if the required JMS classes are present. If it returns 0 (zero), then you need to add the required classes into appsborg2.zip. First verify that the $APPL_TOP/admin/adjborg2.txt file contains entries for the required classes, jmscommon.jar and aqapi.jar. Execute the following command:
```
grep jar $APPL_TOP/admin/adjborg2.txt
```
  Ensure that the output includes entries for jmscommon.jar and aqapi.jar. For example:
```
/d01/vis1159/oracle/visora/iAS/rdbms/jlib/aqapi.jar
/d01/vis1159/oracle/visora/iAS/rdbms/jlib/jmscommon.jar
```
  Then use the AD Administration utility (adadmin) to regenerate product JAR files. Within adadmin, choose the Generate Applications Files menu option and choose the Generate product jar files task. At the prompt that asks whether you want to force generation of all JAR files, enter Yes. See: File System Tasks, Oracle Applications AD Utilities Reference Guide.
If dead subscribers are not being regularly removed from the WF_CONTROL queue, ensure that a recurring concurrent request is scheduled in your Oracle Applications instance for a concurrent program named Workflow Control Queue Cleanup (FNDWFBES_CONTROL_QUEUE_CLEANUP). If you do not have this request scheduled, perform the following steps:
- Terminate the service instances for Oracle Workflow in Oracle Applications Manager. Navigate to the Service Components page in Oracle Workflow Manager, and choose a service instance link in the Container column. In the Service Instances for Generic Service Component Container page, terminate each service instance. For more information, see the Oracle Applications Manager online help.
- Submit a concurrent request for the Workflow Control Queue Cleanup program (FNDWFBES_CONTROL_QUEUE_CLEANUP) for immediate execution. See: Cleaning Up the Workflow Control Queue.
- Submit another request for the Workflow Control Queue Cleanup program to run periodically, so that the WF_CONTROL queue will be cleaned of dead subscribers regularly. The recommended interval for performing cleanup is every six to twelve hours. See: Cleaning Up the Workflow Control Queue.
- After the first concurrent request has completed, restart the service instances for Oracle Workflow. Navigate back to the Service Instances for Generic Service Component Container page in Oracle Applications Manager and restart each service instance. For more information, see the Oracle Applications Manager online help.
  
  Note: You should not restart the service instances until the initial cleanup performed by the first Workflow Control Queue Cleanup request is finished.
If the test could not successfully remove a dead subscriber from the WF_CONTROL queue, the queue may need to be dropped and recreated. Contact Oracle Support for instructions.
If your database version is Oracle9i Release 2 and the SYS.DBMS_AQIN package is missing the required third signature for the AQ$_DEQUEUE_IN procedure, download and apply patch 2805491, available from OracleMetaLink.
If the SYS.DBMS_AQIN package is invalid, Oracle Streams Advanced Queuing may not be properly installed in the database. Contact Oracle Support for instructions.

For more information, see the "About Oracle Workflow" document for your Oracle Workflow mini-pack on OracleMetaLink.

Workflow Advanced Queue Rule Validation Test

This test checks the standard WF_ERROR and WF_DEFERRED queues to verify that only one subscriber rule is defined for each queue. These queues are reserved for internal Oracle Workflow processing. You should not add any custom subscribers to these queues. This test does not require any input parameters. See: Standard Agents, Oracle Workflow Developer's Guide.

If either queue has more than one subscriber rule defined, the test reports the queue name and the invalid rules. Remove any custom subscribers that have been added to the queues. See: Managing Subscribers, Oracle Streams Advanced Queuing User's Guide and Reference.

Workflow Agents/AQ Status Test

This test checks the Business Event System agents for Oracle Workflow and Oracle XML Gateway, as well as the queues associated with these agents. The test verifies that the agents are enabled within the Business Event System. It also verifies that the queues and the queue tables in which they reside are valid database objects, and that the queues are enabled for enqueuing and dequeuing within Oracle Streams Advanced Queuing (AQ). This test does not require any input parameters. See: Oracle Streams AQ Administrative Interface, Oracle Streams Advanced Queuing User's Guide and Reference.

The test reports the status of the agents, queues, and queue tables, and also shows the subscribers and subscriber rules defined for the queues.

If an agent is disabled, you can edit the agent definition in the Event Manager Web pages to set its status to Enabled. See: To Create or Update an Agent, Oracle Workflow Developer's Guide.
If a queue is not enabled for enqueuing or dequeuing, you can stop the queue and restart it with these operations enabled, using the DBMS_AQADM.Stop_Queue and DBMS_AQADM.Start_Queue APIs. See: Managing Queues, Oracle Streams Advanced Queuing User's Guide and Reference.
If any queues or queue tables are invalid, contact Oracle Support for instructions.

Workflow Objects Validity Test

This test checks the Oracle Workflow and Oracle XML Gateway database objects to verify that all the objects are valid. This test does not require any input parameters.

If any invalid objects are found, the test reports the name and type of those objects. Recompile those objects and ensure that they are valid.

XML Parser Installation Test

This test checks your Oracle Applications installation to verify that the Oracle XML parser is installed and valid. This test does not require any input parameters.

The test reports the version of the XML parser you have installed and shows the status of the XMLDOM PL/SQL package or xmlparser Java source object in each schema. If any XML parser object is invalid, reinstall the XML parser for that schema. To install the XML parser version 2.0.2.9, download and apply patch 2199206, available from OracleMetaLink. For more information, see the "About Oracle Workflow" document for your Oracle Workflow mini-pack on OracleMetaLink.

Mailer Component Test

This test checks your notification mailer service components to verify that at least one notification mailer has been configured with all the parameters needed to run it. This test does not require any input parameters.

If your installation does not include any notification mailer components with a completed configuration, the test reports that no notification mailer is configured. Navigate to the Service Components page in Oracle Workflow Manager to configure a notification mailer service component. You can either complete the configuration of the seeded Workflow Notification Mailer component, or create a new custom notification mailer component. See: Implementing Notification Mailers and the Oracle Workflow Manager online help.

Note: This test does not report whether a configured notification mailer is currently running. You can use the Service Components page in Oracle Workflow Manager to check the current status of your notification mailer service components.

Mailer Component Parameter Test

This test checks your notification mailer service components to validate their configuration parameters. The test checks only those notification mailers for which all the mandatory configuration parameters have been defined. This test does not require any input parameters.

If any notification mailer has invalid configuration parameters, the test reports the errors. Navigate to the Service Components page in Oracle Workflow Manager to edit the configuration of a notification mailer. For some parameters, you may also need to check the corresponding setup outside the notification mailer.

Ensure that your SMTP server is accessible and able to accept connections, and that the reply-to e-mail address defined for the notification mailer has a valid account on the SMTP server.
Ensure that your IMAP server is accessible and able to accept connections, that the inbound username defined for the notification mailer has a valid account on the IMAP server, and that you can connect to the IMAP server from an e-mail client using the inbound username and password.
Ensure that the inbox, processed folder, and discard folder defined for the notification mailer exist within the inbound e-mail account, and that these are three separate folders.
Ensure that the HTML agent defined for the notification mailer is accessible and that the Web listener is processing requests.
Ensure that all messages defined as message templates for the notification mailer are loaded in your database, together with the item types to which the messages belong.

See: Implementing Notification Mailers and the Oracle Workflow Manager online help.

Event Diagnostic Test

This test reports details about the Business Event System, including the statuses of the local system and agent listeners, details about the definitions of the specified event and any subscriptions to that event, and details about the specified instance of the event if it appears on one of these queues:

WF_DEFERRED
WF_JAVA_DEFERRED
WF_ERROR
WF_JAVA_ERROR

You can use this information to check the status of a particular event or to investigate errors. Use the Advanced tab within Oracle Diagnostics to enter the event name and event key for the event that you want to review and run the test. The Event Name and Event Key fields are case-sensitive. See: Setting Up the Business Event System.

Note: You can also obtain this information through SQL*Plus using the wfbesdbg.sql script. See: Wfbesdbg.sql.

Mailer Tests

The following test is available in the Mailer Tests group.

Mailer Diagnostic Test

This test reports details about a notification and about the notification mailer that sent the notification. You can use this information to check the status of a particular notification or to investigate errors. Use the Advanced tab within Oracle Diagnostics to enter the notification ID (NID) of the notification that you want to review and run the test. See: Implementing Notification Mailers.

Note: You can also obtain this information through SQL*Plus using the wfmlrdbg.sql script. See: Wfmlrdbg.sql.