7 Diagnostics and Troubleshooting the CA Top Secret Connector

Describes diagnostics and troubleshooting information for the connector that can assist in resolving issues.

Understanding and Using the ENVINFO Diagnostic Tool

Learn about the ENVINFO diagnostics tool and how to use it.

About the ENVINFO Diagnostics Tool

Whenever you need to report any issues related to the mainframe agents, Oracle recommends that you run the ENVINFO diagnostics tool. This tool fetches multiple setup and configuration values in your LPARs, which might be required to resolve the issue.

The ENVINFO tool is located in the default CLISTLIB (located inside HLQ.CLISTLIB) that is installed with the mainframe agents.

When you run the ENVINFO tool, it writes several system configuration information to the HLQ.ENVINFO.OUTPUT file that is created during installation of the mainframe agents. The following is some of the information that the ENVINFO tool is capable of fetching from the mainframe system and storing in the HLQ.ENVINFO.OUTPUT file:

System variables
Storage variables
CVT tables
CPU info
Codepage and character-set information
Agent starter task definitions
Agent version information fetched either from running starter task in spool or bind information in load module

Using the ENVINFO Tool

To use the ENVINFO tool:

Ensure that the DSN <++ HLQ ++>.ENVINFO.OUTPUT file is present and has been created by the CREATDSN job that is shipped along with the connector.
Go to the CLISTLIB (for example – IDF.CLISTLIB) that is created while installing the mainframe agents.
Look for the member ENVINFO.
Execute the ENVINFO rexx by issuing an EX against the member as shown in the following screenshot:

Description of the illustration run_envinfo.png
Check the <++ HLQ ++>. ENVINFO.OUTPUT dataset for output.

Best Practices

If the rexx output reads that the Pioneer or Voyager job was not found, then the jobs need to be submitted and they should be up and running before attempting to execute this rexx again. In addition, this rexx relies on the fact that you are utilizing the agents from the libraries that were setup as described in this guide. If the starter tasks have been moved to a different location than the default ones, then the output of this rexx will be impacted and the starter task definition information may not be displayed.

Troubleshooting Information

You may encounter some problems with CA Top Secret configuration and these are some helpful tips to assist in resolving these problems.

The following table describes solutions to problems that you might encounter while using the connector.

Table 7-1 Troubleshooting Tips

Problem Description	Solution
Oracle Identity Manager cannot establish a connection with the target system.	Ensure that the mainframe is running. Verify that the required ports are working. Due to the nature of the Provisioning Agent, the LDAP Gateway must be started first, and then the mainframe JCL started task must be started. This is a requirement based on how TCP/IP operates. Check that the IP address of the server that hosts the LDAP Gateway is configured in the Reconciliation Agent JCL. Read the LDAP Gateway logs to determine if messages are being sent and received. Examine the Oracle Identity Manager configuration to verify that the IP address, admin ID, and admin password are correct. Check with the mainframe platform manager to verify that the mainframe user account and password have not been changed.
The mainframe does not appear to respond.	Check the connection information that you have provided in the IT resource and the acf2Connection.properties file. Check the logs. If any of the mainframe JCL jobs have reached an abnormal end, then make the required corrections and rerun the jobs.
A particular use case does not work as expected.	Check for the use case event in the LDAP Gateway logs. Then check for the event in the specific log assigned to the connector: If the event has not been recorded in either of these logs, then investigate the connection between Oracle Identity Manager and the LDAP Gateway. If the event is in the log but the command has not had the intended change on a mainframe user profile, then check for configuration and connections between the LDAP Gateway and the mainframe. Verify that the message transport layer is working.
The LDAP Gateway fails and stops working	If this problem occurs, then the Reconciliation Agent stops sending messages to the LDAP Gateway. Instead, it stores them in the subpool cache. When this happens, restart the LDAP Gateway instance so that the Reconciliation Agent reads the subpool cache and resends the messages.
The LDAP Gateway is running. However, the Reconciliation Agent fails and stops working	If this problem occurs, then all events are sent to the subpool cache. If the mainframe fails, then all messages are written to the disk. When this happens, restart the Reconciliation Agent instance so that it reads messages from the disk or subpool cache and resends the messages.
Top Secret reconciles users to Internal LDAP scheduled job (CFILE job) shows "Job Failure" as error message while it is still running. This is usually expected to happen while using Oracle Identity Governance 12c (12.2.1.4.0) only.	This job is failing due to an authentication error. In such a case, set the value of the `ServiceAccount.API.EncryptedParamsValue` and `ServiceAccount.ParamsValue.DBStore` system properties in Oracle Identity Governance to `True`.