Oracle Enterprise Manager Installation and Configuration Guide for HP OpenView Operations Connector, Release 12 (1.1.4.1.0)

Release 12 (1.1.4.1.0)

E12861-12

Contents

Title and Copyright Information

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

1 Introduction to the Connector

- Connector Features

- Oracle Enterprise Manager Alerts Transmitted to OVOU Messages

- Oracle Enterprise Manager Event Polling to OVOU

- Versions Supported

- Prerequisites

2 Installing the Connector

- Installation Platforms

- Installing and Running the HP OpenView Operations Agent

- Installing the Agent

- Running and Stopping the Agent

- Installing the HP OpenView Operations Web Service

- Installing and Running the HP OpenView Operations Web Service on Unix

- Installing the Web Service on Unix

- Running the Web Service on Unix

- Installing and Running the HP OpenView Operations Web Service on Windows

- Prerequisites

- Installing the Web Service on Windows

- Running the Web Service on Windows

- Adding Signed Certificates to Enterprise Manager

- Adding Signed Certificates to Wallet Manager

- Adding Signed Certificates to cacerts

- Installing the HP OpenView Operations Connector in Oracle Enterprise Manager

- Registering Templates

3 Configuring the Connector

- Configuring the General Page

- Configuring the Targets Page

- Testing the HP OVO Connector

- Sending Oracle Enterprise Manager Alerts to HP OVOU

- Creating Notification Rules

- Updating Notification Rules

- Viewing Oracle Enterprise Manager Alerts

4 Changing Default Configurations

- Customizing Mappings

- XML Format of HP OpenView Operations Messages

- Mappings Between XML Format and Message Field Names

- Extended Fields

- XML Format of Oracle Enterprise Manager Alerts

- Changing a Mapping

- Changing Default Port Numbers

- Changing Port Number 9099

- Changing Port Number 9007

- Changing Port Number 8080/8443

5 Troubleshooting the Connector

- Preparing for Troubleshooting

- Using the Correct URL for OVO Web Service Operations

- Diagnosing Problems with Message Generation and Updates

- Alerts from Oracle Enterprise Manager to OVOU

- Messages from OVO to Oracle Enterprise Manager

- Resolving Alerts from Oracle Enterprise Manager

- Resolving Messages from OVO

A Default Mappings

- Data Translation Files

- createEvent Operation

- updateEvent Operation

- getNewAlerts and getUpdatedAlerts Operations

Index

Oracle® Enterprise Manager

Installation and Configuration Guide for HP OpenView Operations Connector

Release 12 (1.1.4.1.0)

E12861-12

May 2011

Oracle Enterprise Manager Installation and Configuration Guide for HP OpenView Operations Connector, Release 12 (1.1.4.1.0)

E12861-12

Copyright © 2011, Oracle and/or its affiliates. All rights reserved.

Primary Author:  Michael Zampiceni

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Preface

This Installation and Configuration Guide for HP OpenView Operations Connector provides the information that you require to install and configure the HP OpenView Operations Connector that integrates Oracle Enterprise Manager with HP OpenView Operations management tools.

Audience

This guide is written for Oracle Enterprise Manager system administrators who want to install and configure the HP OpenView Operations Connector to enable integration between Oracle Enterprise Manager and HP OpenView Operations.

You should already be familiar with Oracle Enterprise Manager.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at

http://www.oracle.com/accessibility/

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

TTY Access to Oracle Support Services

To reach Oracle Support Services, use a telecommunications relay service (TRS) to call Oracle Support at 1.800.223.1711.

Related Documents

For more information, see the following books in the Oracle Enterprise Manager documentation set:

- Oracle Enterprise Manager Integration Guide

- Oracle Database 2 Day DBA

- Oracle Enterprise Manager Concepts

- Oracle Enterprise Manager Quick Installation Guide

- Oracle Enterprise Manager Grid Control Installation and Basic Configuration

- Oracle Enterprise Manager Advanced Configuration

- Oracle Enterprise Manager Metric Reference Manual

- Oracle Enterprise Manager Command Line Interface

- Extending Oracle Enterprise Manager

The latest versions of this and other Oracle Enterprise Manager documentation can be found at:

http://www.oracle.com/technology/documentation/oem.html

Oracle Enterprise Manager also provides extensive online help. Click Help on any Oracle Enterprise Manager page to display the online Help system.

Printed documentation is available for sale in the Oracle Store at

http://oraclestore.oracle.com/

To download free release notes, installation documentation, white papers, or other collateral, please visit the Oracle Technology Network (OTN). You must register online before using OTN; registration is free and can be done at

http://otn.oracle.com/membership/

If you already have a user name and password for OTN, then you can go directly to the documentation section of the OTN Web site at

http://otn.oracle.com/documentation/

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Introduction to the Connector

The Hewlett-Packard OpenView Operations Connector (version 1.1.4.1.0) integrates Oracle Enterprise Manager with HP OpenView Operations Unix, or OVOU, (version 8.0) through web services, enabling you to exchange event information between the two applications.

Connector Features

The Oracle Management Connector for HP OpenView Operations (OVOU) enables customers who manage their data centers using HP OpenView Operations to integrate with Oracle Enterprise Manager by enabling end-to-end event and alert sharing. The connector allows administrators to automatically forward OVOU events to Oracle Enterprise Manager as well as forward Oracle Enterprise Manager alerts to OVOU.

Additionally, the connector monitors all of the events forwarded from OVOU and automatically updates alert information in the Oracle Enterprise Manager console anytime changes occur in OVOU. A similar synchronization of alerts sent from Oracle Enterprise Manager occurs in OVOU. This ensures that the two systems are always synchronized, providing administrators with current information about their entire data center.

The connector supports the following features:

- Synchronization of the alert life cycle on both ends

- Customization of alert mappings during the alert information exchange

- Bi-directional flow of alert information
The state change of the event/alert in the originating system is reflected in the other system but not vice versa. For example, if an alert is forwarded from Oracle Enterprise Manager to HP OpenView Operations, all the state changes in Enterprise Manager are reflected in HP OpenView Operations. However, if you change the state of the alert in HP OpenView Operations, the change is not reflected in Enterprise Manager because the alert originated in Enterprise Manager. This is also the case for the other direction.

The following sections explain how the connector handles OVOU messages and polls the OVOU web service.

Oracle Enterprise Manager Alerts Transmitted to OVOU Messages

Conceptually, alerts in Oracle Enterprise Manager are equivalent to messages in OVOU. In OVOU, a message is information generated for the operator whenever an event occurs. In OVOU, the term acknowledge has a different meaning than it does for most applications. Acknowledging a message in OVOU means that an alert has been resolved and the message is closed.

Whenever an alert is triggered in Oracle Enterprise Manager, the OVOU Connector can automatically open or update a message in OVOU. You can use Notification Rules to specify the set of alerts for which messages must be opened, and the alert severity for which this should happen.

After the connector opens an event message in OVOU, any subsequent change of the alert severity is propagated to HP OpenView Operations. When the severity of the alert changes to Clear in Oracle Enterprise Manager, the corresponding message is acknowledged; that is, closed, in OVOU.

Figure 1–1 shows an example of an Oracle Enterprise Manager alert message.

Figure 1-1 Oracle Enterprise Manager Alert Message

Figure 1–2 shows an example of an HP OVOU message.

Figure 1-2 HP OVOU Message

Oracle Enterprise Manager Event Polling to OVOU

After installation and configuration, the event connector automatically polls the OVOU web service for events to exchange alerts and messages with Oracle Enterprise Manager. The poll cycle is configurable, where the duration is specified in minutes with a minimum possible duration of 5 minutes.

Every poll cycle, the event connector polls for up to 200 new or updated events in OVOU. The Oracle Enterprise Manager connector framework processes and acknowledges all of the events provided in the poll response.

Versions Supported

This connector supports the following versions of Oracle Enterprise Manager and HP OpenView Operations:

- Oracle Enterprise Manager Grid Control:

- 10g Release 4 with one-off patch 6884527

- 10g Release 5

- 11g Release 1

- HP OpenView Operations 8

You can install the HP OpenView Operations Agent, which is part of the connector bundle, on the following platforms:

- HP-UX on Itanium architecture with OS version 8 and above

- Solaris on SPARC architecture with OS version 10 and above

The base Enterprise Manager version number for HP OpenView Operations Release 10 (1.1.4.1.0) is Enterprise Manager 10g Release 4.

Prerequisites

Before using HP OpenView Operations Connector, ensure that you meet the following prerequisites:

- Oracle one-off patch 6884527 for 10g Release 4 is installed.

1. Download patch # 6884527 from:
http://metalink.oracle.com/

2. Follow the instructions included with the download in the README.txt file.

Note:

No patches are required for 10g Release 5 or 11g Release 1.

- The gunzip utility is available on the system hosting HP OpenView Operations.

- An HP OpenView Operations user account must be set up that the HP OpenView Operations Agent can use. The account must have administrative privileges.

If you want Oracle Enterprise Manager to forward alerts to HP OVOU, you need to do the following:

- Create a message group named OracleEnterpriseManager at the HP OpenView Operations server. The HP OpenView Operations account mentioned above must have access to this message group and must be able to create and update messages in this message group.

- Create a node named OracleEnterpriseManager at the HP OpenView Operations server. This node must be a Message Allowed type and must not have an associated IP address. Messages inserted by Enterprise Manager are assigned to this node.

2 Installing the Connector

The Oracle Enterprise Manager Connector Framework requires a web service interface for exchanging event information with HP OpenView Operations (OVO). Since OVO does not provide a web services interface, you must install a third-party OVO web service front-end, which is included in the Oracle Enterprise Manager installation package.

You can install the web service on any UNIX or Windows system that has connectivity with the OVO server. In addition to the OVO web service front-end, you must also install a back-end Oracle OVO Agent on the same physical system as the OVO server. The Oracle OVO Agent is preconfigured and is also included in the Oracle Enterprise Manager installation package.

Figure 2–1 shows the communication between the various components of the OVOU Connector.

Figure 2-1 Connector Communication Between Components

The following sections in this chapter discuss these topics:

- Installation Platforms

- Installing and Running the HP OpenView Operations Agent

- Installing the HP OpenView Operations Web Service

- Installing the HP OpenView Operations Connector in Oracle Enterprise Manager

- Registering Templates

Installation Platforms

You can install the HP OpenView Operations web service on the following platforms that support Java JRE 1.6:

- Microsoft Windows

- Sun Solaris

- HP-UX

- Linux

You can install the HP OpenView Operations Agent on the following platform:

- HP-UX on Itanium architecture with OS version 8 and above

- Solaris on SPARC architecture with OS version 10 and above

Installing and Running the HP OpenView Operations Agent

The following sections provide procedures that successfully enable you to install the Agent, then subsequently run it.

Installing the Agent

The back-end Oracle OVO Agent exchanges data with the OVO API and must be run on the same physical system as the OVO server. The Oracle OVO Agent is preconfigured to interface with the OVO Web Service and requires minimal configuration.

To install the Oracle OVO Agent, perform the following steps:

1. Download the hp_ovou_connector_bundler.jar file from the Oracle Technology Network to the installation directory.

2. Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.

3. Extract the .jar file by running the following command:

jar -xvf hp_ovou_connector_bundle.jar

4. Put the appropriate installation file into the directory where you intend to install the Oracle OVO Agent. Note that you need to do this on the HP OpenView Operations system host.
For the HP-UX platform, the Agent zip file is named agent-hpovou-connector.tar.gz, and for the Solaris platform, the Agent zip file is named agent-solaris-connector.tar.gz.

5. Open a terminal and change the working directory to the installation directory.

6. Enter the appropriate command listed below to unzip the Agent zip:

- For HP-UX:

gunzip agent-hpovou-connector.tar.gz

- For Solaris:

gunzip agent-solaris-hpovou-connector.tar.gz

7. Enter the appropriate command listed below to extract the installation files from the resulting .tar file:

- For HP-UX:

tar xvf agent-hpovou-connector.tar

- For Solaris:

tar xvf agent-solaris-hpovou-connector.tar

This creates the ovo-agent directory that contains the installation files.

8. Change the working directory to the ovo-agent/scripts directory.

9. Enter the following command to run the setup script to configure the Oracle OVO Agent:
./setup.sh

The following prompts appear in this sequence:

1. Enter the OpenView message groups to register — Enter a space-separated list of the OVO message group(s) to be picked up by Oracle Enterprise Manager when polling for new or updated alerts.

Note:

All message groups registered with the Agent must have an automatic action defined. This enables the Agent to detect new messages created in OVO. For any message groups that do not already have a defined automatic action, the recommended approach is to set up an automatic action to invoke a script that does nothing.

2. Enter the OVO UserID to be used — Enter the user name for the OVO account to be used for accessing the OVO API. This is the OVO user account specified in the prerequisites section.

3. Enter the OVO Password — Enter the password for the OVO account to be used in accessing the OVO API. This is the OVO user account specified in the prerequisites section.
Note that for security reasons, the password information will not be echoed to the terminal.

4. Enter the system UserID that has access to start and stop the service — Enter the system user name that will be able to start and stop the Oracle OVO Agent.

Note:

For the Solaris platform, the account that starts the Agent must include the /opt/OV/lib path in the LD_LIBRARY_PATH environment variable. This instructs the OS where to find the OVO libraries that the Agent references.

5. Enter the host name of the HP-OVO Adapter — Enter the host name where the OVO web service will be installed. This can be on the same system or on a different system that has connectivity to the OVO server and the Oracle Enterprise Manager server.

10. Open another terminal and log in as root.

11. Change the working directory to the ovo-agent/scripts directory in the Oracle OVO Agent installation directory.

12. Enter the following command to enable the Oracle OVO Agent to run with root permissions:
./root-setup.sh

13. Close the terminal where you are logged in as root.

14. Delete the agent-hpovou-connector.tar file from the installation directory.

Running and Stopping the Agent

Running the Agent

Before starting the Agent on the Solaris platform, verify that the LD_LIBRARY_PATH environment variable contains the /opt/OV/lib path.

To start the Oracle OVO Agent, enter the following command:

./startallbb

Stopping the Agent

To stop the Oracle OVO Agent, enter the following command:

./stopallbb

You must specify the user name and password for the account that is authorized to stop the Oracle OVO Agent.

Installing the HP OpenView Operations Web Service

The OVO web service acts as a front-end for all data flowing into and out of OVO. Oracle Enterprise Manager posts calls to the web service whenever it needs to create or update a message, or get new or updated messages from OVO.

You can install the OVO web service on any UNIX or Windows system that has connectivity to the OVO server and the Oracle Enterprise Manager server.

Installing and Running the HP OpenView Operations Web Service on Unix

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

Installing the Web Service on Unix

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

1. Create a directory where you want to install the web service.

2. Open a terminal and change the working directory to the installation directory.

3. Download the hp_ovou_connector_bundler.jar file from the Oracle Technology Network to the installation directory.

4. Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.

5. Extract the .jar file by running the following command:

jar -xvf hp_ovou_connector_bundle.jar

6. Enter the following command to unzip the .tar file:
gunzip ws-hpovou-connector-unix.tar.gz

7. Enter the following command to extract the installation files:
tar xvf ws-hpovou-connector-unix.tar

This creates the iwave-af-1.1.1 directory that contains the installation files.

8. Enter the following command to change the working directory as follows:
cd iwave-af-1.1.1/endpoints/hpovou

9. Enter the following command to run the installation script:
./install.sh

10. When the script prompts whether you want to use HTTPS:

- If you specify Y, the web service is set up to use HTTPS port number 8443.

- If you specify N, the web service is set up to use HTTP port number 8080.

11. When the script prompts for the host name of the HP-OVO server, enter the host name where the Oracle OVO Agent is installed.
Note that you cannot specify the host name of a local host. The host name must be the actual host name or IP address of the system.

12. Enter the following command to change the working directory to the iwave-af-1.1.1 directory:
cd ../..

13. Enter the following command to change the user name and password for accessing the OVO web service:
bin/propertiesEditor.sh -e framework.username="<username>" -e framework.password="<password>" conf/spring.properties

... where <username> is the user name to specify for the web service, and <password> is the password.

This command encrypts the user name and password information in the configuration file.

14. Delete the ws-hpovou-connector-unix.tar file from the installation directory.

The web service framework is now installed and ready to start.

If the HP OpenView Operations Web Service was configured to use the HTTPS protocol, the certificate must be imported into Enterprise Manager. See Adding Signed Certificates to Enterprise Manager for instructions.

Running the Web Service on Unix

To run the HP OpenView Operations Web Service framework commands listed with the following tasks, first change the working directory to ...

iwave-af-1.1.1/bin

... in the installation directory.

- Start — ./service.sh start

- Shut Down — ./service.sh stop

- Restart — ./service.sh restart

- Check Status — ./service.sh status

Installing and Running the HP OpenView Operations Web Service on Windows

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

Prerequisites

The following prerequisites must be met before proceeding to the next section.

- Java Runtime Environment (JRE) version 6 is installed.

- JAVA_HOME environment variable is set to the JRE installation directory.

- Zip utility, such as WinZip, is installed for unzipping a zip file.

Installing the Web Service on Windows

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

1. Create a directory where you want to install the web service.

2. Open a terminal and change the working directory to the installation directory.

3. Download the hp_ovou_connector_bundler.jar file from the Oracle Technology Network to the installation directory.

4. Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.

5. Extract the .jar file by running the following command:

jar -xvf hp_ovou_connector_bundle.jar

6. Open a command prompt window and change the working directory to the installation directory.

7. Unzip the ws-hpovou-connector-windows.zip file using a zip utility.

8. Change the working directory to the iwave-af-1.1.1\conf directory.

9. Enter the following command to install the OVO connector configuration file:
copy ..\endpoints\hpovou\hpovou-spring.xml .

10. Enter the following command to configure the web service to connect to the Oracle OVO Agent ...

..\bin\propertiesEditor.bat -p hpovou.xmlagent=http://<OVOserver>:9007 spring.properties

... where <OVOserver> is the host name or IP address of the OVO server.

11. Configure the URL used by the web service based on whether you want to encrypt data. There are two possible protocols available: the default protocol is HTTP, which does not provide encryption of data. The other protocol available is HTTPS, which provides encryption of data using SSL certificates.
Oracle recommends that you use HTTPS as the protocol for the communication between Enterprise Manager and the HP OVOU Web Service server. Use HTTP only if a secure connection is not required and the data can be transferred in clear text between the two systems.

- To configure the web service without encryption, enter the following command to configure the web service URL ...

..\bin\propertiesEditor.bat -p services.url=http://<hostname>:8080/ services spring.properties

... where <hostname> is the host name or IP address of the system where the web service will be installed.

The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for UNIX platforms is propertiesEditor.sh.

- To configure the web service to use encryption, enter the following command to configure the web service URL ...

..\bin\propertiesEditor.bat -p services.url=https://<hostname>:8443/ services spring.properties

... where <hostname> is the host name or IP address of the system where the web service will be installed.

12. Install an SSL certificate. You need to do this whether or not the data will be encrypted. If you configured the web service to use the HTTP protocol in the preceding step, install a self-signed SSL certificate. If you configured the web service to use the HTTPS protocol, you can install a self-signed SSL certificate or one that the Certificate Authority assigns.

- To generate and install a self-signed SSL certificate:

- Enter the following command, and replace <hostname> with the system host name or IP address specified in the preceding step:

"%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 of the system specified in the preceding step. The host name in the certificate must match the host name configured for the web service. If they do not match, the web service 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

13. Enter the following command to change the user name and password for accessing the OVO web service ...
..\bin\propertiesEditor.bat -e framework.username="<username>" -e framework.password="<password>" spring.properties

... where <username> is the user name to specify for the web service, and <password> is the password.

This command encrypts the user name and password information in the configuration file.

14. Delete the ws-hpovou-connector-windows.zip file.

The web service framework is now installed and ready to start.

If the HP OpenView Operations Web Service was configured to use the HTTPS protocol, the certificate must be imported into Enterprise Manager. See Adding Signed Certificates to Enterprise Manager for instructions.

Running the Web Service on Windows

To start the OVO web service framework:

1. Change the working directory to the iwave-af-1.1.1\bin directory in the installation directory.

2. Run the following command:
startAdapters.bat

To shut down the OVO web service framework, press Ctrl-C in the window where you started the adapter.

Adding Signed Certificates to Enterprise Manager

The Service Manager SSL certificate must be imported into Enterprise Manager. For versions 10.2.0.4 and 10.2.0.5, perform the steps in Adding Signed Certificates to Wallet Manager. For version 11.1.0.1, perform the steps in Adding Signed Certificates to cacerts.

Adding Signed Certificates to Wallet Manager

Note:

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

Perform the following steps in Oracle Enterprise Manager to add signed certificates:

1. Do the following to obtain a copy of the certificate that the OVO web service is using:

1. Open a command prompt window and change the working directory to ...
<OVOWS_INSTALL>/iwave-af-1.1.1/conf

... where <OVOWS_INSTALL> is the directory where the OVO web service is installed.

2. Issue the following command to extract the certificate:
— Unix platforms:

$JAVA_HOME/bin/keytool -exportcert -alias iwave -file ovows.cer -keystore keystore.jks -storepass iwavepw

— Windows platforms:

%JAVA_HOME%\bin\keytool -exportcert -alias iwave -file ovows.cer -keystore keystore.jks -storepass iwavepw

3. Transfer the certificate file ovows.cer to the system where Enterprise Manager is installed.

2. Open a new terminal and set the ORACLE_HOME environment variable to the directory where OMS is installed.

3. As Super Administrator, create a wallet using the following orapki utility command at the OMS host:
$OMS_HOME/../agent11g/orapki wallet create -wallet client -auto_login

4. Add the trusted certificate to the wallet by entering the following command:
$OMS_HOME/../agent11g/orapki wallet add -wallet client -trusted_cert -cert <certFile>

5. To view the content of the wallet, enter the following command:
$OMS_HOME/../agent11g/orapki wallet display -wallet client

Verify that the certificate that was added is listed in the Trusted Certificates.

6. Start Oracle Wallet Manager and open the client wallet.

7. Click on Trusted Certificates and select Operations on the main menu.

8. Select Export All Trusted Certificates.

9. Save the file as certdb.txt.

10. Place the file certdb.txt in the connector home root directory ($OMS_HOME/sysman/connector).
If the certdb.txt file already exists in the root directory, open the file and add the contents of your certdb.txt file to the existing content.

Java SSL can now use this file for communication between Oracle Enterprise Manager and the OVO web service in HTTPS mode.

See Also:

For additional 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).

Adding Signed Certificates to cacerts

Do the following in Enterprise Manager to add signed certificates to the Java cacerts keystore:

1. Copy the certificate to the Enterprise Manager server system.

2. Determine the location of the JRE in the Oracle Home directory.

3. Open a command window and navigate to the JRE bin directory.

4. Enter the following command to add the certificate to the cacerts keystore:

keytool -importcert -keystore ..\lib\security\cacerts -storepass changeit -trustcacerts -file <certfile> -alias ovouws_cert

5. Restart OMS by opening a command window, changing the working directory to <ORACLE_HOME>/oms10g/bin, and issuing the following commands:

emctl stop oms
emctl start oms

Installing the HP OpenView Operations Connector in Oracle Enterprise Manager

The following steps explain how to add the new HP OpenView Operations Unix Connector to Oracle Enterprise Manager Grid Control.

Note:

Table 2–1 at the end of this section provides descriptions for the parameters shown for the emctl command in this procedure.

Note:

The commands in this section and the following section reference the OMS_HOME environment variable. OMS_HOME must be set to the OMS sub-directory in the Enterprise Manager installation directory. For versions 10.2.0.4 and 10.2.0.5, this is the oms10g directory. For version 11.1.0.1, this is the oms11g directory. Example settings of the OMS_HOME variable are /gc/OracleHomes/oms10g on a Unix platform running version 10.2.0.5, and C:\Oracle\Middleware2\oms11g on a Windows platform running version 11.1.0.1.

1. Enter the following command to extract the connector .jar file for versions 10.2.0.5 and 11.1.0.1:

$OMS_HOME/bin/emctl extract_jar connector -jar <jarfile> -cname <connectorTypeName>

For version 10.2.0.4, enter the following command:

$OMS_HOME/bin/emctl extract_jar connector <jarfile> <connectorTypeName>  <OracleHome>

Note:

You should perform this extraction on all OMS instances, because all OMS instances need to access the files locally.

10.2.0.5 and 11.1.0.1 Command Example

$OMS_HOME/bin/emctl extract_jar connector -jar "$OMS_HOME/ bin/sysman/connector/hpovou.jar" -cname "HP OVOU Connector"

When run, this creates the following new connector sub-directory:

$OMS_HOME/sysman/connector/HP_OVOU_Connector

2. Register the connector by entering the following command based on your Enterprise Manager version, noting the required double-quotes. You only need to perform the registration once.
11.1.0.1

$OMS_HOME/bin/emctl register_connector connector -dd "<deployment file>" -repos_pwd <repos_pwd>

10.2.0.5

$OMS_HOME/bin/emctl register_connector connector -dd "<deployment file>" -cs //<server>:<port>/<databaseSID> -repos_user <repos_user> -repos_pwd  <repos_pwd>

10.2.0.4

$OMS_HOME/bin/emctl register_connector connector “<deployment file>”  <server> <port> <databaseSid> <reposuser> <repospwd> “<omshome>”

11.1.0.1 Command Example

$OMS_HOME/bin/emctl register_connector connector -dd “$OMS_HOME/ sysman/connector/HP_OVOU_Connector/HPOVOUConnector.xml”
-repos_pwd password

The new HP OVO connector should now appear in the Management Connectors page after the emctl register_connector command has loaded the connector, as shown in Figure 2–2.

Figure 2-2 Installed HP OVO Connector

Table 2–1 provides descriptions for the parameters shown in the procedure above.

Table 2-1 emctl Parameters

Parameter

Description

cname

Connector name. Specify "HP OVOU Connector". The double quotes ("") are mandatory.

cs

Connect string. Specify as "//$emHost:$dbPort/$dbSID”, where, $emHost is the server, $dbPort is the port, and $dbSID is the database session identifier.

ctname

Connector type name. Specify "HP OVOU Connector". The double quotes ("") are mandatory.

database sid/ Service Name for RAC DB

Repository database instance ID or service name if you are using a RAC database as the repository.

deployment file

Fully-qualified name of the connector deployment file. This HPOVOUConnector.xml file resides in the following HP OVOU connector directory:

$OMS_HOME/sysman/connector/HP_OVOU_Connector/

description

Short description for the ticket template. This description is also displayed in Enterprise Manager.

iname

Internal name — Depending on the template, the values can be acknowledgeAlerts, createEvent, getNewAlerts, getUpdatedAlerts, or updateEvent.

oraclehome

Top directory of the OMS installation.

omshome

"<oraclehome>\oms10g" with double quotes recommended.

port

Listener port of the repository.

repos_pwd

Password for SYSMAN.

repos_user

Specify SYSMAN.

server

Host name of the Enterprise Manager repository.

tname

Template name — Depending on the template, the values can be Acknowledge Alerts, Create Event, Get New Alerts, Get Updated Alerts, or Update Event.

ttype

Template type — Specify 1 for inbound transformation and 2 for outbound transformation.

Registering Templates

The following steps explain how to register templates for various Enterprise Manager versions.

1. For each template, run the following emctl register_template connector command based on the Enterprise Manager version. The command must be run as a user with execute privilege on emctl and the ability to read the template.
11.1.0.1

$OMS_HOME/bin/emctl register_template connector -t <template.xml> -repos_pwd <password> -ctname <connector_type_name> -cname <connector_name> -tname <template_name> -iname <internal_name> -ttype <template_type> -d <description>

10.2.0.5

$OMS_HOME/bin/emctl register_template connector -t <template.xml> -cs //<server>:<port> /<database sid> -repos_user <username> -repos_pwd <password> -ctname <connector_type_name> -cname <connector_name> -tname <template_name> -iname <internal_name> -ttype <template_type> -d <description>

10.2.0.4

$OMS_HOME/bin/emctl register_template connector -t <template.xml> -cs //<server>:<port>/<databaseSID> -repos_user <username> -repos_pwd <password> -ctname <connector_type_name> -cname <connector_name> -iname <internal_name> -tname <template_name> -ttype <template_type> -d <description>

2. Replace <template.xml>, <internal_name>, <template_name> and <template_type> with the values listed in Table 2–2, which lists the properties of each template for the HP OpenView Operations Connector.

Table 2-2 Possible Replacement Values For register_template Parameters

template.xsl and template_xml

template_name

internal_name

template_type

acknowledge_request.xsl

Acknowledge Alerts

acknowledgeAlerts

2

createEvent_request.xsl

Create Event

createEvent

2

createEvent_response.xsl

Create Event

createEvent

1

generic_request_acknowledgealerts.xml

Acknowledge Alert

acknowledgeAlerts

3

getNewAlert_request.xsl

Get New Alerts

getNewAlerts

2

getNewAlerts_response.xsl

Get New Alerts

getNewAlerts

1

getUpdatedAlert_request.xsl

Get Updated Alerts

getUpdatedAlerts

2

getUpdatedAlerts_response.xsl

Get Updated Alerts

getUpdatedAlerts

1

updateEvent_request.xsl

Update Event

updateEvent

2

updateEvent_response.xsl

Update Event

updateEvent

1

template_type Key:

template_type1 — Inbound transformation template_type 2 — Outbound transformation template_type 3 — XML outbound transformation

The following example is based on the template values shown in Table 2–2.

Example 2-1 Request XSL File for acknowledgeAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/ HP_OVOU_Connector/acknowledge_request.xsl -repos_pwd mypassword -ctname "HP OVOU Connector" -cname "HP OVOU Connector" -tname "Acknowledge Alerts" -iname "acknowledgeAlerts" -ttype 2 -d "This is the request xsl file for acknowledgeAlerts method"

3 Configuring the Connector

This chapter provides procedures to configure the two sub-pages of the main Configure Management Connector page, then explains how to perform other tasks to complete the configuration process.

This chapter discusses the following topics:

- Configuring the General Page

- Configuring the Targets Page

- Testing the HP OVO Connector

- Sending Oracle Enterprise Manager Alerts to HP OVOU

Configuring the General Page

To configure the General page:

1. From the Management Connectors page, select the HP OVOU Connector and click the Configure icon. By default, the General sub-page of the Configure Management Connector page appears, as shown in Figure 3–1.

Figure 3-1 HP OVO Connector General Settings

2. Change HTTP to HTTPS at the beginning of the web service URLs if you have configured the HP OpenView Operations web services with HTTPS. Otherwise, go to the next step.

3. Change the port to the port on which the web services are running. For example, the default port for HTTP is 8080 and the default port for HTTPS is 8443.
If you are using HTTPS as the protocol, you must also include the HP OpenView Operations web service certificate in the Enterprise Manager as described in Adding Signed Certificates to Enterprise Manager.

Operation Descriptions

- getNewAlerts — Creates alerts in Oracle Enterprise Manager based on events (messages) that originate in HP OpenView Operations. Oracle Enterprise Manager uses this operation when polling for events in HP OpenView Operations.

- getUpdatedAlerts — Updates alerts in Oracle Enterprise Manager based on events (messages) that originate from HP OpenView Operations. Oracle Enterprise Manager uses this operation when polling for events from HP OpenView Operations.

- acknowledgeAlerts — Acknowledges the alerts after Oracle Enterprise Manager has processed them. Oracle Enterprise Manager uses this operation when polling for events in HP OpenView Operations.

- createEvent — Generates events (messages) in HP OpenView Operations based on alerts that originate in Oracle Enterprise Manager. Oracle Enterprise Manager invokes this operation when it forwards a new alert to OVOU.

- updateEvent — Updates events (messages) in HP OpenView Operations based on alerts that originate in Oracle Enterprise Manager. Oracle Enterprise Manager invokes this operation when it forwards a new alert to OVOU.

URL Types

The connector uses two different URLs. One URL is used for operations that poll data out of HP OpenView Operations (getNewAlerts, getUpdatedAlerts and acknowledgeAlerts), and defaults to the following value:

http://[Hostname]:8080/services/AcquisitionService

You need to replace [Hostname] in the URL when configuring it for HTTP.

The other URL is used for operations that push data into HP OpenView Operations (createEvent and updateEvent), and defaults to the following value:

http://[Hostname]:8080/services/hpovou/EventService

You need to replace [Hostname] in the URL when configuring it for HTTP.

4. Enter the user name and password of the Oracle Enterprise Manager account.

5. Optionally enter a polling interval to specify how often Oracle Enterprise Manager should poll the HP OpenView Operations web service for new or updated messages to process. The poll interval defaults to 5 minutes if not specified.

6. Click OK to save your configuration changes.

Configuring the Targets Page

Whenever an HP OpenView Operations message is translated into an Oracle Enterprise Manager alert, the HP OVO message node determines the target-type instance associated with the alert in Oracle Enterprise Manager. If a target instance that matches the message node is not found, the default target instance of generic_ovou_managed_node is used for the alert.

To add proxy targets in Oracle Enterprise Manager:

1. From the Configure Management Connector page, click the Targets link to display the Targets page, as shown in Figure 3–2.

Figure 3-2 HP OVO Connector Target Settings

2. Provide a target name. The Target Name field is set to the node name specified in the OVO message and must match the message node name exactly.

3. Provide the fully qualified OVOU node name in the OVOU NODE NAME field. This field must be set to the same value as the Target Name field.

4. Repeat this process for as many target instances as desired.

5. Click OK to save your configuration changes.

Testing the HP OVO Connector

Perform the following steps to test the connector:

1. 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.

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 HP OVOU Connector.

5. Click the General link.

6. Select and copy the URL specified for the createEvent or updateEvent operation.

7. Open an internet browser on the system where the Oracle Enterprise Manager server is installed.

8. 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]:8080/services/hpovou/EventService?wsdl

[Hostname] is the actual host name or IP address where the OVO web service is installed.

If the WSDL is loaded, this confirms that the connector is configured correctly for sending event information to OVO.

9. At the Oracle Enterprise Manager console, select and copy the URL specified for the getNewAlerts, getUpdatedAlerts, or the acknowledgeAlerts operation. They should all be set to the same URL.

10. Open an internet browser on the system where the Oracle Enterprise Manager server is installed.

11. In the address window, enter the URL that you copied in step 9 above. Add ?wsdl to the end of the URL. The URL should similar to the following example:
http://[Hostname]:8080/services/AcquisitionService?wsdl

[Hostname] is the actual host name or IP address where the OVO web service is installed.

If the WSDL is loaded, this confirms that the connector is configured correctly for polling event information from OVO.

Sending Oracle Enterprise Manager Alerts to HP OVOU

Alerts generated or updated in Oracle Enterprise Manager are not transferred to OVO unless you create notification rules to invoke the HP OVOU notification method. A notification rule identifies the conditions that must be met before the notification method is invoked.

The following sections provide procedures that explain how to create and update notification rules.

Creating Notification Rules

The following procedure explains how to create a new notification rule to invoke the OVO notification method.

1. Click the Preferences link in the upper right corner of the Oracle Enterprise Manager console. The General page appears.

2. Click the Notification Rules link on the left side of the window. The Notification Rules page appears and displays a list of all defined notification rules.

3. Click Create to create a new notification rule.

4. From the General sub-page, enter a name for the notification rule and an optional description.
Select the target type and whether you want it to apply to all targets of that type or a specific instance. If you indicate that you want a specific instance, you need to click Add and select the desired target instance.

5. Click the Availability link, then select the availability states for which you would like to receive notifications. Each state you select invokes the notification method whenever it is reached.

6. Click the Metrics link. If you want to trigger the notification method based on metric violations, click Add and select the metrics and states for which you want to invoke the notification method, then click Continue.

7. Click the Methods link. In the Advanced Notification Methods section, click the check box next to the HP OVOU Connector to assign the OVO notification method to the notification rule.

8. Click OK to complete the setup.

Updating Notification Rules

The following procedure explains how to update an existing notification rule to invoke the OVO notification method.

1. Click the Preferences link in the upper right corner of the Oracle Enterprise Manager console. The General page appears.

2. Click the Notification Rules link on the left side of the window. The Notification Rules page appears and displays a list of all defined notification rules.

3. Click on the radio button next to the notification rule you want to update, and click Edit to update the notification rule.

4. Click the Methods link. In the Advanced Notification Methods section, click on the check box next to the HP OVOU Connector to assign the OVO notification method to the notification rule.

5. Click OK to complete the update.

Viewing Oracle Enterprise Manager Alerts

Whenever a message is created in HP OpenView Operations from an alert that originates in Oracle Enterprise Manager, a link is provided in the message text. To view the Oracle Enterprise Manager alert that triggered the message, click on the link and you will be asked to log into Oracle Enterprise Manager. After logging in, the Oracle Enterprise Manager alert information is displayed.

4 Changing Default Configurations

This chapter explains how to change default mappings and default port numbers. This chapter discusses the following topics:

- Customizing Mappings

- Changing Default Port Numbers

Customizing Mappings

Although the default mappings are sufficient for most implementations, you can change them as needed. The following sections discuss:

- XML Format of HP OpenView Operations Messages

- XML Format of Oracle Enterprise Manager Alerts

- Changing a Mapping

It is assumed that you already have a good understanding of XSL.

For reference information on the default mappings, see Appendix A, "Default Mappings".

XML Format of HP OpenView Operations Messages

Example 4–1 represents the format that the HP OpenView Operations web service expects for creating new messages in HP OpenView Operations. The format for update requests is the same, except the root node would be update instead of create.

Example 4-1 Sample Format for HP OpenView Operations Web Service

<iwaveaf:create xmlns:iwaveaf="http://iwavesoftware.com/services/    adapter-framework">
<event>

<summary></summary>

<urgency></urgency>

<resolvedBy></resolvedBy>

<identifier></identifier>

<group>
<name></name>
</group>

<object>
<displayName></displayName>
</object>

<source>
<computerName></computerName>
</source>

<extended-fields>
<string-field value="Oracle Enterprise Manager" name="application"/>
<string-field value="NONE" name="ovo_ts_field"/>
<!-- CMA fields go here -->
<!-- The name attribute should be set to the name of the CMA field to           <!--  populate -->
<!-- The value attribute should be set to the value to place in the CMA           <!--  field -->
<!-- <string-field value="" name=""/> -->
</extended-fields>

</event>
</iwaveaf:create>

Mappings Between XML Format and Message Field Names

Table 4–1 identifies the mappings between the HP OpenView Operations message field names and the XML format that the HP OpenView Operations web services uses. To set the HP OpenView Operations message attributes, the XML document presented to the HP OpenView Operations web service must have the corresponding fields set. This must be handled in the appropriate translation file identified in Table A–1.

Table 4-1 Message Attributes and XML Path Mappings

HP OpenView Operations Message Attributes

XML Path

Identifier

/create/event/identifier

Message Text

/create/event/summary

Severity

/create/event/urgency

Message Group

/create/event/group/name

Object

/create/event/object/displayName

Node

/create/event/source/computerName

Application

See "Extended Fields" below.

ResolvedBy

/create/event/resolvedBy

CMA Fields

See "Extended Fields" below.

Extended Fields

An extended field is defined as a <string-field/> element that is a child of the extended-fields node. The name of the extended field is specified in the name attribute, and the value of this field is specified in the value attribute.

Some reserved extended field names are handled differently. The reserved field names are listed below along with a description of how they are handled.

- application — Reserved for the HP OpenView Operations application attribute. The specified value for this field is used to set the application field when creating or updating an HP OpenView Operations message.

- disown — Used to change the behavior of the HP OpenView Operations Agent. By default, the HP OpenView Operations account used to create the message is left as the owner. By setting this field to true, the message is disowned after it is created.

- ovo_ts_field — Used to prevent transaction loopback, and should always be set to NONE.

Any other extended field name you specify adds a Custom Message Attribute (CMA) field to the message. You specify the name of the CMA field for the Name attribute, and you specify the value for the Value attribute.

Note:

Adding CMA fields causes overhead. Attempting to add a large number of CMA fields can affect performance somewhat.

XML Format of Oracle Enterprise Manager Alerts

Example 4–2 shows the format that the Oracle Enterprise Manager Connector Framework provides when an alert is created or updated in Oracle Enterprise Manager.

Example 4-2 XML Format of Alerts

<EMEvent>
<EventGuid/>
<ExternalEventId/>
<ViolationId/>
<TargetType/>
<TargetName/>
<MetricName/>
<MetricColumn/>
<KeyValues/>
<Message/>
<Severity/>
<SeverityCode/>
<CollectionTime/>
<EventPageURL/>
<EMUser/>
<NotificationRuleName/>
<TargetHost/>
<TargetTimezone/>
<Property>
<Name/>
<Value/>
</Property>
</EMEvent>

Table 4–2 provides a description of the fields shown in Example 4–2.

Table 4-2 Field Descriptions for XML Format

Field

Description

EventGuid

Unique identifier of the alert in Oracle Enterprise Manager.

ExternalEventId

Unique identifier of the message in HP OpenView Operations. This will only be set for updates.

CollectionTime

Time the alert was generated.

TargetType

Target type for which the alert was generated.

TargetName

Target name that is a unique instance of the target type.

MetricName

Name of the metric that was violated.

MetricColumn

Column under the metric that was violated.

KeyValues

Key values associated with the metric column that was violated.

Severity

Severity text assigned to the alert.

SeverityCode

Severity numeric code assigned to he alert.

EMUser

User that owns the rule that generated the alert.

NotificationRuleName

Name of the notification rule that caused the alert to be forwarded to HP OpenView Operations.

EventPageURL

Link to the web page for the alert.

Message

Description of the alert.

TargetHost

Host name of the system where the target resides.

TargetTimezone

Time zone of the system where the target resides.

Property

Additional properties that do not have a specific field in the alert model.

Changing a Mapping

The following procedure provides the steps required for changing a mapping. Following this procedure below, an example is provided to more fully illustrate the procedure.

1. Study the default mapping and determine the changes you want to make.

2. Create a back-up copy of the XSL file you want to change.

3. Open the XSL file in a text editor or in an XSLT editor.

4. Change the file to map the fields as determined in step 1. You might need to study the information in Section 4.1.1 and Section 4.1.2. These sections describe the data formats of the HP OpenView Operations messages and Oracle Enterprise Manager alerts.

5. Save your changes.

The files are now ready for integration. You do not need to stop and start OMS. The changes will automatically be picked up.

Example of Changing a Mapping

By default, the Application field in the HP OpenView Operations message is set to the Oracle Enterprise Manager target type, and no CMA fields are defined. The example procedure below shows how to change the value assigned to the Application field to a different value. The example also shows how to add a CMA field.

The changes made to the default mapping are as follows:

- The Application field is modified to use a hard-coded value of Oracle Enterprise Manager.

- A new CMA field named TargetType is added to contain the TargetType associated with the Oracle Enterprise Manager alert.

1. Make a back-up copy of the createEvent_request.xsl file and name it default_createEvent_request.xsl.

2. Make a backup copy of the updateEvent_request.xsl file and name it default_updateEvent_request.xsl.

3. Open the createEvent_request.xsl file in your text editor.

4. Change the Extended Fields section to reflect the new mapping.

- Before Changes
The code below shows the Extended Fields section in the file before the changes.

<extended-fields>
<!-- The extended fields section contains any fields that are not           <!--  defined in the event model -->

<!-- BEGIN RESERVED FIELDS SECTION -->
<!-- The fields defined in this section are reserved and have                 <!-- special meaning -->

<!-- The application field is mapped to the OVO Application                 <!--  field -->
<string-field name="application">
<xsl:attribute name="value">
<xsl:value-of select="a:TargetType"/>
</xsl:attribute>
</string-field>

<!-- The ovo_ts_field node must always be set to NONE -->
<string-field value="NONE" name="ovo_ts_field"/>

<!-- The following extended field is used to disown the alert in                 <!-- OVO after it is created -->
<!-- By default, the ovo user account used to create the alert                 <!-- will be left as the owner -->
<!-- To force it to disown it after it is created, uncomment the                <!--  following line and comment out the next line -->
<!-- <string-field value="true" name="disown"/> -->
<string-field value="true" name="own"/>
<!-- END RESERVED FIELDS SECTION -->

<!-- BEGIN CMA FIELDS SECTION -->
<!-- All of the fields that follow will be added as CMA fields                 <!-- in OVO -->
<!-- CMA field names do not have to be predefined in OVO -->

<!-- To add a CMA field, copy the following line and set the                 <!-- name and value attributes -->
<!-- Set the name attribute to the name of the CMA field                 <!-- to add -->
<!-- Set the value attribute to the value to assign                 <!-- the CMA field -->
<!--
<string-field value="" name=""/>
-->
<!-- END CMA FIELDS SECTION -->

</extended-fields>

- After Changes
The code below shows the Extended Fields section in the file after the changes. The changes are shown in bold italics.

<extended-fields>
<!-- The extended fields section contains any fields that are not           <!--  defined in the event model -->

<!-- BEGIN RESERVED FIELDS SECTION -->
<!-- The fields defined in this section are reserved and have                 <!-- special meaning -->

<!-- The application field is mapped to the OVO Application                 <!--  field -->
<string-field value=”Oracle Enterprise Manager”                  name="application"/>

<!-- The ovo_ts_field node must always be set to NONE -->
<string-field value="NONE" name="ovo_ts_field"/>

<!-- The following extended field is used to disown the alert in                 <!-- OVO after it is created -->
<!-- By default, the ovo user account used to create the alert                 <!-- will be left as the owner -->
<!-- To force it to disown it after it is created, uncomment the                <!--  following line and comment out the next -->line
<!-- out the next line -->
<!-- <string-field value="true" name="disown"/> -->
<string-field value="true" name="own"/>
<!-- END RESERVED FIELDS SECTION -->

<!-- BEGIN CMA FIELDS SECTION -->
<!-- All of the fields that follow will be added as CMA fields                 <!--  in OVO -->
<!-- CMA field names do not have to be predefined in OVO -->

<!-- To add a CMA field, copy the following line and set the                 <!-- name and value attributes -->
<!-- Set the name attribute to the name of the CMA field                 <!-- to add -->
<!-- Set the value attribute to the value to assign                 <!-- the CMA field -->
<!--
<string-field value="" name=""/>
-->
<string-field name="TargetType">
<xsl:attribute name="value">
<xsl:value-of select="a:TargetType"/>
</xsl:attribute>
</string-field>
<!-- END CMA FIELDS SECTION -->

</extended-fields>

5. Save your changes after making the updates.

6. Open the updateEvent_request.xsl file and make the same changes. In this case, you cannot just cut and paste the Extended Fields section, because there are some differences between the create and update translations. You will need to edit them separately.

7. Save your changes after making the updates.

Changing Default Port Numbers

In most cases, you can use the default port numbers that the HP OpenView Operations web service uses. However, if there are any conflicts with existing applications, you need to change the port numbers.

The following sections provide procedures on how to change these default port numbers.

Changing Port Number 9099

9099 is the default port number that the HP OpenView Operations server system uses internally. To change this port number, perform the following steps on the server where you installed the OVOU Agent.

Replace <OVOA_INSTALL> with the directory where the HP OpenView Operations Agent is installed.

1. Open a command prompt window and change the working directory to:
<OVOA_INSTALL>/ovo-agent/scripts

2. Enter the following command to stop the HP OpenView Operations Agent:
./stopallbb

You must specify the user name and password for the account that is authorized to stop the Oracle OVO Agent. See Section 2.2, "Installing and Running the HP OpenView Operations Agent" on page 2-2 for information about the account that is authorized to stop the Oracle OVO Agent.

3. Make a backup copy of the following file:
<OVOA_INSTALL>/ovo-agent/bin/sdserverbb.ini

4. Open the file above in a text editor.

5. Search for the line containing the string ManagementPort=9099.

6. Change 9099 to the new port number.

7. Save the file and exit.

8. Open the following file in a text editor:
<OVOA_INSTALL>/ovo-agent/scripts/setenvbb

9. Search for the line containing the string export IW_MGMTPORT=9099.

10. Change 9099 to the new port number.

11. Enter the following command to start the HP OpenView Operations Agent.
./startallbb

The Oracle OVO Agent will pick up the configuration changes and use the new port number.

Changing Port Number 9007

9007 is the default port number used for communication between the HP OpenView Operations Agent and the HP OpenView Operations web service. To change this port number, perform the following steps at the HP OpenView Operations server system.

Replace <OVOA_INSTALL> with the directory where the HP OpenView Operations Agent is installed.

1. Open a command prompt window and change the working directory to:
<OVOA_INSTALL>/ovo-agent/scripts

2. Enter the following command to stop the HP OpenView Operations Agent. You will be prompted for the credentials to stop the Oracle OVO Agent.
./stopallbb

You must specify the user name and password for the account that is authorized to stop the Oracle OVO Agent. See Section 2.2, "Installing and Running the HP OpenView Operations Agent" for information about the account that is authorized to stop the Oracle OVO Agent.

3. Make a backup copy of the following file:
<OVOA_INSTALL>/ovo-agent/bin/sdserverbb.ini

4. Open the file above in a text editor.

5. Search for the line containing the AGENTADDR= string.

6. Change 9007 to the new port number.

7. Save the file and exit.

8. Enter the following command to start the HP OpenView Operations Agent.
./startallbb

The Oracle OVO Agent will pick up the configuration changes and use the new port number.

Perform the following steps at the system where the HP OpenView Operations web services are installed. Replace <OVOWS_INSTALL> with the directory where the HP OpenView Operations web services are installed.

1. Open a command prompt window and change the working directory to:
<OVOWS_INSTALL>/iwave-af-1.1.1/conf

2. Enter the following command to configure the web service to connect to the HP OpenView Operations Agent ...
../bin/propertiesEditor.bat -p hpovou.xmlagent=<prot>://<OVOserver>:<newPort> spring.properties

... where <prot> is the protocol (HTTP or HTTPS), <OVOserver> is the host name or IP address of the HP OpenView Operations server, and <newPort> is the new port number.

The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for UNIX platforms is propertiesEditor.sh.

3. Change the working directory to ../bin.

4. If the web service is installed on a UNIX system, enter the following command to restart the HP OpenView Operations web service:
./service.sh restart

5. If the web service is installed on a Windows system, press Ctrl-C in the window where the adapter was running and run the following command to restart the HP OpenView Operations web service:
startAdapters.bat

Changing Port Number 8080/8443

8080 is the default port number for HTTP communication, and 8443 is the default port for HTTPS communication. To change the port number, perform the following steps on the system where the Oracle OVO Agent is installed.

Replace <OVOA_INSTALL> with the directory where the HP OpenView Operations Agent is installed.

1. Open a command prompt window and change the working directory to:
<OVOA_INSTALL>/ovo-agent/scripts

2. Enter the following command to stop the HP OpenView Operations Agent. You will be prompted for the credentials to stop the Oracle OVO Agent.
./stopallbb

You must specify the user name and password for the account that is authorized to stop the Oracle OVO Agent. See Section 2.2, "Installing and Running the HP OpenView Operations Agent" on page 2-2 for information about the account that is authorized to stop the Oracle OVO Agent.

3. Make a backup copy of the following file:
<OVOA_INSTALL>/ovo-agent/bin/sdserverbb.ini

4. Open the file above in a text editor.

5. Search for and replace the old port number with the new port number. If the old port number is 8443, you will not find any references to the old port number.

6. Save the file and exit.

7. Enter the following command to start the HP OpenView Operations Agent.
./startallbb

The Oracle OVO Agent will pick up the configuration changes and use the new port number.

Perform the following steps at the system where the HP OpenView Operations web services are installed. Replace <OVOWS_INSTALL> with the directory where the HP OVOU web services are installed.

1. Open a command prompt window and change the working directory to:
<OVOWS_INSTALL>/iwave-af-1.1.1/conf

2. Enter the following command to configure the web service to connect to the HP OpenView Operations Agent ...
../bin/propertiesEditor.bat -p services.url=<prot>://<hostname>:<newPort>/services spring.properties

... where <prot> is the protocol (HTTP or HTTPS), <hostname> is the host name or IP address of the HP OpenView Operations server, and <newPort> is the new port number.

The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for UNIX platforms is propertiesEditor.sh.

3. Make a back-up copy of the spring.properties file.

4. Open the spring.properties file with a text editor and replace all references to the old port number the new port number, then save the file.

5. Change the working directory to ../bin.

6. Enter the following command to restart the HP OpenView Operations web service:

- If the web service is installed on a UNIX system:
./service.sh restart

- If the web service is installed on a Windows system, press Ctrl-C in the window where the adapter was running, then run:
startAdapters.bat

Perform the following steps to change the URL being used by the OVOU connector:

1. 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.

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 HP OVOU Connector. This invokes edit mode, enabling you to configure the connector.

5. Change the URLs listed in the Web Service End Points section to use the new port number.

6. Click OK to save your changes.

5 Troubleshooting the Connector

The Oracle Enterprise Manager Connector Framework requires a web service interface for exchanging event information with OVO. Since OVO does not come with a web services front end, an Oracle-provided web service front end must be installed before Oracle Enterprise Manager can exchange event information with OVO. Additionally, a back-end Agent must also be installed on the same system as the OVO server.

This chapter provides information to assist in troubleshooting integration issues with HP OVOU. The chapter focuses on troubleshooting issues in the web service front-end and the back-end Agent.

This chapter discusses the following topics:

- Preparing for Troubleshooting

- Using the Correct URL for OVO Web Service Operations

- Diagnosing Problems with Message Generation and Updates

- Resolving Alerts from Oracle Enterprise Manager

- Resolving Messages from OVO

Preparing for Troubleshooting

In order to troubleshoot integration issues, you must adjust the Oracle Enterprise Manager logging options to capture additional information.

To enable debug logging information for 10.2.0.5:

1. Edit the emomslogging.properties file using a text editor. The file is located in the following directory ...
<ORACLE_HOME>/oms10g/sysman/config

... where <ORACLE_HOME> is the Oracle install directory.

2. Set the parameters as follows:
log4j.appender.emlogAppender.Threshold = DEBUG log4j.rootCategory=DEBUG, emlogAppender, emtrcAppender

3. After setting the debug logging parameters, restart OMS by opening a command window, changing the working directory to <ORACLE_HOME>/oms10g/bin, and issuing the following commands:
emctl stop oms emctl start oms

To enable debug logging information for 11.1.0.1, see "Controlling the Contents of the Oracle Management Service Trace File," in Oracle Enterprise Manager Administration 11g Release 1 (11.1.0.1).

Using the Correct URL for OVO Web Service Operations

Perform the following steps to identify and configure the connector to use the correct URL for OVO Web Service operations.

1. Open a command terminal on the system where the OVO web service is installed.

2. Change the working directory to the iwave-af-1.1.1/log directory in the OVO web service installation directory.

3. Open the framework.log file in a text editor.

4. Go to the bottom of the file and search backwards for the string “Setting the server's publish address to be”. Continue searching backwards until the URL that contains AcquisitionService is found. The URL listed there is the URL that should be specified for the getNewAlerts, getUpdatedAlerts, and acknowledgeAlerts operations.

5. Go to the bottom of the file and search backwards for the string “Setting the server's publish address to be”. Continue searching backwards until the URL that contains EventService is found. The URL listed here is the URL that should be specified for the createEvent and updateEvent operations.

6. 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.

7. Click the Setup link at the top right part of the window. The Overview of Setup page appears.

8. Click the Management Connectors link on the left side of the window. The Management Connectors page appears, which shows the installed connectors.

9. Click on the Configure icon associated with the HP OVOU Connector. This invokes edit mode, enabling you to configure the connector.

10. Verify that the URL identified in step 4 is specified for the getNewAlerts, getUpdatedAlerts, and acknowledgeAlerts operations.

11. Verify that the URL identified in step 5 is specified for the createEvent and updateEvent operations.

12. If any of the operations are incorrect, change to the correct URL and click OK.

Diagnosing Problems with Message Generation and Updates

You might encounter issues involved in generating or updating messages in OVO from alerts that have originated in Oracle Enterprise Manager or vice versa. The following sections provide diagnostic information to resolve these problems.

Alerts from Oracle Enterprise Manager to OVOU

OVO can generate or update messages from alerts that have originated in Oracle Enterprise Manager. Perform the following diagnostic steps if OVO messages are not being generated or updated as expected.

1. Verify that a notification rule is set up for the condition that triggered the alert. Perform the following steps to verify that it is setup correctly:

1. Open an Oracle Enterprise Manager console window and log in.

2. Click on the Setup link in the upper right corner of the Oracle Enterprise Manager console.

3. Click on the Notification Methods link on the left side of the window.

4. Locate the HP OVOU Connector in the table near the bottom of the window and click on it to list and note the notification rules that use this method.

5. Click on the Preferences link in the upper right corner.

6. Click on the Notification Rules link on the left side of the window. This displays a list of all defined notification methods.

7. Examine the details for the rules listed in step d above and verify that at least one rule matches the conditions that triggered the alert.

8. If you did not find at least one rule, you need to modify an existing notification rule or add a new one to invoke the OVO notification method.

2. Determine the error that Oracle Enterprise Manager has reported.

1. Navigate to the page that displays the alert information that should have triggered the new message in OVO.
For example, if the Memory Utilization % metric was set up to invoke the HP OVOU Connector method, you would perform the following steps to access the page that displays alert information. This example assumes that the generated alert was critical.

1.) Click on the Alerts tab.

2.) Click on the Critical sub-tab.

3.) Click on the Memory Utilization % alert.

2. Click on the details and look for any error messages.
After the alert is generated, it initially indicates that the method will be invoked, but no error messages appear. The Enterprise Manager Connector Framework makes several attempts to transfer the alert information to the OVO web service. After all attempts have failed, an error message is usually added to the details for the alert. If there are no errors after several minutes, it is likely that no error messages will be added to the log.

3. If there is no error information in the alert details, 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 location of the file depends on the Enterprise Manager version.

For 11.1.0.1, the file is located at:

<EM_INSTANCE_BASE>/em/<OMS_NAME>/sysman/log/

where <EM_INSTANCE_BASE> is the OMS Instance Base directory. By default, the OMS Instance Base directory is gc_inst, which is present under the parent directory of the Oracle Middleware Home.

For 10.2.0.5, the file is located at:

$OMS_HOME/sysman/log

2.) Go to the bottom of the file and search backwards for this string:

ERROR core.EMEventConnectorServiceImpl createEvent

The error message is contained in the Exception information.

3. Diagnose the problem based on the error message. See Section 5.4, "Resolving Alerts from Oracle Enterprise Manager" for information on troubleshooting common error messages.

Messages from OVO to Oracle Enterprise Manager

Oracle Enterprise Manager can generate or update alerts resulting from messages that have originated in OVO. Perform the following diagnostic steps if Oracle Enterprise Manager alerts are not being generated or updated as expected.

1. Open the emoms.trc file in a text editor. The file is located here:

<EM_INSTANCE_BASE>/em/<OMS_NAME>/sysman/log/

where <EM_INSTANCE_BASE> is the OMS Instance Base directory. By default, the OMS Instance Base directory is gc_inst, which is present under the parent directory of the Oracle Middleware Home.

2. Go to the bottom of the file perform a backwards search for getNewAlerts().
Any instances you find are immediately followed by exception information that identifies the cause of the failure.

See Section 5.5, "Resolving Messages from OVO" for the error message you found in the log file. Each message entry explains the cause of the problem and the steps required to correct the problem.

Resolving Alerts from Oracle Enterprise Manager

This section provides cause and solution information on troubleshooting common alert messages. Find the error message in Table 5–1 that matches your alert message, then refer to the corresponding section(s) indicated under Possible Cause for instructions on diagnosing and correcting the problem.

Table 5-1 Enterprise Manager Alert Messages

Alert Message

Possible Cause

Applicable Versions

targetException=oracle.xml.parser.v2.XMLParseException: Start of root element expected

Invalid Web Service Credentials

10.2.0.4, 10.2.0.5

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

SSL Not Configured in Enterprise Manager

10.2.0.4, 10.2.0.5

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

Missing certdb.txt File

10.2.0.4, 10.2.0.5

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

OVO Web Service Down

10.2.0.4, 10.2.0.5

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

Invalid XML Format

10.2.0.4, 10.2.0.5

Error occurred while calling Web Service: soap:Serverjava.net.ConnectException: Connection refused (errno:239)

Unable to Connect to Oracle OVO Agent

10.2.0.4, 10.2.0.5

Error occurred while calling Web Service: soap:Servercom.iwave.operations.NonRecoverable OperationsException: Error creating or updating event: SMSAFWU.028.U keyword 'object' is missing

Request Missing Required Field

10.2.0.4, 10.2.0.5

Error opening socket: java.net.UnknownHostException: <hostname>

Unknown Host

10.2.0.4, 10.2.0.5

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

Invalid IP Address or Port Number

10.2.0.4, 10.2.0.5

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

Invalid URL Path

10.2.0.4, 10.2.0.5

The server sent HTTP status code 403: Forbidden

Invalid Web Service Credentials

11.1.0.1

javax.net.ssl.SSLKeyException: [Security:090477]Certificate chain received from <hostname> - <IPAddress> was not trusted causing SSL handshake failure

SSL Not Configured in Enterprise Manager

11.1.0.1

HTTP transport error: java.net.SocketException: Socket Closed

OVO Web Service Down, Invalid IP Address or Port Number

11.1.0.1

java.net.ConnectException: Connection refused (errno:239)

Unable to Connect to Oracle OVO Agent

11.1.0.1

com.iwave.operations.NonRecoverableOperationsException: Error creating or updating event: SMSAFWU.028.U keyword 'object' is missing

Request Missing Required Field

11.1.0.1

HTTP transport error: java.net.UnknownHostException: <hostname>

Unknown Host

11.1.0.1

The server sent HTTP status code 404: Not Found

Invalid URL Path

11.1.0.1

Invalid Web Service Credentials

Cause

The user name or password for accessing the OVO web service is incorrect.

Solution

1. 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.

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 OVOU Connector.

5. Click the General tab.

6. Correct the OVOU Web Service Username and OVOU Web Service Password fields and click OK.

SSL Not Configured in Enterprise Manager

Cause

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

Solution

Import the SSL certificate from the OVO web service into the wallet manager. See Section 2.3.3, "Adding Signed Certificates to Enterprise Manager" for details on setting up Oracle Enterprise Manager with the OVO SSL certificate.

Missing certdb.txt File

Cause

The OVO web service is configured to use SSL, but the certdb.txt file that contains the SSL information is missing.

Solution

Import the SSL certificate from the OVO web service into the wallet manager. See Section 2.3.3, "Adding Signed Certificates to Enterprise Manager" on page 2-8 for details on setting up Oracle Enterprise Manager with the OVO SSL certificate.

OVO Web Service Down

Cause

The OVO web service is down.

Solution

Perform the following steps to check the status of the web service and start it if necessary.

If the OVO web service is installed on a Unix system:

1. Open a command terminal on the system where the OVO web service is installed.

2. Change the working directory to the iwave-af-1.1.1/bin directory in the OVO web service installation directory.

3. Enter the following command:
./service.sh status

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

If the OVO web service is installed on a Windows system:

1. Open a command terminal on the system where the OVO web service is installed.

2. Change the working directory to the iwave-af-1.1.1/log directory in the OVO web service installation directory.

3. Open the framework.log file in a text editor.

4. 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.

5. If the web service is not started, change the working directory to the iwave-af-1.1.1/bin directory and run the startAdapters.bat command file.

Invalid XML Format

Cause

The request sent to the OVO web service was rejected because the XML was formatted incorrectly. This problem should not occur unless the connector configuration XML files are manually updated.

Solution

Look at the error message in the faultstring node of the SOAP fault response and determine what is incorrect in the request document. Examine any changes made to the XML configuration files for mistakes that could have caused the problem. You can determine the correct XML format by accessing the WSDL using a web browser.

Perform the following steps to access the WSDL:

1. 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.

2. Click the Setup link at the top right portion 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 HP OVOU Connector.

5. Click the General tab.

6. Select and copy the URL specified for the getNewAlerts operation.

7. Open an internet browser on the system where the Oracle Enterprise Manager server is installed.

8. 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]:8080/services/hpovou/EventService?wsdl

[Hostname] is the actual host name or IP address where the OVO web service is installed.

If you cannot determine why the format is incorrect, contact Oracle support.

Unable to Connect to Oracle OVO Agent

Cause

The OVO web service could not connect to the Oracle OVO Agent. Some of the causes could be:

- The Oracle OVO Agent is down.

- A configuration error in the Oracle OVO Agent or web service is preventing communication.

Solution

Perform the following steps to verify that the Oracle OVO Agent is operational:

1. Open a command prompt at the system where the OVO server is installed.

2. Enter the following command to determine if the Agent process is running:
ps –ef | grep sdserverbb | grep –v grep

If no processes are listed, the Oracle OVO Agent is down.

3. To start the Agent, first change the working directory to ...
<OVAG_INST>/ovo-agent/scripts

... where <OVAG_INST> is the Oracle OVO Agent install directory

4. Enter the following command to start the Agent:
./startallbb

Perform the following steps to verify that the configuration is correct:

1. Open a command prompt window at the OVO server system and change the working directory to ...
<OVOA_INSTALL>/ovo-agent/scripts

... where <OVOA_INSTALL> is the directory where the Oracle OVO Agent is installed.

2. Open the <OVOA_INSTALL>/ovo-agent/bin/sdserverbb.ini file in a text editor.

3. Search for the line containing the string AGENTADDR=.
This parameter defines the hostname/IP address and port number that the Oracle OVO Agent uses when listening for requests from the OVO web service. Make a note of these values.

4. Open a command prompt window at the system where the OVO web service is installed, and change the working directory to ...
<OVOWS_INSTALL>/iwave-af-1.1.1/conf

... where <OVOWS_INSTALL> is the directory where the OVO web service is installed

5. Open the spring.properties file in a text editor.

6. Search for the hpovou.xmlagent parameter. The format of the parameter is:
http\://<hostname>\:<port>

7. Verify that the hostname/IP address and the port number specified in this file match the information from step 3.

8. If the information does not match, perform the following steps to change the parameter to use the correct hostname/IP address and port number, then restart the web service.

1. At the command prompt window of the system where the OVO web service is installed, enter the following command ...
../bin/propertiesEditor.bat -p hpovou.xmlagent=<prot>://<OVOserver>:<newPort> spring.properties

... where <prot> is the protocol (HTTP or HTTPS), <host> is the correct host name or IP address, and <port> is the correct port number.

The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for UNIX platforms is propertiesEditor.sh.

2. Change the working directory to ../bin.

3. Enter one of the following commands to restart the OVO web service, depending on whether the web service is installed on a Unix system or Windows system.
— For UNIX, enter:

./service.sh restart

— For Windows:

Press Ctrl-C in the window where the adapter was running, then run:

startAdapters.bat

Request Missing Required Field

Cause

The Oracle OVO Agent could not process the request because key information was missing. This error should not occur if you are using the default configuration. It only occurs if the default mappings were modified and a required field was omitted.

Solution

You need to modify the XSL file to generate the XML node that maps to the missing OVO field. See Appendix A, "Default Mappings" for information on customizing the default mappings.

Unknown Host

Cause

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

Solution

You have the following options for addressing 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 OVO web service 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 HP OVOU 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.

Invalid IP Address or Port Number

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:

1. 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.

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 HP OVOU Connector. This invokes edit mode, enabling you to configure the connector.

5. Verify that the hostname/IP address and port number specified in the URL for the createEvent and updateEvent operations are correct.

6. If the hostname/IP address and port number are incorrect, provide the correct values and click OK.

If the URLs specify a host name, make 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 hostname/IP address appears to be correct, try to ping the system where the OVO web service is installed using the hostname/IP address. If the ping fails, the system administrator needs to investigate why there is no connectivity.

Invalid URL Path

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.

1. 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.

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 HP OVOU Connector.

5. Click the General tab.

6. Select and copy the URL specified for the createEvent operation.

7. Open an internet browser on the system where the Oracle Enterprise Manager server is installed.

8. 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]:8080/services/hpovou/EventService?wsdl

[Hostname] is the actual host name or IP address where the OVO web service 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 Section 5.2, "Using the Correct URL for OVO Web Service Operations" to configure the connector to use the correct URL.

Resolving Messages from OVO

This section provides cause and solution information on troubleshooting common messages from OVO. Find the error message in Table 5–2 that matches your error message, then refer to the corresponding section(s) indicated under Possible Cause for instructions on diagnosing and correcting the problem.

Table 5-2 OVO Error Messages

Error Message

Possible Cause

Applicable Versions

targetException=oracle.xml.parser.v2.XMLParseException: Start of root element expected.

Invalid Web Service Credentials

10.2.0.4, 10.2.0.5

SOAPException: faultCode=SOAP-ENV:IOException; msg=javax.net.ssl.SSLException: SSL handshake failed: X509CertChainInvalidErr

SSL Not Configured in Enterprise Manager

10.2.0.4, 10.2.0.5

SOAPException: faultCode=SOAP-ENV:IOException; msg=The wallet &quot;/gc/OracleHomes/oms10g/sysman/connector//certdb.txt&quot; does not exist

Missing certdb.txt File

10.2.0.4, 10.2.0.5

SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: java.net.ConnectException: Connection refused;

OVO Web Service Down, Invalid Port Number

10.2.0.4, 10.2.0.5

SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: java.net.UnknownHostException: <hostname>;

Unknown Host

10.2.0.4, 10.2.0.5

SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: java.net.NoRouteToHostException: No route to host;

Invalid IP Address

10.2.0.4, 10.2.0.5

SOAPException: faultCode=SOAP-ENV:Protocol; msg=Unsupported response content type

Invalid URL Path

10.2.0.4, 10.2.0.5

The server sent HTTP status code 403: Forbidden

Unknown Host

10.2.0.4, 10.2.0.5

Certificate chain received from <hostname> - <IPAddress> was not trusted causing SSL handshake failure.

SSL Not Configured in Enterprise Manager

11.1.0.1

Tried all: 1 addresses, but could not connect over HTTPS to server: <IPAddress> port: <port>

OVO Web Service Down

11.1.0.1

HTTP transport error: java.net.SocketException: Socket Closed

Invalid Port Number, Invalid IP Address

11.1.0.1

HTTP transport error: java.net.UnknownHostException: <hostname>

Unknown Host

11.1.0.1

The server sent HTTP status code 404: Not Found

Invalid URL Path

11.1.0.1

Invalid Web Service Credentials

Cause

The user name or password for accessing the OVO web service is incorrect.

Solution

1. 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.

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 OVOU Connector.

5. Click the General tab.

6. Correct the OVOU Web Service Username and OVOU Web Service Password fields and click OK.

SSL Not Configured in Enterprise Manager

Cause

The SSL handshake between the Oracle Enterprise Manager Connector Framework and the OVO web service failed. This failure occurs when the SSL certificate in the certificate store does not match the SSL certificate that the OVO web service provides.

Solution

You need to import the SSL certificate from the OVO web service into the certificate store. See Section 2.3.3, "Adding Signed Certificates to Enterprise Manager" for details on setting up Oracle Enterprise Manager with the OVO SSL certificate.

Missing certdb.txt File

Cause

The OVO web service is configured to use SSL, but the certdb.txt file that contains the SSL information is missing.

Solution

You need to import the SSL certificate from the OVO web service into the wallet manager. See Section 2.3.3, "Adding Signed Certificates to Enterprise Manager" on page 2-8 for details on setting up Oracle Enterprise Manager with the OVO SSL certificate

OVO Web Service Down

Cause

The OVO web service is down.

Solution

Perform the following steps to check the status of the web service and start it if necessary.

If the OVO web service is installed on a Unix system:

1. Open a command terminal on the system where the OVO web service is installed.

2. Change the working directory to the iwave-af-1.1.1/bin directory in the OVO web service installation directory.

3. Enter the following command:
./service.sh status

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

If the OVO web service is installed on a Windows system:

1. Open a command terminal on the system where the OVO web service is installed.

2. Change the working directory to the iwave-af-1.1.1/log directory in the OVO web service installation directory.

3. Open the framework.log file in a text editor.

4. 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.

5. If the web service is not started, change the working directory to the iwave-af-1.1.1/bin directory and run the startAdapters.bat command file.

Invalid Port Number

Cause

The port number in the URL is incorrect.

Solution

Perform the steps specified in Section 5.2, "Using the Correct URL for OVO Web Service Operations" to identify the correct URL, including the port number.

Unknown Host

Cause

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

Solution

You have the following options for addressing 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 OVO web service 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 HP OVOU 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 getNewAlerts, getUpdatedAlerts, and acknowledgeAlerts operations.

7. Click OK.

Invalid IP Address

Cause

The IP address specified in the URL is invalid, or the network is down.

Solution

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

1. 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.

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 HP OVOU Connector. This invokes edit mode, enabling you to configure the connector.

5. Verify that the hostname/IP address specified in the URL for the getNewAlerts, getUpdatedAlerts, and acknowledgeAlerts operations are correct.

6. If the hostname/IP address are incorrect, provide the correct values and click OK.

If the URLs specify a host name, make 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 hostname/IP address appears to be correct, try to ping the system where the OVO web service is installed using the hostname/IP address. If the ping fails, the system administrator needs to investigate why there is no connectivity.

Invalid URL Path

Cause

The URL hostname/IP address and port numbers are correct, but there is an invalid path.

Solution

Perform the steps specified in Section 5.2, "Using the Correct URL for OVO Web Service Operations" to identify the correct URL, including the port number.

A Default Mappings

This appendix describes the default mappings between the Enterprise Manager alert data fields and the HP OpenView Operations message fields. The data is formatted in XML, and the XSLT files transform the data from one format to another.

For information on customizing the field mappings, see Section 4.1, "Customizing Mappings".

This appendix discusses the following topics:

- Data Translation Files

- createEvent Operation

- updateEvent Operation

- getNewAlerts and getUpdatedAlerts Operations

Data Translation Files

XML Style Sheet (XSL) files contain the mappings between the two systems. These files are located in the following directory:

$ORACLE_HOME/sysman/connector/HP_OVOU_Connector

Table A–1 lists the XSL files that perform the mappings and provides a summary of each.

Table A-1 XSL Files that Perform Mappings

File

Description

createEvent_request.xsl

Transforms the Oracle Enterprise Manager alert data to the HP OpenView Operations message format for the createEvent operation.

updateEvent_request.xsl

Transforms the Oracle Enterprise Manager alert data to the HP OpenView Operations message format for the updateEvent operation.

getNewAlerts_response.xsl

Transforms data in the HP OpenView Operations message format to the Oracle Enterprise Manager alert format. This file is invoked to transform the response for the getNewAlerts poll operation.

getUpdatedAlerts_response.xsl

Transforms data in the HP OpenView Operations message format to the Oracle Enterprise Manager alert format. This file is invoked to transform the response for the getUpdatedAlerts poll operation.

The following sections provide details about the default mappings in each of the files.

createEvent Operation

The Oracle Enterprise Manager Connector Framework invokes the createEvent operation whenever an alert is generated in Oracle Enterprise Manager and there is a notification rule configured to invoke the OVOU connector. createEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to OVOU message format. Table A–2 lists the default field mappings between the HP OpenView Operations message and the Oracle Enterprise Manager alert.

Table A-2 createEvent Operation Mappings

OVO Event Attribute

OVO Attribute Type

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

Message Text

String

Yes

Values from the alert context are listed in angle brackets in the Value column.

Received alert reported by Oracle Enterprise Manager:

Collection Time — <Collection Time>* Key Values — <KeyValues>Message — <Message>Metric Column — <MetricColumn>Metric Name — <MetricName>* Notification Rule — <NotificationRuleName>Target Name — <TargetName>Target Type — <TargetType>Severity — <Severity>* URL — <EventPageURL>

Fields preceded with an asterisk ( * ) are only present if the corresponding Enterprise Manager alert field has data.

Severity

String

Yes

Conditional based on the Oracle Enterprise Manager severity.

Set to Normal if Oracle Enterprise Manager Severity is Information.

Set to Critical if Oracle Enterprise Manager Severity is Critical.

Set to Warning for all other Oracle Enterprise Manager Severity values.

Message Group

String

Yes

Value defaulted.

OracleEnterpriseManager

Object

String

Yes

Set to the target name specified in the Oracle Enterprise Manager alert data.

<TargetName>

Node

String

Yes

Value defaulted.

OracleEnterpriseManager

Application

String

Yes

Set to the target name specified in the Oracle Enterprise Manager alert data.

<TargetType>

updateEvent Operation

The Oracle Enterprise Manager Connector Framework invokes the updateEvent operation whenever an alert is generated in Oracle Enterprise Manager and there is a notification rule configured to invoke the OVOU connector. updateEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to OVOU message format. Table A–3 lists the default field mappings between the HP OpenView Operations message and the Oracle Enterprise Manager alert.

Table A-3 updateEvent Operation Mappings

OVO Event Attribute

OVO Attribute Type

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

Message text

String

Yes

Values from the alert context are listed in angle brackets in the Value column.

Received alert reported by Oracle Enterprise Manager:

Collection Time — <Collection Time>* Key Values — <KeyValues>Message — <Message>Metric Column — <MetricColumn>Metric Name — <MetricName>* Notification Rule — <NotificationRuleName>Target Name — <TargetName>Target Type — <TargetType>Severity — <Severity>* URL — <EventPageURL>

Fields preceded with an asterisk ( * ) are only present if the corresponding Enterprise Manager alert field has data.

Severity

String

Yes

Conditional based on the Oracle Enterprise Manager severity.

Set to Normal if Oracle Enterprise Manager Severity is Information.

Set to Critical if Oracle Enterprise Manager Severity is Critical.

Set to Warning for all other Oracle Enterprise Manager Severity values.

Message Group

String

Yes

Value defaulted.

OracleEnterpriseManager

Object

String

Yes

Set to the target name specified in the Oracle Enterprise Manager alert data.

<TargetName>

Node

String

Yes

Value defaulted.

OracleEnterpriseManager

Application

String

Yes

Set to the target name specified in the Oracle Enterprise Manager alert data.

<TargetType>

getNewAlerts and getUpdatedAlerts Operations

The Oracle Enterprise Manager Connector Framework invokes the getNewAlerts operation on the poll cycle interval configured for the OVOU connector. One step in the operation is to send a request to the HP OpenView Operations web service for new alerts in HP OpenView Operations. When the response comes back, the getNewAlerts_response.xsl file is invoked to transform the HP OpenView Operations message data to the format required to create a new alert in Oracle Enterprise Manager.

After the getNewAlerts operation is complete, the Enterprise Manager Connector Framework performs the getUpdatedAlerts operation. Like the getNewAlerts operation, it sends a request to the HP OpenView Operations web service for updated alerts. When the response comes back, the getUpdatedAlerts_response.xsl file is invoked to transform the HP OpenView Operations message data to the format required to update the alert in Oracle Enterprise Manager.

Table A–4 lists the default field mappings between the HP OpenView Operations message and the Oracle Enterprise Manager alert. These mappings are applicable to new and updated alerts, and must always be the same.

Table A-4 getNewAlerts and getUpdatedAlerts Operation Mappings

Oracle Enterprise Manager Event Attribute

OVO Attribute Type

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

key1

String

Yes

Set to the HP OpenView Operations message identifier.

<Identifier>

message

String

Yes

Values from the alert context are listed in angle brackets in the Value column.

Severity — <Severity>Message Group — <MessageGroup>Node — <Node>Object — <Object>Application — <Application>Service Name — <ServiceName>Message Key — <MessageKey>

comment

String

Yes

Set to message text.

<MessageText>

producerID

String

No

Value defaulted.

OVOU

targetName

String

Yes

Set to the node that reported the problem.

<Node>

TargetType

String

No

Value defaulted.

ovou_managed_node

username

String

No

Value defaulted to no value.

password

String

No

Value default to no value.

metricName

String

Yes

Set to the message group the alert belongs to.

<MessageGroup>

category

String

Yes

Set to the message group.

<MessageGroup>

value

String

Yes

Set to the transaction identifier. This is not part of the message data. It is provided by the web service for tracking transactions.

<transactionID>

severity

String

Yes

Conditional based on the HP OpenView Operations severity and on the ResolvedBy field.

Set to Clear if the ResolvedBy field is not empty.

Set to Informational if the ResolvedBy field is empty and the HP OpenView Operations Severity is Normal.

Set to Critical if the ResolvedBy field is empty and the HP OpenView Operations Severity is Major or Critical.

Set to Warning if the ResolvedBy field is empty and any other HP OpenView Operations Severity value is specified.

Index

A  B  C  D  E  F  G  H  I  M  N  O  P  R  S  T  U  V  W  X

A

acknowledging a message in OVOU, 1.1.1

adding new Unix connector, 2.4

Agent

configuring, 2.2.1

starting, 2.2.2

unzipping, 2.2.1

alert message, example of, 1.1.1, 1.1.1

alerts

to OVOU messages, Enterprise Manager and, 1.1.1

viewing, 3.4.3

B

back-end OVO Agent, 2.2.1

C

certificate authority, 2.3.2.2

configuring

connector General page, 3.1

connector Targets page, 3.2

OVO Agent, 2.2.1

connector

features, 1.1

general settings, picture of, 3.1

target settings, picture of, 3.2

D

default port numbers, changing, 4.2

E

emctl parameters

HP OpenView Connector, 2.4

encrypting data, 2.3.2.2

Enterprise Manager

alerts to OVOU messages, 1.1.1

alerts, XML format of, 4.1.2

Connector Framework (EMCF), A.2

event polling OVOU, 1.1.2

installing the connector in, 2.4

versions supported by connector, 1.2

viewing alerts, 3.4.3

event polling to OVOU, Enterprise Manager and, 1.1.2

extended fields

reserved extended field names, 4.1.1.2

XML path mappings, 4.1.1.2, 4.1.1.2

extracting installation files, 2.2.1

F

features of the connector, 1.1

G

General page settings

operation descriptions, 3.1

URL types, 3.1

gunzip utility, 1.3, 1.3

H

HP OpenView Connector

emctl parameters, 2.4

HP OpenView Operations Connector, 2.2

adding new Unix connector, 2.4

Agent, 2.2, 2.2

configuring General page, 3.1

configuring Targets page, 3.2

features, 1.1

installing the connector, 2.4

installing web service, 2.3

prerequisites, 1.3

Wallet Manager, 2.3.3

HP OVO

connector general settings, picture of, 3.1

connector target settings, picture of, 3.2

connector, testing, 3.3

HP OVOU message, example of, 1.1.1

HTTP or HTTPS, choosing, 2.3.1.1

I

installation files, extracting, 2.2.1

installed HP OVOU connector, picture of, 2.4

installing

OVO connector configuration file, 2.3.2.2

SSL certificate, 2.3.2.2

web service, 2.3

M

mappings

between XML format and message field names, 4.1.1.1

changing, 4.1.3

changing, example of, 4.1.3

createEvent operation, A.2

getNewAlerts operation, A.4

getUpdatedAlerts operation, A.4

updateEvent operation, A.3

N

notification rules, 1.1.1

O

OpenView Operations, XML format of, 4.1.1

orapki utility, 2.3.3.1

OVO API, 2.2.1

OVO connector configuration file, installing, 2.3.2.2

P

poll cycle interval configured for connector, A.4

port numbers, changing defaults, 4.2

prerequisites, HP OpenView Operations Connector, 1.3

R

reserved extended field names, 4.1.1.2

running

installation script, web service on Unix, 2.3.1.1

setup script, 2.2.1

S

sample format of HP OpenView Operations messages, 4.1.1

setup script, running, 2.2.1

SSL certificate, installing, 2.3.2.2

starting OVO Agent, 2.2.2

T

target settings, picture of, 3.2

troubleshooting preparation, 5.1

trusted certificate, adding to Wallet Manager, 2.3.3.1

U

Unix

installing web service on, 2.3.1.1

running web service on, 2.3.1.2, 2.3.1.2

unzipping the Agent, 2.2.1

V

viewing alerts, 3.4.3

W

Wallet Manager

adding trusted certificate, 2.3.3.1

HP OpenView Operations Connector, 2.3.3

orapki utility, 2.3.3

viewing content of wallet, 2.3.3.1

web service

installing web service on Unix, 2.3.1.1

installing web service on Windows, 2.3.2.2

running installation script, 2.3.1.1

running web service on, 2.3.1.2

running web service on Unix, 2.3.1.2

running web service on Windows, 2.3.2.3

web service, installing, 2.3

Windows

installing web service on, 2.3.2.2

running web service on, 2.3.2.3

X

XML format

Enterprise Manager alerts, 4.1.2

message field names, mappings between, 4.1.1.1

OpenView Operations messages, 4.1.1

XML Style Sheet (XSL) files, A.1

XSL files that perform mappings, A.1

Copyright © 2011, Oracle and/or its affiliates. All rights reserved.