2 Installing and Uninstalling the Connector

The CA Service Desk (CASD) ticketing connector is comprised of two components. The first component is the CASD adapter. The CASD adapter provides a web service interface for manipulating incidents in CA Service Desk. The casd_adapter.jar file contains the installation files for the CASD adapter. The second component is the CASD connector. The casd_connector.jar file contains the CASD connector and is deployed via the Enterprise Manager emctl command.

You can download the connector bundle jar file and extract it by using the following command:

jar -xvf casd_connector_bundle.jar

You will see the two components mentioned above, casd_connector.jar and casd_adapter.jar.

This chapter provides the following information for installing or uninstalling the CASD Connector, as well as switching from one console to the other:

Prerequisites
Installing the Adapter
Installing the Connector
Uninstalling the Connector
Uninstalling the Adapter
Navigating Between CASD and Enterprise Manager
Adding Signed Certificates to Wallet Manager

Prerequisites

As a prerequisite before using CA Service Desk Connector, ensure that CA Service Desk 11 or 12 is installed and configured. As a prerequisite to installing the CASD Adapter, Java JRE 6.0 update 15 or higher must be installed on the system where the CASD Adapter will be installed.

There can be only one ticketing connector in Oracle Enterprise Manager. Before proceeding to the next section, follow these steps to remove any existing ticketing connector:

Click the Setup link in the upper right corner of the Oracle Enterprise Manager console.
Click the Management Connectors link in the left column of the Overview of Setup page.
Remove any ticketing connector you may have.

Installing the Adapter

The CASD Adapter acts as a front-end for all incidents flowing into and out of CASD. Oracle Enterprise Manager posts calls to the web service whenever it needs to create or update an incident, or get an incident from CASD.

You can install the CASD Adapter on any Unix or Windows system that has connectivity to the CASD server and the Oracle Enterprise Manager server.

Security Recommendations

Because the CASD Adapter stores sensitive information for accessing CA Service Desk, access to the adapter files should be limited. Oracle recommends setting up a separate group (hereafter referred to as "the adapter group") that has permission to configure and run the CASD Adapter. Access to the adapter should not be allowed for anyone that is not a member of the adapter group.

Installing and Running the CASD Adapter on Unix

The following sections explain how to install and then subsequently run the Adapter.

Installing the Adapter on Unix

To install the adapter on a Unix platform, perform the following steps:

Log in as a user that is a member of the adapter group. See the Security Recommendations sections for more information regarding the adapter group.
Create a directory where you want to install the adapter.
Open a terminal and change the working directory to the installation directory.
Download the casd_adapter.jar file from the Oracle Technology Network (OTN) to the installation directory.
Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.
Enter the following command to unzip and extract the jar file:

$JAVA_HOME/bin/jar xvf casd_adapter.jar

This creates the adapters directory that contains the installation files.

Note:
If the system where the CASD adapter is being installed does not have the JDK installed, you cannot extract the jar file contents. You must copy the jar file to a system that has the JDK installed and transfer the files after they have been extracted.
Enter the following command to change the working directory:

cd adapters/endpoints/ca-usd
Enter the following command to run the installation script:

sh ./install.sh
When the script prompts whether you want to use HTTPS, answer Y (yes) or N (no):
- If you specify Y, the adapter is set up to use HTTPS port number 8443.
- If you specify N, the adapter is set up to use HTTP port number 8082.
When the script prompts for the user name of the web service, enter the user name that must be provided to access the CASD adapter web service.

Note:
This user name is not associated with any CASD or system account. It can be any value that you choose. This user name will be used to restrict access to the adapter web service interface.
When the script prompts for the password of the web service, enter the password that must be provided to access the CASD adapter web service.

Note:
This password is not associated with any CASD or system account. It can be any value that you choose. This password will be used to restrict access to the adapter web service interface.
When the script prompts for the hostname/IP address of the CASD server, enter the hostname or IP address of the machine where the CASD server is deployed. The hostname will default to localhost if no value is provided.
When the script prompts for the port number of the CASD server, enter the port number used by the CASD web server (Tomcat or IIS). The port number will default to 8080 if no value is provided.
When the script prompts for the user name to use when accessing CASD, enter the user name of the CASD account that the adapter should use when accessing CASD.

Note:
The account must have permission to create, update, and retrieve incident information.
When the script prompts for the password to use when accessing CASD, enter the password of the CASD account that the adapter should use when accessing CASD.

Note:
The account must have permission to create, update, and retrieve incident information.
After the script displays the message CASD Adapter Install Complete, press Enter to complete the installation.
Enter the following command to change the working directory to the conf directory.

cd ../../conf
Change the permissions on the framework.properties file to allow read, write, and execute permissions for the owner and the adapter group and no access for any other users.
If the adapter was configured to run using the HTTPS protocol, you must install a SSL certificate. You can install a self-signed certificate, or you can acquire a certificate from a Certificate Authority (CA).
- To generate and install a self-signed SSL certificate, enter the following commands and replace <hostname> with the system host name or the IP address that the CASD adapter will use:
```
$JAVA_HOME/bin/keytool -delete -alias iwave -keypass iwavepw -storepass iwavepw -keystore keystore.jks
$JAVA_HOME/bin/keytool -genkey -alias iwave -keyalg RSA -keysize 1024 -dname "CN=<hostname>, OU=Development, O=iWave Software, L=Frisco, ST=TX, C=US" -keypass iwavepw -storepass iwavepw -keystore keystore.jks
```
- To install a certificate that the Certificate Authority issues:
  - Request a certificate from a Certificate Authority, such as VeriSign.
    
    In the certificate request, make sure to specify the host name or IP address that the CASD adapter will use. The host name in the certificate must match the host name configured for the adapter. If they do not match, the adapter cannot function.
  - After you obtain the certificate from the Certificate Authority, enter the following command to install the certificate, where <certificateFile> is the full path name of the file provided by the Certificate Authority:
```
$JAVA_HOME/bin/keytool -export -alias iwave -file <certificateFile> -keypass iwavepw -storepass iwavepw -keystore keystore.jks
```

The adapter framework is now installed and ready to start.

To add signed certificates to Wallet Manager, see Adding Signed Certificates to Wallet Manager.

Running the Adapter on Unix

To run the CASD Adapter framework commands listed with the following tasks, first change the working directory in the installation directory to:

adapters/bin

Run the following four commands:

Start - ./service.sh start
Shut Down - ./service.sh stop
Restart - ./service.sh restart
Check Status - ./service.sh status

Testing the Adapter on Unix

Perform the following steps to verify that the CASD Adapter is functional.

Open a terminal and change the working directory to the adapters/bin directory in the installation directory.
Enter the following command to run the test script:

./testAdapter.sh
The test script will prompt for the password information. At the prompt, enter the password that was configured for accessing the Adapter web service in step 11 of Section 2.2.2.1, "Installing the Adapter on Unix".
If the test completes successfully, the last line the utility displays is Test completed successfully.

Installing and Running the CASD Adapter on Windows

The following sections explain how to install and then subsequently run the Adapter.

Installing the Adapter on Windows

To install the adapter on a Windows platform, perform the following steps:

Log in as a user that is a member of the adapter group. See the Security Recommendations sections for more information regarding the adapter group.
Create a directory where you want to install the adapter.
Open a terminal and change the working directory to the installation directory.
Download the casd_adapter.jar file from the Oracle Technology Network (OTN) to the installation directory.
Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.
Enter the following command to unzip and extract the jar file:

"%JAVA_HOME%\bin\jar" xvf casd_adapter.jar

This creates the adapters directory that contains the installation files.

Note:
If the system where the CASD adapter is being installed does not have the JDK installed, you cannot extract the jar file contents. You must copy the jar file to a system that has the JDK installed and transfer the files after they have been extracted.
Enter the following command to change the working directory:

cd adapters\endpoints\ca-usd
Enter the following command to run the installation script:

.\install.bat
When the script prompts whether you want to use HTTPS, choose Y (yes) or N (no):
- If you specify Y, the adapter is set up to use HTTPS port number 8443.
- If you specify N, the adapter is set up to use HTTP port number 8082.
When the script prompts for the user name of the web service, enter the user name that must be provided to access the CASD adapter web service.

Note:
This user name is not associated with any CASD or system account. It can be any value that you choose. This user name will be used to restrict access to the adapter web service interface.
When the script prompts for the password of the web service, enter the password that must be provided to access the CASD adapter web service.

Note:
This password is not associated with any CASD or system account. It can be any value that you choose. This password will be used to restrict access to the adapter web service interface.
When the script prompts for the hostname/IP address of the CASD server, enter the hostname or IP address of the machine where the CASD server is deployed. The hostname will default to localhost if no value is provided.
When the script prompts for the port number of the CASD server, enter the port number used by the CASD web server (Tomcat or IIS). The port number will default to 8080 if no value is provided.
When the script prompts for the user name to use when accessing CASD, enter the user name of the CASD account that the adapter should use when accessing CASD.

Note:
The account must have permission to create, update, and retrieve incident information.
When the script prompts for the password to use when accessing CASD, enter the password of the CASD account that the adapter should use when accessing CASD.

Note:
The account must have permission to create, update, and retrieve incident information.
Enter the following command to change the working directory to the conf directory.

cd ..\..\conf
Change the permissions on the framework.properties file to allow read, write, and execute permissions for the adapter group and no access for any other users.
After the script displays the message CASD Adapter Install Complete, press Enter to complete the installation.
If the adapter was configured to run using the HTTPS protocol, you must install a SSL certificate. You can install a self-signed certificate, or you can acquire a certificate from a Certificate Authority (CA).
- To generate and install a self-signed SSL certificate, enter the following commands, and replace <hostname> with the system host name or IP address that the CASD adapter will use:
```
"%JAVA_HOME%\bin\keytool" -delete -alias iwave -keypass iwavepw -storepass iwavepw -keystore keystore.jks
"%JAVA_HOME%\bin\keytool" -genkey -alias iwave -keyalg RSA -keysize 1024 -dname "CN=<hostname>, OU=Development, O=iWave Software, L=Frisco, ST=TX, C=US" -keypass iwavepw -storepass iwavepw -keystore keystore.jks
```
- To install a certificate that the Certificate Authority issues:
  - Request a certificate from a Certificate Authority, such as VeriSign.
    
    In the certificate request, make sure to specify the host name or IP address that the CASD adapter will use. The host name in the certificate must match the host name configured for the adapter. If they do not match, the adapter cannot function.
  - After you obtain the certificate from the Certificate Authority, enter the following command to install the certificate, where <certificateFile> is the full path name of the file provided by the Certificate Authority:
```
"%JAVA_HOME%\bin\keytool" -export -alias iwave -file <certificateFile> -keypass iwavepw -storepass iwavepw -keystore keystore.jks
```

The following steps are optional. If you want the adapter to run as a Windows service, perform the following steps.

Log into an account that has permission to add a windows service.

Note:
On most systems, the account must be a member of the Administrators group to add a windows service.
Make sure the account has read and execute permissions for the adapters\bin directory.
Change the working directory to the adapters\bin directory in the installation directory.
Enter the following command to install the adapter as a Windows service:

service.bat install
Make sure the designated login account for the windows service has Full Control for the adapter directory and read and execute permissions on the conf\framework.properties file.

The adapter framework is now installed and ready to start.

To add signed certificates to Wallet Manager, see Adding Signed Certificates to Wallet Manager.

Running the Adapter on Windows

There are two ways you can run the adapter on Windows: Standalone Service and Windows Service.

Standalone Service

To start the CASD adapter framework when set up as a standalone application (not set up to run as a Windows service):

Change the working directory to the adapters\bin directory in the installation directory.
Run the following command:

startAdapters.bat

To shut down the CASD adapter framework, close the window where you started the adapter.

Windows Service

To start the CASD adapter framework when set up to run as a Windows service, run the following command:

net start iWaveAdapters

To shut down the CASD adapter framework, run the following command:

net stop iWaveAdapters

Testing the Adapter on Windows

Perform the following steps to verify that the CASD Adapter is functional.

Open a terminal and change the working directory to the adapters\bin directory in the installation directory.
Enter the following command to run the test script:

.\testAdapter.bat
The test script will prompt for the password information. At the prompt, enter the password that was configured for accessing the Adapter web service in step 11 of Section 2.2.3.1, "Installing the Adapter on Windows".
If the test completes successfully, the last line the utility displays is Test completed successfully.

Installing the Connector

Perform the following steps to install the connector:

Copy casd_connector.jar to $ORACLE_HOME/sysman/connector on the server hosting your OMS. For multiple OMSes, you need to copy the jar file for all OMSes.
Run the following emctl command on all OMSes if you have a multi-OMS environment:
```
$ORACLE_HOME/bin/emctl extract_jar connector -jar <jarfile> 
-cname <connector_name>
```
This extracts the jar file to this folder:

$ORACLE_HOME/sysman/connector/CASD_Connector/

For example:
```
emctl extract_jar connector -jar casd_connector.jar 
-cname "CASD Connector"
```
Deploy the connector by running the following emctl command. You only need to run this step on one OMS.

$ORACLE_HOME/bin/emctl register_connector connector -dd <connectorType.xml>

-cs //<server>:<port>/<dbSID> -repos_user <username> -repos_pwd <password>

For example:
```
emctl register_connector connector -dd $ORACLE_HOME/sysman/connector/
CA_Service_Desk_Connector/CADeploy.xml  
-cs  //$emhost:$dbport/$dbSID -repos_user sysman -repos_pwd $repospwd
```

The CASD Connector should now appear in the Management Connector page with version 1.0.5.1.0.

Registering the Ticket Templates

There are two default templates located in the $ORACLE_HOME/sysman/connector/CASD_Connector/templates directory:

CASD_Default_Incident.xsl
CASD_Default_Incident_AutoClose.xsl

Note:

See Template Process for detailed information about these templates.

Perform the following steps to register these templates as well as others:

For each template above, run the following emctl register_ticket_template connector command as a user with execute privilege on emctl and the ability to read the ticket template:

$ORACLE_HOME/bin/emctl register_ticket_template connector -t <ticketTemplate.xsl> -cs //<server>:<port>/<dbsid/service name for RAC DB> -repos_user <username> -repos_pwd <password> -ctname <connectorTypeName> -cname  <connectorName> -iname <internalName> -tname <templateName> -ttype 2 -d <description>

See Table 2-1, "emctl Parameters" for descriptions of the command parameters.

Run the same command for each of the following templates:

createTicketResponse.xsl - Specify ttype 1, iname createTicket
getTicket_response.xsl - Specify ttype 1, iname getTicket
getTicket_request.xsl - Specify ttype 2, iname getTicket
updateTicketResponse.xsl - Specify ttype 1, iname updateTicket

These templates are located in the following directory:

$ORACLE_HOME/sysman/connector/CASD_Connector

For templates CASD_Default_Incident.xsl and CASD_Default_Incident_AutoClose.xsl, the internal name can be the file names. For the other templates, the inames are fixed.

For multiple OMS installations, you must run the emctl command only once for each template from any of the OMSes.

Table 2-1, "emctl Parameters" provides descriptions for the parameters shown in the emctl command above.

Table 2-1 emctl Parameters

Parameter	Description
cs	Connect string. Specify as "//$emHost:$dbPort/$dbSID", where, $emHost is the server, $dbPort is the port, and $dbSID is the database session identifier.
server	Host name of the Enterprise Manager repository
port	Listener port of the repository.
database sid/ Service Name for RAC DB	Repository database instance ID or service name if you are using RAC database as the repository
repos_user	Specify SYSMAN
repos_pwd	Password for SYSMAN
ctname	Connector type name - Specify "CA Service Desk Connector". The double quotes ("") are mandatory.
cname Connector name	Specify "CA Service Desk Connector". The double quotes ("") are mandatory
iname Internal name	Depending on the template, the values can be CASD_Default_Incident_AutoResolve.xsl, CASD_Default_Incident_AutoClose.xsl, or createTicket, getTicket
tname Template name	Depending on the template, the values can be Create Ticket Response, Get Ticket Request, Get Ticket Response, Update Ticket Response, or a value defined by the user
ttype Template type	Specify 1 for inbound transformation and 2 for outbound transformation
description	Short description for the ticket template. This description is also displayed in Enterprise Manager

Example 2-1, "Registration Example" shows template registration for the CASD_Default_Incident_AutoClose.xsl template.

Example 2-1 Registration Example

emctl register_template connector -t "$ORACLE_HOME/sysman/connector/CASD _Connector/templates/CASD_Default_Incident_AutoClose.xsl" -cs "//$emHost:$dbPort/$dbSID" -repos_user sysman -ctname "CASD Connector" -cname "CASD Connector" -tname "CASD_Default_Incident_AutoClose.xsl" -iname "CASD_Default_Incident_AutoClose.xsl" -ttype 2 -d "Template creates a ticket with priority based on event severity. It sets the ticket to 'Closed' if the event severity clears" -repos_pwd $repos_pwd

The following table lists the properties of each template for the CASD Connector.

Table 2-2 Template Properties

Template	Template Name	Internal Name	Template Type
CASD_Default_Incident_AutoClose.xsl	<Defined by the users>	CASD_Default_Incident_AutoClose.xsl	2
CASD_Default_Incident.xsl	<Defined by the users>	CASD_Default_Incident_.xsl	2
createTicketResponse.xsl	Create Ticket Response	createTicket	1
getTicket_request.xsl	Get Ticket Request	getTicket	2
getTicket_response.xsl	Get Ticket Response	getTicket	1
updateTicketResponse.xsl	Update Ticket Response	updateTicket	1

Uninstalling the Connector

To uninstall the connector, follow these steps:

Click the Setup link in the upper right corner of the Oracle Enterprise Manager console.
Click the Management Connectors link in the left column of the Overview of Setup page.
Select the connector, then click Delete.
On the Confirmation page, click Yes.

Uninstalling the Adapter

This section describes the procedures for uninstalling the adapter on Unix and on Windows.

Uninstalling the Adapter on Unix

To uninstall the adapter on a Unix platform, perform the following steps:

Stop the adapter as specified in Running the Adapter on Unix.
Delete the adapters folder from the adapter installation directory.

Uninstalling the Adapter on Windows

To uninstall the adapter on a Windows platform, perform the following steps:

Stop the adapter as specified in Running the Adapter on Windows.
If the adapter is installed as a Window service, perform the following steps to uninstall the adapter as a service:
- Open a command window and change the working directory to the adapters\bin directory in the adapter install directory.
- Issue the command .\service uninstall
Delete the adapters folder from the adapter installation directory.

Navigating Between CASD and Enterprise Manager

The following sections explain how to switch from one console to the other.

Navigating from CASD to Enterprise Manager

From the Incident Detail page, click the link to the URL label in the Description field, as shown in Figure 2-1. This action takes you to the Enterprise Manager console login page. After you provide the Enterprise Manager user name and password, you are forwarded to the alert related to this incident.

Note:

The Enterprise Manager user whose name you specify should at least have View privileges on the target on which the alert was raised.

Figure 2-1 Incident Detail in CASD Console

Navigating from Enterprise Manager to CASD

Follow these steps to navigate from Enterprise Manager to CASD:

In the Enterprise Manager console, click the alert message to go to the Metric Details page for the alert.
In the Alert History table, locate the ticket ID link in the Last Comment column.

Note:
The ticket id that is displayed is comprised of two identifiers used by CASD. The first ID is the external identifier and is a numeric value. This is the incident identifier that is displayed at the CASD web console. The second ID is the internal identifier and is listed in parentheses. The internal identifier is comprised of cr: followed by a numeric value. This identifier is used when the connector submits update, reopen, or close requests to the CASD Adapter.
(If not found) Click the icon in the Details column to get more information about the alert.
On the page that appears, locate the ticket ID in the Alert Details table.
Click the ticket ID link. You are forwarded to the CASD Web console login page.
Provide valid CASD account details.

The incident details associated with this alert are displayed.

Adding Signed Certificates to Wallet Manager

To add signed certificates to Wallet Manager, follow these steps on Enterprise Manager:

Note:

Oracle Wallet Manager is available at $ORACLE_HOME/bin on OMS. See the Oracle Application Server Administrator's Guide for details.

Do the following to obtain a copy of the certificate that the CASD Adapter is using:
1. Open a command prompt window and change the working directory to the adapters/comf directory in the adapter install directory:
  
  <ADAPTER_INSTALL>/adapters/conf
2. Issue the following command to extract the certificate:
  - Unix platforms:
    
    $JAVA_HOME/bin/keytool -exportcert -alias iwave -file CASDws.cer -keystore keystore.jks -storepass iwavepw
  - Windows platforms:
    
    "%JAVA_HOME%\bin\keytool" -exportcert -alias iwave -file CASDws.cer -keystore keystore.jks -storepass iwavepw
3. Transfer the certificate file CASDws.cer to the system where Enterprise Manager is installed.
As Super Administrator, create a wallet using the following orapki utility command at the OMS host:

orapki wallet create -wallet client -auto_login

Note:
orapki is available at $ORACLE_HOME/bin on OMS.
Add the trusted certificate to the wallet by entering the following command:

orapki wallet add -wallet client -trusted_cert -cert CASDws.cer
To view the content of the wallet, enter the following command:

orapki wallet display -wallet client

Ensure that the information for the CASDws.cer certificate is displayed.
In Oracle Wallet Manager, open the client wallet.
Go to Select Trusted Certificates and select Operations on the main menu.
Select Export All Trusted Certificates.
Save the file as certdb.txt.
Place the file certdb.txt in the connector home root directory ($OMS_HOME/sysman/connector).

If the file certdb.txt already exists in the root directory, open the file and add the contents of your certdb.txt to the existing content.

Now Java SSL can use this file for communication between Enterprise Manager and the CASD Adapter in HTTPS mode.

Note:

For information on creating a wallet, see "Creating and Viewing Oracle Wallets with orapki" in the Oracle Database Advanced Security Administrator's Guide, 10g Release 2 (10.2).