6 Troubleshooting the Connector

This chapter provides information to assist you in troubleshooting integration issues with the CA Service Desk Connector. The connector will not work unless the appropriate components have been installed and configured. Before you start the troubleshooting steps, you must insure that you have done the following:

Install and test the CASD Adapter as specified in Installing the Adapter.
Install the CA Service Desk Connector as specified in Installing the Connector.
Configure the CA Service Desk Connector as specified in Configuring the Connector.
Set up one or more notification rules as specified step 4 of Automatically Creating a Ticket.

If all the actions above have been completed and the connector is not working, perform the following steps to diagnose the problem.

Verify that the CASD Adapter has been successfully started and the WSDL for the CASD Adapter can be accessed from the machine where the CASD Adapter is installed. Performing the following steps to do this:
1. Refer to "Using the Correct URL for CASD Adapter Operations" in Appendix A to see the first five steps to use to complete this procedure.
  
  Note:
  If the adapter does not successfully complete the startup, see Troubleshooting Adapter Startup Errors to diagnose the problem.
2. Open a browser and paste the URL from the framework.log file in the address window. Append ?WSDL to the end of the URL and attempt to load the URL.
3. The WSDL should be loaded if the Adapter is operational.
  
  Note:
  A WSDL is an XML file that describes the web service.
Verify that the WSDL for the CASD Adapter can be accessed from the machine where the Enterprise Manager server is installed.
1. Open a browser at the Enterprise Manager server and copy the URL from step 1-b above to the address window. The hostname for the URL will be localhost. Change localhost to the actual hostname or IP address of the machine where the CASD Adapter is installed. If you specify a hostname, you must make sure that the hostname is recognized at the Enterprise Manager server machine. This can be done using the ping command.
  
  For example, if the CASD Adapter is installed on the server with a hostname of SDServer01 and the URL listed in framework.log is:
  
  http://localhost:8082/services/causd/IncidentService
  
  The URL used at the Enterprise Manager server machine would be:
  
  http://SDServer01:8082/services/causd/IncidentService
2. Attempt to load the WSDL by appending ?WSDL at the end of the URL. If the WSDL cannot be loaded, either the hostname is not recognized at the Enterprise Manager machine or there is a connectivity issue between the two machines. If you specified a hostname, try using the IP address instead of the hostname in the URL. If it still will not load, you have a connectivity problem. You will need to consult with your IT department to resolve this issue.
Verify that the CA Service Desk Connector specifies the correct URL for the createTicket, getTicket, and updateTicket operations. Determine the URL being used by the CASD Adapter as specified in "Using the Correct URL for CASD Adapter Operations" in Appendix A.
1. Log into the Oracle Enterprise Manager console by entering a user name with a Super Administrator role, entering the appropriate password, then clicking Login.
2. Click the Setup link at the top right part of the window. The Overview of Setup page appears.
3. Click the Management Connectors link on the left side of the window. The Management Connectors page appears, which shows the installed connectors.
4. Click on the Configure icon associated with the CA Service Desk Connector. This invokes edit mode, enabling you to configure the connector.
5. Verify that the URL identified in step 2-b is specified for all three operations (createTicket, getTicket, and updateTicket). If any of the operations are incorrect, change to the correct URL.
  
  Note:
  Do not append the WSDL to the end of the URL that is specified here.
6. Enter a valid ticket number in the Ticket Number field and click OK.
7. You will see the message Connection test succeeded if everything is set up correctly.
If there is an error in step 3-g, there is likely a configuration error in the CASD Adapter. See the section entitled Troubleshooting Adapter Operations Errors for information on diagnosing errors.

Troubleshooting Adapter Startup Errors

To identify the cause of a startup failure, navigate to the adapters/log directory in the CASD Adapter install directory and open the framework.log file in a text editor. Search for Exception to find any errors in the file. If the file does not exist, it indicates that there is a problem locating or executing the JVM. See JVM Errors for information about resolving JVM issues.

Listed below are some possible Exceptions, an explanation of the root cause, and a description of the solution.

java.net.BindException: Address already in use: bind

This error indicates that the adapter could not start because of a port conflict. There are two possible causes for this error.

Another application is using a port that the Adapter is configured to use. If the adapter is configured to use SSL, the port number is 8443. If it is not configured to use SSL, the port number is 8082.

There are two possible solutions to this. You can change the other application to use a different port or you can change the CASD Adapter to use a different port. To change the Adapter to use a different port, see "Changing the Default Adapter Port" in Appendix A.
There is an instance of the Adapter already running. If this is the case then there is no change required. You should only run one instance of the Adapter at a time.

org.springframework.beans.factory.BeanInitializationException: Could not load properties; nested exception is java.io.FileNotFoundException: … framework.properties (Permission denied)

This error indicates that the adapter could not start because the permissions on the framework.properties file in the conf directory were not set correctly.

To solve the problem, change the permissions to give the account or group under which the CASD Adapter runs read and execute permissions.

For any other startup errors, consult with Oracle Support.

JVM Errors

The CASD Adapter requires version 1.6 of the JVM. If there are multiple versions of the JVM installed on the machine, it is possible that an older version of the JVM is being executed whenever the adapter starts.

On UNIX systems, the JAVA_HOME environment variable must be set to the directory where Java 1.6 is installed in the shell where the adapter is started. To properly start the adapter on a UNIX platform, perform the following:

Set the JAVA_HOME environment variable to the Java 1.6 install directory.
Navigate to the adapters/bin subdirectory in the Adapter install directory.
Execute the ./service.sh start command.

On Windows systems, perform the following to insure that Java 1.6 is used when starting the adapter.

Navigate to the adapters/bin subdirectory in the Adapter install directory.
Run the iWaveAdaptersw.exe executable.
Click on the Java tab.
Make sure that the Use Default check box is not checked.
In the Java Virtual Machine box, specify the path to the jvm.dll file in the Java 1.6 install directory.
Click on the OK button.

Troubleshooting Adapter Operations Errors

In order to troubleshoot integration issues, you must modify the Oracle Enterprise Manager logging options to capture additional debug information. Perform the steps specified in the section entitled "Enabling Debug in Enterprise Manager" in Appendix A to enable debugging.

Perform the following diagnostic steps if tickets are not being generated or updated as expected in CA Service Desk.

Verify that the metric/job that was triggered is referenced in a notification rule that specifies one of the CA Service Desk Ticketing Templates.
Determine the error that Oracle Enterprise Manager has reported.
1. To do this you need to examine the log file for errors. Perform the following steps to locate errors in the log file:
  
  1.) Open the emoms.trc file in a text editor. The file is located in this directory:
  
  <ORACLE_HOME>/oms10g/sysman/log
  
  2.) Go to the bottom of the file and search backwards for the appropriate string based on the operation that failed:
```
If the getTicket operation failed, search for "ERROR
ticketTicketConnectorConfigData".
If the createTicket or updateTicket operation failed, search for "ERROR
svc.TTCServiceImpl".
```
  The error information is contained on the same line where the search string is found or on the next line.
Diagnose the problem based on the error event. See Errors to Check for information on troubleshooting common error events.

Errors to Check

This section provides cause and solution information on troubleshooting common errors reported by Enterprise Manager. Find the heading that matches your error and follow the instructions for diagnosing and correcting the problem.

javax.net.ssl.SSLException: SSL handshake failed: X509CertChainInvalidErr

Cause : The SSL handshake between the Oracle Enterprise Manager Connector Framework and the CASD Adapter failed. This failure occurs because Oracle Enterprise Manager is not configured correctly with the SSL certificate for the CASD Adapter. The SSL certificate the CASD Adapter uses must be imported into the wallet manager. The certificate is either missing from the wallet or does not match the SSL certificate provided by the CASD Adapter.

Solution : Import the SSL certificate from the CASD Adapter into the wallet manager. See Adding Signed Certificates to Wallet Manager for details on setting up Oracle Enterprise Manager with the CASD Adapter SSL certificate.

The wallet "/gc/OracleHomes/oms10g/sysman/connector//certdb.txt" does not exist

Cause : The CASD Adapter is configured to use SSL, but the certdb.txt file that contains the SSL information is missing.

Error opening socket: java.net.ConnectException: Connection refused

Cause : The CASD Adapter is down.

Solution : Perform the following steps to check the status of the adapter and start it if necessary.

If the CASD Adapter is installed on a Unix system:

Open a command terminal on the system where the CASD Adapter is installed.
Change the working directory to the adapters/bin directory in the CASD Adapter installation directory.
Enter the following command:

./service.sh status
If the command indicates that the service is not running, enter the following command:

./service.sh start

If the CASD Adapter is installed on a Windows system:

Open a command terminal on the system where the CASD Adapter is installed.
Change the working directory to the adapters/log directory in the CASD Adapter installation directory.
Open the framework.log file in a text editor.
Go to the bottom of the file and search backwards for the string iWave Adapter Framework. If the last occurrence found is iWave Adapter Framework Started, this indicates that the web service is started.
If the web service is not started, start the web service based on how the web service is installed.
- If it is installed as a standalone application, change the working directory to the adapters/bin directory and run the startAdapters.bat command file.
- If it is installed as a Windows service, enter the net start iWaveAdapters command.

Error opening socket: java.net.UnknownHostException:

Cause : The system does not recognize the host name specified in the URL.

Solution : You can use the following options to address this issue:

Coordinate with the system administrator to change the system configuration to recognize the host name.
Specify the IP address in the URL instead of the host name. To do this, perform the following steps:
1. Determine the IP address of the system where the CASD Adapter is installed.
2. Log in to the Oracle Enterprise Manager console by entering a user name with a Super Administrator role, entering the appropriate password, then clicking Login.
3. Click the Setup link at the top right part of the window. The Overview of Setup page appears.
4. Click the Management Connectors link on the left side of the window. The Management Connectors page appears, which shows the installed connectors.
5. Click on the Configure icon associated with the MICROSOFT CA Service Desk Connector. This invokes edit mode, enabling you to configure the connector.
6. Change the host name to the IP address in the URL specified for the createEvent and updateEvent operations.
7. Click OK.

Error opening socket: java.net.NoRouteToHostException: No route to host

Cause : The IP address or port number specified in the URL is invalid, or the network is down.

Solution : Verify that the hostname/IP address configured for the connector is correct:

Log in to the Oracle Enterprise Manager console by entering a user name with a Super Administrator role, entering the appropriate password, then click Login.
Click the Setup link at the top right part of the window. The Overview of Setup page appears.
Click the Management Connectors link on the left side of the window. The Management Connectors page appears, which shows the installed connectors.
Click on the Configure icon associated with the CA Service Desk Connector. This invokes edit mode, enabling you to configure the connector.
Verify that the hostname/IP address and port number specified in the URL for the createEvent and updateEvent operations are correct.
If the hostname/IP address and port number are incorrect, provide the correct values and click OK.

If the URLs specify a host name, be sure that the host name resolves to the correct IP address. To determine the IP address of the host name, issue the ping <hostname> command, where <hostname> is the actual host name. This lists the IP address that was resolved for the host name. If this is incorrect, the system administrator needs to investigate why it is incorrect.

If the ping fails, the system administrator needs to investigate why there is no connectivity.

SOAPException: faultCode=SOAP-ENV:Protocol; msg=Unsupported response content type "text/html;

Cause : The web service received the request and rejected it because there was a problem. This likely indicates that an invalid path was specified in the URL.

Solution : To determine the reason for the failure, examine the HTML document listed with the Exception information in the emoms.trc log file. In the HTML document, it provides error information that indicates the reason why it was rejected. The error information may be difficult to spot because the HTML tag delimiters are encoded.

If the error information specifies HTTP Error: 404, this indicates that the path in the URL is incorrect. Perform the following steps to test the URL the connector is using.

Log in to the Oracle Enterprise Manager console by entering a user name with a Super Administrator role, entering the appropriate password, then clicking Login.
Click the Setup link at the top right part of the window. The Overview of Setup page appears.
Click the Management Connectors link on the left side of the window. The Management Connectors page appears, which shows the installed connectors.
Click on the Configure icon associated with the CA Service Desk Connector.
Click the General tab.
Select and copy the URL specified for the createEvent operation.
Open an internet browser on the system where the Oracle Enterprise Manager server is installed.
In the address window, enter the URL that was copied in step 6 above. Add ?wsdl to the end of the URL. The URL should appear similar to the following example:

http://[Hostname]:8082/services/causd/IncidentService?wsdl

[Hostname] is the actual host name or IP address where the CASD Adapter is installed.

If the WSDL is loaded, this confirms that the URL is correct. If it fails to load, there is a problem with the URL. Perform the steps specified in the section entitled "Using the Correct URL for CASD Adapter Operations" in Appendix A to configure the connector to use the correct URL.

Error occurred while calling Web Service: - or - java.lang.Exception: Error occurred while calling Web Service:

The CASD Adapter returned a SOAP fault. To determine root cause of the SOAP fault, you must examine the contents of the soapfault element following the error message. Listed below are some of the possible errors listed in the soapfault element. Find the error listed below contained in your soapfault message for a description of possible causes/solutions.

javax.xml.ws.soap.SOAPFaultException: Could not send Message.

Cause : The CASD Adapter could not connect to the CA Service Desk Server for one of the following reasons:

The hostname/IP address specified for the CA Service Desk Server is incorrect
The port number specified for the CA Service Desk Server is incorrect
The CA Service Desk Server is down

Solution : Perform the following steps to determine and correct the root cause of the problem:

Verify that the CA Service Desk Server is up. If it is not up, start the server.
Verify that hostname/IP address and the port number configured for the CA Service Desk Server are correct. Perform the following steps to determine the hostname/IP address and port number configured for the CA Service Desk Server:

Navigate to the adapters/conf directory in the CASD Adapter install directory.
Make a backup copy of the framework.properties file.
Open the framework.properties file in a text editor.
Search for the causd.webservice.endpoint.r11 property. This is the URL that is used to connect to the CA Service Desk Server.
The hostname/IP address and port number should be specified in the URL.
Verify that the information is correct. If it is not correct, change the incorrect information and save the file.
If the framework.properties file was modified, the CASD Adapter must be restarted to pick up the configuration change.

Error - invalid login name

Cause : The web service could not access the CA Service Desk Server because the user name specified for the CAUSD account is incorrect.

Solution : Perform the following steps to change the user name for accessing the CA Service Desk Server.

Navigate to the adapters/conf directory in the CASD Adapter install directory.
Make a backup copy of the framework.properties file.
Enter the following command to change the user name where <username> is the new user name to specify:

..\bin\propertiesEditor.bat -e causd.username=<username> framework.properties

The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for Unix platforms is propertiesEditor.sh.
Restart the CASD Adapter.

Error - invalid login password

Cause : The web service could not access the CA Service Desk Server because the password specified for the CAUSD account is incorrect.

Solution : Perform the following steps to change the password for accessing the CA Service Desk Server.

Navigate to the adapters/conf directory in the CASD Adapter install directory.
Make a backup copy of the framework.properties file.
Enter the following commands to change the user name and password information where <username> is the new user name to specify:

..\bin\propertiesEditor.bat -e causd.username=<username> framework.properties

The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for Unix platforms is propertiesEditor.sh.
Enter the following command to change the password where <password> is the new password to specify:

..\bin\propertiesEditor.bat -e causd.password=<password> framework.properties
Restart the CASD Adapter.

Error - Login service failed

Cause : The web service could not access the CA Service Desk Server because the account specified does not have sufficient permissions.

Solution : There are 2 options to correct this problem. One option is to change the account permissions in CA Service Desk to allow the account to create/update incidents. The other option is to specify a different account that has the appropriate permissions. Perform the following steps to change the account for accessing the CA Service Desk Server.

Navigate to the adapters/conf directory in the CASD Adapter install directory.
Make a backup copy of the framework.properties file.
Enter the following command to change the password where <username> is the new user name to specify:

..\bin\propertiesEditor.bat -e causd.username=<username> framework.properties

The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for Unix platforms is propertiesEditor.sh.
Restart the CASD Adapter.