Oracle Enterprise Manager Installation and Configuration Guide for IBM Tivoli Enterprise Console Connector, Release 1.0.4.1.0

Release 1.0.4.1.0

E14038-05

Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

1 Introduction to the Connector

- Connector Features

- Oracle Enterprise Manager Alerts Transmitted to TEC Events

- Versions Supported

- Prerequisites

2 Installing the Connector

- Installation Platforms

- Installing the IBM TEC Web Service

- Installing and Running the IBM TEC Web Service on Unix

- Installing the Web Service on Unix

- Running the Web Service on Unix

- Testing the Web Service on Unix

- Installing and Running the IBM TEC Web Service on Windows

- Installing the Web Service on Windows

- Running the Web Service on Windows

- Testing the Web Service on Windows

- Adding Signed Certificates to Enterprise Manager

- Adding Signed Certificates to Wallet Manager

- Adding Signed Certificates to cacerts

- Oracle Enterprise Manager Event Polling to TEC

- Installing and Running the IBM TEC Agent

- Installing the Agent

- Running and Stopping the Agent

- Updates to TEC Rules

- Handling Data Flowing from Enterprise Manager to TEC

- Handling Data Flowing from TEC to Enterprise Manager

- Installing the IBM TEC Connector in Oracle Enterprise Manager

3 Configuring the Connector

- Configuring the General Page

- Configuring the Targets Page

- Testing the IBM TEC Connector

- Sending Oracle Enterprise Manager Alerts to IBM TEC

- Creating Notification Rules

- Updating Notification Rules

- Viewing Oracle Enterprise Manager Alerts

- Sending Oracle Enterprise Manager Alerts to IBM TEC

4 Changing Default Configurations

- Customizing Mappings

- XML Format of IBM TEC Events

- Mappings Between XML Format and Event Field Names

- Extended Fields

- XML Format of Oracle Enterprise Manager Alerts

- Changing a Mapping

- Changing Default Port Numbers

5 Troubleshooting the Connector

- Preparing for Troubleshooting

- Using the Correct URL for TEC Web Service Operations

- Diagnosing Problems with Event Generation and Updates

- Alerts from Oracle Enterprise Manager to TEC

- Events from TEC to Oracle Enterprise Manager

- Resolving Alerts from Oracle Enterprise Manager

- Resolving Events from TEC

A Default Mappings

- Data Translation Files

- createEvent Operation

- updateEvent Operation

- getNewAlerts and getUpdatedAlerts Operations

Index

List of Examples

- 4-1 Sample Format for IBM TEC Web Service

- 4-2 XML Format of Alerts

List of Figures

- 1-1 Oracle Enterprise Manager Alert Event

- 1-2 IBM TEC Event

- 2-1 Connector Communication Between Components

- 2-2 Installed TEC Connector

- 3-1 TEC Connector General Settings

- 3-2 TEC Connector Target Settings

List of Tables

- 2-1 Platform Installation Files

- 2-2 emctl Parameters

- 4-1 Event Attributes and XML Path Mappings

- 4-2 Field Descriptions for XML Format

- 5-1 Enterprise Manager Alert Messages

- 5-2 TEC Error Messages

- A-1 XSL Files that Perform Mappings

- A-2 createEvent Operation Mappings

- A-3 updateEvent Operation Mappings

- A-4 getNewAlerts and getUpdatedAlerts Operation Mappings

Oracle® Enterprise Manager

Installation and Configuration Guide for IBM Tivoli Enterprise Console Connector

Release 1.0.4.1.0

E14038-05

May 2011

Oracle Enterprise Manager Installation and Configuration Guide for IBM Tivoli Enterprise Console Connector, Release 1.0.4.1.0

E14038-05

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 IBM Tivoli Enterprise Console (TEC) Connector provides the information that you require to install and configure the IBM Service Manager Connector that integrates Oracle Enterprise Manager with IBM Service Manager management tools and help desk systems.

Audience

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

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 Connectors 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 IBM Tivoli Enterprise Console (TEC) Connector (version 1.0.4.1.0) integrates Oracle Enterprise Manager with IBM TEC through web services, enabling you to exchange event information between the two systems.

Connector Features

The Oracle Management Connector for IBM TEC monitors all of the events forwarded from TEC and automatically updates alert information in the Oracle Enterprise Manager console whenever changes occur in TEC. A similar synchronization of alerts sent from Oracle Enterprise Manager occurs in TEC. 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 TEC, all the state changes in Enterprise Manager are reflected in TEC. However, if you change the state of the alert in TEC, 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 TEC events and polls the TEC web service.

Oracle Enterprise Manager Alerts Transmitted to TEC Events

Conceptually, alerts in Oracle Enterprise Manager are equivalent to events in TEC. Whenever an alert is triggered in Oracle Enterprise Manager, the TEC Connector can automatically create or update an event in TEC. You can use Notification Rules to specify the set of alerts for which events must be created, and the alert severity for which this should happen.

After the connector creates an event in TEC, any subsequent change of the alert severity is propagated to IBM TEC. When the severity of the alert changes to Clear in Oracle Enterprise Manager, the corresponding event is closed in TEC.

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

Figure 1-1 Oracle Enterprise Manager Alert Event

Figure 1–2 shows an example of an IBM TEC event.

Figure 1-2 IBM TEC Event

Versions Supported

This connector supports the following versions of Oracle Enterprise Manager and IBM TEC:

- Oracle Enterprise Manager Grid Control 10g Release 4 with one-off patch 6884527 or later

- IBM Tivoli Enterprise Console versions 3.8 and 3.9

You can install the TEC Agent on the following platforms:

- Microsoft Windows (2000, 2003, XP)

- Sun Solaris (SPARC OS version 5-10)

- IBM AIX (RS/6000 OS version 5.2+)

The base Enterprise Manager version number for the HP Tivoli Enterprise Console Connector Release 1.0.4.1.0 is Enterprise Manager 10g Release 4.

Prerequisites

Before using the IBM TEC connector, ensure that you meet the following prerequisites:

- Oracle Patches are installed. To install patches, do the following:

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

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

- A utility for unzipping .zip files is available on the system hosting IBM TEC.

- Java JRE 6.0 or higher is installed on the system where the TEC Web Service will be installed.

If you want Oracle Enterprise Manager to forward alerts to IBM TEC, you need to create an event class named OracleEnterpriseManager at the IBM TEC server. Sample BAROC and rules files are provided with the installation that you can install manually or with the installation script.

2 Installing the Connector

The Oracle Enterprise Manager Connector Framework requires a web service interface for exchanging event information with IBM TEC. Since TEC does not provide a web services interface, you must install a third-party TEC 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 TEC server. In addition to the TEC web service front-end, you must also install a back-end TEC Agent on the same physical system as the TEC server. The TEC 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 TEC Connector.

Figure 2-1 Connector Communication Between Components

The following sections in this chapter discuss these topics:

- Installation Platforms

- Installing the IBM TEC Web Service

- Installing and Running the IBM TEC Agent

- Updates to TEC Rules

- Installing the IBM TEC Connector in Oracle Enterprise Manager

Installation Platforms

You can install the TEC web service on the following platforms that support Java JRE 1.6:

- Microsoft Windows

- Sun Solaris

- HP-UX

- Linux

You can install the TEC Agent on the following platforms:

- Microsoft Windows (2000, 2003, XP)

- Sun Solaris (SPARC OS version 5-10)

- IBM AIX (RS/6000 OS version 5.2+)

Installing the IBM TEC Web Service

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

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

Installing and Running the IBM TEC 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 tec_connector_bundle.jar from the Oracle Technology Network to the installation directory, then extract the component .jar files.

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

5. Enter the following command to unzip and extract the .tar file:
$JAVA_HOME/bin/jar xvf TEC_webservices_adapter.jar

This creates the adapters directory that contains the installation files.

Note:

If the system where the TEC web service is being installed does not have the JDK installed, you cannot extract the jar file contents. You need to copy the jar file to a system that has the JDK installed and transfer the files after they have been extracted.

6. Enter the following command to change the working directory:
cd adapters/endpoints/tec

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

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

9. When the script prompts for the user name of the web service, enter the user name that must be provided to access the web service, or accept the default of "tec."

10. When the script prompts for the password of the web service, enter the password that must be provided to access the web service, or accept the default of "webservice."

11. When the script prompts for the host name of the IBM TEC server, enter the host name or IP address where the server is installed.

12. When the script prompts for the port number of the IBM TEC server, enter the port number of the TEC reception port if a port mapper is not defined for the server. If a port mapper is defined for the server, specify a port number of 0.

Note:

The TEC reception port is defined by the tec_recv_agent_port parameter in the .tec_config file in the $BINDIR/TME/TEC directory.

13. Copy the API jar files from the TEC installation disk to the adapters/lib/adapters directory. The files you need to copy are log.jar and evd.jar, which are located in the EIFSDK/jars directory of the TEC installation disk.

14. If the web service was configured to run using the HTTPS protocol, you must install a SSL certificate. You can install a self-signed certificate, or you can acquire a certificate from a Certificate Authority (CA).

- To generate and install a self-signed SSL certificate, enter the following commands, and replace <hostname> with the system host name or IP address that the TEC web service will use:
"%JAVA_HOME%\bin\keytool" –delete -alias iwave -keypass iwavepw -storepass iwavepw -keystore keystore.jks

"%JAVA_HOME%\bin\keytool" -genkey -alias iwave -keyalg RSA -keysize 1024 -dname "CN=<hostname>, OU=Development, O=iWave Software, L=Frisco, ST=TX, C=US" -keypass iwavepw -storepass iwavepw -keystore keystore.jks

- To install a certificate that the Certificate Authority issues:

- Request a certificate from a Certificate Authority, such as VeriSign.
In the certificate request, make sure to specify the host name or IP address that the TEC web service will use. 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

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

Running the Web Service on Unix

To run the IBM TEC Web Service framework commands listed with the following tasks, first change the working directory to ...

adapters/bin

... in the installation directory.

- Start — ./service.sh start

- Shut Down — ./service.sh stop

- Restart — ./service.sh restart

- Check Status — ./service.sh status

Testing the Web Service on Unix

Perform the following steps to verify that the IBM TEC Web Service is functional.

1. Open a terminal and change the working directory to the adapters/bin directory in the installation directory.

2. Enter the following command to run the test script:
./testAdapter.sh

3. If the test completes successfully, the last line the utility displays is "Test completed successfully."

Note:

If the HTTPS protocol is being used, the test fails if the installed JRE version is 1.6_10. An issue with this version causes the test to fail. To test the web service, you need to verify that you can load the WSDL in a web browser. See Section 3.3, "Testing the IBM TEC Connector".

Installing and Running the IBM TEC Web Service on Windows

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

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 tec_connector_bundle.jar from the Oracle Technology Network to the installation directory, then extract the component .jar files.

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

5. Enter the following command to unzip and extract the .jar file:
%JAVA_HOME%\bin\jar xvf TEC_webservices_adapter.jar

This creates the adapters directory that contains the installation files.

Note:

If the system where the TEC web service is being installed does not have the JDK installed, you cannot extract the jar file contents. You need to copy the jar file to a system that has the JDK installed and transfer the files after they have been extracted.

6. Enter the following command to change the working directory:
cd adapters\endpoints\tec

7. Enter the following command to run the installation script:
.\install.bat

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

9. When the script prompts for the user name of the web service, enter the user name that must be provided to access the web service, or accept the default of "tec."

10. When the script prompts for the password of the web service, enter the password that must be provided to access the web service, or accept the default of "webservice."

11. When the script prompts for the host name of the IBM TEC server, enter the host name or IP address where the server is installed.

12. When the script prompts for the port number of the IBM TEC server, enter the port number of the TEC reception port. The default value for this port is 5529.

Note:

The TEC reception port is defined by the tec_recv_agent_port parameter in the .tec_config file in the $BINDIR/TME/TEC directory.

13. Copy the API jar files from the TEC installation disk to the adapters\lib\adapters directory. The files you need to copy are log.jar and evd.jar, which are located in the EIFSDK\jars directory of the TEC installation disk.

14. If the web service was configured to run using the HTTPS protocol, you must install a SSL certificate. You can install a self-signed certificate, or you can acquire a certificate from a Certificate Authority (CA).

- To generate and install a self-signed SSL certificate, enter the following commands, and replace <hostname> with the system host name or IP address that the TEC web service will use:
"%JAVA_HOME%\bin\keytool" –delete -alias iwave -keypass iwavepw -storepass iwavepw -keystore keystore.jks

"%JAVA_HOME%\bin\keytool" -genkey -alias iwave -keyalg RSA -keysize 1024 -dname "CN=<hostname>, OU=Development, O=iWave Software, L=Frisco, ST=TX, C=US" -keypass iwavepw -storepass iwavepw -keystore keystore.jks

- To install a certificate that the Certificate Authority issues:

- Request a certificate from a Certificate Authority, such as VeriSign.
In the certificate request, make sure to specify the host name or IP address that the TEC web service will use. 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

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

1. Enter the following command to change the working directory to the bin directory:
cd ..\..\bin

2. Enter the following command to install the web service as a Windows service:
service.bat install

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

If the Microsoft SCOM Web Service was configured to use the HTTPS protocol, the certificate must be imported into Enterprise Manager. See Section 2.2.3, "Adding Signed Certificates to Enterprise Manager" for instructions.

Running the Web Service on Windows

Standalone Service

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

1. Change the working directory to the adapters\bin directory in the installation directory.

2. Run the following command:
startAdapters.bat

To shut down the TEC web service framework, close the window where you started the adapter.

Windows Service

To start the TEC web service framework when set up to run as a Windows service:

net start iWaveAdapters

To shut down the TEC web service framework:

net stop iWaveAdapters

Testing the Web Service on Windows

Perform the following steps to verify that the IBM TEC Web Service is functional.

1. Open a terminal and change the working directory to the adapters/bin directory in the installation directory.

2. Enter the following command to run the test script:
./testAdapter.bat

3. If the test completes successfully, the last line the utility displays is "Test completed successfully."

Note:

If the HTTPS protocol is being used, the test fails if the installed JRE version is 1.6_10. An issue with this version causes the test to fail. To test the web service, you need to verify that you can load the WSDL in a web browser. See Section 3.3, "Testing the IBM TEC Connector".

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 Section 2.2.3.1, "Adding Signed Certificates to Wallet Manager". For versions 11.1.0.1, perform the steps in the Adding Signed Certificates to cacerts section.

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 TEC web service is using:

1. Open a command prompt window and change the working directory to ...
<TECWS_INSTALL>/adapters/conf

... where <TECWS_INSTALL> is the directory where the TEC web service is installed.

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

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

— Windows platforms:

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

3. Transfer the certificate file TECws.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/bin/orapki wallet create -wallet client -auto_login

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

5. To view the content of the wallet, enter the following command:
$OMS_HOME/bin/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.

Note:

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

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 TEC 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 scomws_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

Oracle Enterprise Manager Event Polling to TEC

After installation and configuration, the event connector automatically polls the TEC web service for events to exchange alerts and events 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 (40 * polling interval) new or updated events in TEC. The Oracle Enterprise Manager connector framework processes and acknowledges all of the events provided in the poll response.

Installing and Running the IBM TEC Agent

The following sections provide procedures for installing and running the TEC Agent.

Installing the Agent

The back-end TEC Agent pushes data from TEC into the TEC Web Service. The Agent is comprised of a script (invoked by TEC rules and a command line utility invoked by the script) to send a transaction to the TEC Web Service. The TEC Agent must be installed on the same physical system as the TEC server. The TEC Agent is preconfigured to interface with the TEC Web Service and requires minimal configuration.

To install the TEC Agent, perform the following steps:

1. Download tec_connector_bundle.jar from Oracle Technology Network, extract the components, and put the appropriate installation file into the directory where you intend to install the TEC Agent.

Note:

You need to do this on the IBM TEC system host.

Table 2–1 identifies the installation file name for each supported platform.

Table 2-1 Platform Installation Files

Platform

Installation File

IBM AIX

TECAgentAIX.tar.gz

Sun Solaris

TECAgentSolaris.tar.gz

Microsoft Windows

TECAgentWindows.zip

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

3. Unzip the installation file. This creates the TEC-agent directory that contains the installation files.

- For Windows platforms, use a zip utility to unzip the TECAgentWindows.zip file.

- For AIX platforms, issue the following commands to unzip and untar the files:
gunzip TECAgentAIX.tar.gz

tar xvf TECAgentAIX.tar

- For Solaris platforms, issue the following commands to unzip and untar the files:
gunzip TECAgentSolaris.tar.gz

tar xvf TECAgentSolaris.tar

4. Set up the TEC environment:

- For Windows systems, enter the following commands to start the bash shell:
%SystemRoot%\system32\drivers\etc\Tivoli\setup_env.cmd

bash

- For Unix systems, enter the following command to start the bash shell:
/etc/Tivoli/setup_env.sh

5. Change the working directory to the TEC-agent directory.

6. Enter the following command to run the setup script to configure the TEC Agent:
./install.sh

The following prompts appear in this sequence:

- Enter the hostname or IP address where the TEC adapter is installed [localhost]:
Enter the host name or IP address of the system where the TEC Web Service adapter is installed.

- Do you want to install the default Oracle Enterprise Manager classes and rules [Y]?
Enter Y to install and activate the class definitions and rules for the OracleEnterpriseManager class. This class must be installed before alerts from Enterprise Manager can be inserted into TEC. Enter N to skip the installation of the OracleEnterpriseManager class. The classes must be manually installed if you choose not to install the class definitions.

The following prompts appear in this sequence if you choose to install the OracleEnterpriseManager class.

- Enter the name of the rule base to use:
Enter the name of the rule base where the class should be installed. This can be an existing rule base or one that does not exist.

- Rule base could not be found. Do you want to create it [N]?
This prompt only appears if the rule base specified in the previous response did not already exist. Specify Y to create a new rule base, or specify N to exit the script without installing the OracleEnterpriseManager class.

- Enter the rule base directory:
This prompt only appears if the script cannot determine the directory where the rule base files are located. Enter the directory where the rule base files are located. The script terminates if the directory does not exist.

7. Delete the installation file from the installation directory.

Running and Stopping the Agent

You do not need to start or stop the Agent. A TEC rule invokes it whenever a transaction needs to be sent to the TEC Web Service adapter. The Agent terminates after the transaction has been successfully delivered to the TEC Web Service adapter.

Updates to TEC Rules

TEC rules must initiate event information sent from TEC to the TEC Web Service. This requires changes to the TEC rule sets to invoke the tec2uniagt script, which sends event information to the TEC Web Service. The following sections describe the required changes to the TEC rule sets for data flowing in both directions.

Handling Data Flowing from Enterprise Manager to TEC

For the TEC connector to work out of the box, the Oracle Enterprise Manager default classes must be installed and loaded into the TEC Server. When installing the TEC Agent, you have the option to install the classes and rules.

If you choose to install the default classes, the install script compiles the classes and rules, and loads them into the TEC Server. It also shuts down and restarts the server to pick up the new classes.

If you choose not to install the classes, you must manually install the classes and rules. The default class files are located in the TEC-agent/Samples directory. The OracleEnterpriseManager.baroc file defines the 5 classes that are required to insert events into TEC. The OracleEnterpriseManager.rls file contains the rules required to send the event data back to the TEC Web Service after an event has been created, updated, or closed. To manually install the classes with the install script, perform the following steps.

1. Open a command terminal at the system where the TEC server is installed.

2. Change the working directory to the TEC-agent/Samples directory in the TEC Agent install directory.

3. Set up the TEC environment:

- For Windows systems, enter the following commands to start the bash shell:
%SystemRoot%\system32\drivers\etc\Tivoli\setup_env.cmd

bash

- For Unix systems, enter the following command to start the bash shell:
/etc/Tivoli/setup_env.sh

4. Enter the following command to install the default classes:
./rule_load.sh

Handling Data Flowing from TEC to Enterprise Manager

To send new/updated events from TEC to Enterprise Manager, you need to define one or more rules in TEC to call the tec2uniagt script. The script is named tec2uniagt.sh on Unix systems and it is named tec2uniagt.cmd on Windows systems. This script sends an event to the TEC Web Service and makes the event available for Enterprise Manager to consume.

You need to identify the classes that you want Enterprise Manager to consume. You also need to identify the conditions that should trigger sending an event to the TEC Web Service. An example of conditions would be changing the status or severity of an event. After you identify this information, you need to coordinate with the TEC Administrator to define and install the necessary rules to invoke the tec2uniagt script.

Sample files are provided in the TEC-agent/Samples directory of the TEC Agent install directory. The files are named tec2uniagt_sample.baroc and tec2uniagt_sample.rls. These files provide an example of how to invoke the tec2uniagt script and should not be installed on your TEC Server.

Installing the IBM TEC Connector in Oracle Enterprise Manager

The following procedure explains how to add the new TEC Connector.

Note:

Table 2–2 provides descriptions for the parameters shown for the emctl command in this procedure.

Note:

The commands in this 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.01:

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

For version 10.2.0.4, enter the following command:

$OMS_HOME/bin/emctl extract_jar connector <jarfile> <connector_type_name> <OracleHomes>

Note:

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

Command Example

$OMS_HOME/bin/emctl extract_jar connector -jar $OMS_HOME/sysman/ connector/ibm_tec.jar" –cname "TEC Connector"

When run, this creates a new connector subdirectory called TEC_Connector in the <OracleHomes>…sysman/connector directory.

2. Register the connector by entering the following command based on the 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 <password>

10.2.0.5

$OMS_HOME/bin/emctl register_connector connector -dd "<deployment_file>" -cs //<server>:<port>/<database_sid> -repos_user <username> -repos_pwd <password>

10.2.0.4

$OMS_HOME/bin/emctl register_connector connector “<deployment_file>” <server> <port> <database_sid> <username> <password> “<omshome>”

Command Example

$OMS_HOME/bin/emctl register_connector connector –dd
$OMS_HOME/sysman/connector/TEC_Connector/TECConnector.xml”
-repos_pwd password

The new TEC 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 TEC Connector

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

Table 2-2 emctl Parameters

Parameter

Description

connector_name

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

connector_type_name

Connector type name. Specify "TEC 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 TECConnector.xml file resides in the TEC connector directory $OMS_HOME/sysman/connector/TEC_Connector/.

description

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

internal_name

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

jarfile

Fully-qualified name of the connector jar file. The jar file name is ibm_tec.jar.

omshome

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

oraclehome

Top directory of the OMS installation.

password

Password for SYSMAN.

port

Listener port of the repository.

server

Host name of the Enterprise Manager repository.

template_name

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

template_type

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

template.xml

Fully-qualified name of the connector template file

username

Specify SYSMAN.

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 IBM TEC Connector

- Sending Oracle Enterprise Manager Alerts to IBM TEC

Configuring the General Page

To configure the General page:

1. From the Management Connectors page, select the TEC 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 TEC Connector General Settings

2. Update the URLs for each of the Web Service End Point operations as described below.
Operation Descriptions

The TEC connector uses the following operations (web methods) to exchange data with the TEC Web Service.

- getNewAlerts — Creates alerts in Oracle Enterprise Manager based on events that originate in IBM TEC. Oracle Enterprise Manager uses this operation when polling for events in IBM TEC.

- getUpdatedAlerts — Updates alerts in Oracle Enterprise Manager based on events that originate from IBM TEC. Oracle Enterprise Manager uses this operation when polling for events from IBM TEC.

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

- createEvent — Generates events in IBM TEC based on alerts that originate in Oracle Enterprise Manager. Oracle Enterprise Manager invokes this operation when it forwards a new alert to TEC.

- updateEvent — Updates events in IBM TEC based on alerts that originate in Oracle Enterprise Manager. Oracle Enterprise Manager invokes this operation when it forwards a new alert to TEC.

URL Types

The connector uses two different URLs for operations. One URL polls data out of IBM TEC (getNewAlerts, getUpdatedAlerts and acknowledgeAlerts), and defaults to the following value:

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

The other URL pushes data into IBM TEC (createEvent and updateEvent), and defaults to the following value:

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

You need to make the following changes to each of the default URLs:

- Replace [Hostname] in the URL with the hostname or IP address of the system where the TEC Web Service is installed.

- If necessary, 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 the TEC Web Service was configured to use the HTTPS protocol, change http to https at the beginning of each web service URL.

If you are using HTTPS as the protocol, you must also include the TEC web service certificate in Oracle Wallet Manager as described in Adding Signed Certificates to Enterprise Manager on on page 2-7.

3. Enter the user name and password you specified when you installed the TEC web service, which is discussed in steps 9 and 10 of Section 2.2.1.1 and section steps 9 and 10 of Section 2.2.2.1.
The TEC web service installer prompts for the user name and password that should be supplied when accessing the TEC web service. It provides default values if you do not provide a response.

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 IBM TEC web service for new or updated events 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 IBM TEC event is translated into an Oracle Enterprise Manager alert, the IBM TEC event host name determines the target-type instance associated with the alert in Oracle Enterprise Manager. If a target instance that matches the event host name is not found, the default target instance of generic_tec_host 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 TEC Connector Target Settings

2. Provide a target name. The Target Name field is set to the host name specified in the TEC event and must exactly match the name.

3. Provide the TEC host name in the TEC HOST 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 IBM TEC 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 TEC Connector.

5. Click on the General tab.

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/tec/EventService?wsdl

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

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

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 be similar to the following example:
http://[Hostname]:8080/services/AcquisitionService?wsdl

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

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

Sending Oracle Enterprise Manager Alerts to IBM TEC

Alerts generated or updated in Oracle Enterprise Manager are not transferred to TEC unless you create notification rules to invoke the IBM TEC 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 TEC 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 TEC Connector to assign the TEC 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 TEC 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 TEC Connector to assign the TEC notification method to the notification rule.

5. Click OK to complete the update.

Viewing Oracle Enterprise Manager Alerts

Whenever an event is created in IBM TEC from an alert that originates in Oracle Enterprise Manager, a link is provided in the event text. To view the Oracle Enterprise Manager alert that triggered the event, copy the URL to a web browser. You will be asked to log in to Oracle Enterprise Manager. After logging in, the Oracle Enterprise Manager alert information is displayed.

Sending Oracle Enterprise Manager Alerts to IBM TEC

No special setup is required in Oracle Enterprise Manager to retrieve event information from TEC. Oracle Enterprise Manager automatically starts polling the TEC web service after the connector has been configured.

TEC does not automatically send new and updated events to the TEC web service. You must create and install TEC rules to forward events to the TEC Web Service. See "Handling Data Flowing from TEC to Enterprise Manager" on page 2-11 for information about the TEC rules changes.

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 IBM TEC Events

- 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 IBM TEC Events

Example 4–1 represents the format that the IBM TEC web service expects for creating new events in IBM TEC. The format for update requests is the same, except the root node would be "update" instead of "create."

Example 4-1 Sample Format for IBM TEC Web Service

<iwaveaf:create xmlns:iwaveaf="http://iwavesoftware.com/services/  adapter-framework">
<event>
<description></description>
<status></status>
<severity></severity>
<repeatCount></repeatCount>
<createDate></createDate>
<eventClass>
<name>OracleEnterpriseManager</name>
</eventClass>
<group>
<name>PrimaryServer</name>
</group>
<object>
<computerName></computerName>
<displayName></displayName>
</object>
<source>
<computerName></computerName>
<name>OracleEnterpriseManager</name>
</source>
<extended-fields>
<string-field name="ext_id"></string-field>
<string-field name="sub_source">OracleEnterpriseManager</string-field>
</extended-fields>
</event>
</iwaveaf:create>

Mappings Between XML Format and Event Field Names

Table 4–1 identifies the mappings between the IBM TEC base event slot names and the XML format that the IBM TEC web services uses. The XML document presented to the IBM TEC 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 Event Attributes and XML Path Mappings

IBM TEC Slot Names

XML Path

Class Name

/create/event/eventClass/name

msg

/create/event/description

status

/create/event/status

severity

/create/event/severity

repeat_count

/create/event/repeatCount

date

/create/event/createDate

fqhostname

/create/event/object/displayName

hostname

/create/event/object/computerName

source

/create/event/source/name

origin

/create/event/source/computerName

All other slot names

See "Extended Fields" below.

Extended Fields

Extended fields pass information for slots that are not mapped. An extended field is defined as a <string-field/> element that is a child of the extended-fields node. The name of the slot is specified in the name attribute, and the value of the slot is specified in the value attribute.

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 event in IBM TEC. 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 the 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 IBM TEC.

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

This section explains how to customize the mapping between Enterprise Manager and the IBM TEC web service. The procedure provides the steps required for changing a mapping. Following this procedure, an example is provided that shows how to change the mapping of the target type and target name fields.

1. Study the default mapping and determine the changes you want to make. See Appendix A for details about the default mappings and the files that define the mapping for the different Enterprise Manager operations.

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 IBM TEC events 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 origin slot in the IBM TEC event is set to the Oracle Enterprise Manager target type, and the sub_origin slot is set to the target name. The following example shows how to change the value where the target type and name information is placed in TEC. In this example, the target_type and target_name slots were added to the class definition to contain this information.

The changes made to the default mapping are as follows:

- The origin slot is modified to use a hard-coded value of Oracle Enterprise Manager.

- The sub_origin slot is not set to any value.

- The new target_type slot is set to the Oracle Enterprise Manager target type.

- The new target_name slot is set to the Oracle Enterprise Manager target name.

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 appropriate sections to reflect the new mapping.

- Before Changes
The code below shows the impacted sections in the file before the changes.

<source>  <!-- TEC slot = source -->  <name>OracleEnterpriseManager</name>  <!-- TEC slot = origin -->  <computerName>    <xsl:value-of select="a:TargetType"/>  </computerName></source>…<extended-fields>  <!-- TEC fields that are not mapped to the common object model -->  <string-field name="action_flag">CREATE</string-field>  <string-field name="ext_id">    <xsl:value-of select="a:EventGuid"/>  </string-field>  <string-field name="sub_source">OracleEnterpriseManager</string-field>  <string-field name="sub_origin">    <xsl:value-of select="a:TargetName"/>  </string-field></extended-fields>

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

<source>
<!-- TEC slot = source -->
<name>OracleEnterpriseManager</name>
<!-- TEC slot = origin -->
<computerName>Oracle Enterprise Manager</computerName>
</source>
…
<extended-fields>
<!-- TEC fields that are not mapped to the common object model -->
<string-field name="action_flag">CREATE</string-field>
<string-field name="ext_id">
<xsl:value-of select="a:EventGuid"/>
</string-field>
<string-field name="sub_source">OracleEnterpriseManager</string-field>
<string-field name="target_type">
<xsl:value-of select="a:TargetType"/>
</string-field>
<string-field name="target_name">
<xsl:value-of select="a:TargetName"/>
</string-field>
</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 IBM TEC web service uses. However, if there are any conflicts with existing applications, you need to change the port numbers.

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 IBM TEC web services are installed. Replace <TECWS_INSTALL> with the directory where the IBM TEC web services are installed.

1. Open a command prompt window and change the working directory to:
<TECWS_INSTALL>/adapters/conf

2. Enter the following command to configure the web service to connect to the IBM TEC Agent...

../bin/propertiesEditor.bat -p
services.url=<prot>://localhost:<newPort>/
services framework.properties

... where <prot> is the protocol (HTTPS or HTTPS) 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 backup copy of the framework.properties file.

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

Note:

If the old port number is 8443, you will not find any references to the old port number.

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

6. Enter the following command to restart the IBM TEC 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 as a standalone application, close the window where the adapter was running, then run:
startAdapters.bat

- If the web service is installed on a Windows system as a Windows service, enter the following commands:
net stop iWaveAdapters

net start iWaveAdapters

Perform the following steps to change the URL the TEC 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 TEC 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

This chapter provides information to assist in troubleshooting integration issues with IBM TEC. 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 TEC Web Service Operations

- Diagnosing Problems with Event Generation and Updates

- Resolving Alerts from Oracle Enterprise Manager

- Resolving Events from TEC

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:

1. Edit the emomslogging.properties file using a text editor. The location of the file depends on the Enterprise Manager version.
Version 11.1.0.1

<ORACLE_HOME>/oms11g/sysman/config

Versions 10.2.0.4 and 10.2.0.5

<ORACLE_HOME>/oms10g/sysman/config

... where <ORACLE_HOME> is the Oracle installation 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

Using the Correct URL for TEC Web Service Operations

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

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

2. Change the working directory to the adapters/log directory in the TEC 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 TEC 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. The URL from the log file will specify a host name of localhost. The URL specified for the different operations must specify the IP address or host name of the system where the web service is installed as the host name instead of localhost.

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 Event Generation and Updates

You might encounter issues involved in generating or updating events in TEC 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 TEC

TEC can generate or update events from alerts that have originated in Oracle Enterprise Manager. Perform the following diagnostic steps if TEC events 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 set up 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 TEC 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 TEC 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 event in TEC.
For example, if the Memory Utilization % metric was set up to invoke the TEC 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 events.
After the alert is generated, it initially indicates that the method will be invoked, but no error events appear. The Enterprise Manager Connector Framework makes several attempts to transfer the alert information to the TEC web service. After all attempts have failed, an error event is usually added to the details for the alert. If there are no errors after several minutes, it is likely that no error events 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.

Version 11.1.0.1

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

Versions 10.2.0.4 and 10.2.0.5

$OMS_HOME/sysman/log

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

ERROR core.EMEventConnectorServiceImpl createEvent

The error event is contained in the Exception information.

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

Events from TEC to Oracle Enterprise Manager

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

1. Open the $OMS_HOME/sysman/log/emoms.trc file in a text editor. The location of the file depends on the Enterprise Manager version.
Version 11.1.0.1

<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

Versions 10.2.0.4 and 10.2.0.5

$OMS_HOME/sysman/log

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

See Section 5.5, "Resolving Events from TEC" for the error event you found in the log file. Each event 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 to diagnose and correct 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

TEC Web Service Is Down

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

Error occurred while calling Web Service: soap:ServerAttempt to insert the event into TEC failed

TEC Server Not Operational

10.2.0.4, 10.2.0.5

Error occurred while calling Web Service: soap:ServerTimeout occurred waiting for synchronous response from TEC after inserting an event

TEC Server Timeout

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 IWAVETEC39A - 10.2.1.141 was not trusted causing SSL handshake failure.

SSL Not Configured in Oracle Enterprise Manager

11.1.0.1

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

TEC Web Service is Down, Invalid IP Address or Port Number

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

javax.xml.ws.soap.SOAPFaultException: Attempt to insert the event into TEC failed

TEC Server Not Operational

11.1.0.1

javax.xml.ws.soap.SOAPFaultException: Timeout occurred waiting for synchronous response from TEC after inserting an event

TEC Server Timeout

11.1.0.1

Invalid Web Service Credentials

Cause

The user name or password for accessing the TEC 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 corner 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 TEC Connector.

5. Click the General tab.

6. Correct the TEC Web Service Username and TEC Web Service Password fields, then click OK.

SSL Not Configured in Enterprise Manager

Cause

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

Solution

Import the SSL certificate from the TEC web service into the certificate store. See Section 2.2.3, "Adding Signed Certificates to Enterprise Manager" on page 2-7 for details on setting up Oracle Enterprise Manager with the TEC SSL certificate.

Missing certdb.txt File

Cause

The TEC 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 TEC web service into the wallet manager. See Section 2.2.3, "Adding Signed Certificates to Enterprise Manager" on page 2-7 for details on setting up Oracle Enterprise Manager with the TEC SSL certificate.

TEC Web Service Is Down

Cause

The TEC web service is down.

Solution

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

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

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

2. Change the working directory to the adapters/bin directory in the TEC 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 TEC web service is installed on a Windows system:

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

2. Change the working directory to the adapters/log directory in the TEC 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, start the web service based on how the web service is installed.

- If it is installed as a standalone application, change the working directory to the adapters/bin directory and run the startAdapters.bat command file.

- If it is installed as a Windows service, enter the net start iWaveAdapters command.

Unknown Host

Cause

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

Solution

You can use the following options to address this issue:

- Coordinate with the system administrator to change the system configuration to recognize the host name.

- Specify the IP address in the URL instead of the host name. To do this, perform the following steps:

1. Determine the IP address of the system where the TEC 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 IBM TEC 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 TEC 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 TEC 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.

The location of this 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.

The HTML document 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 TEC 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/tec/EventService?wsdl

[Hostname] is the actual host name or IP address where the TEC 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 TEC Web Service Operations" to configure the connector to use the correct URL.

TEC Server Not Operational

Cause

The web service could not insert the event into TEC because it could not connect to the TEC server. This problem could be caused for one of the following reasons:

- The TEC server is down.

- The TEC server hostname/IP address or port number is not configured correctly for the TEC web service.

- A network outage is preventing the TEC web service from connecting to the TEC server.

Solution

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

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

2. Change the working directory to the adapters/conf directory in the TEC web service installation directory.

3. Edit the framework.properties file with a text editor.

4. Search for the tec.server1.config.t_ServerLocation parameter. This parameter specifies the hostname/IP address to use when connecting to the TEC API server.

5. Verify that the host name or IP address is correct. If the hostname/IP address appears to be correct, try to ping the system where the TEC web service is installed using the hostname/IP address. If the ping fails, the system administrator needs to investigate why there is no connectivity.

6. Search for the tec.server1.config.t_Port parameter. This parameter specifies the port number to use when connecting to the TEC API server.

7. Verify that the port number is correct. If the TEC server is running on a Unix machine with a port mapper, the port number should be set to 0. If the TEC server is running on a Windows system or Unix system without a port mapper, the port number must be set to the TEC reception port.

Note:

The TEC reception port is defined by the tec_recv_agent_port parameter in the .tec_config file in the $BINDIR/TME/TEC directory.

If the hostname/IP address is valid and reachable, and the port number is correct, the TEC server must be down.

8. To check the status of the TEC server, open a command terminal on the system where the TEC server is installed.

9. Set up the TEC environment.

- For Windows systems, enter the following commands to start the bash shell:
%SystemRoot%\system32\drivers\etc\Tivoli\setup_env.cmd

bash

- For Unix systems, enter the following command to set the TEC environment variables:
/etc/Tivoli/setup_env/sh

10. Enter the following command to display the status of the TEC server:
wstatesvr

11. If the TEC server is down, contact your TEC system administrator to start the server.

TEC Server Timeout

Cause

The web service successfully sent the event to the TEC server, but did not receive a response in the time-out period. This problem could be caused for one of the following reasons:

- The TEC server ignored the request because it contained invalid data.

- The TEC rule for the class is incorrectly configured.

Solution

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

1. Open a command terminal on the system where the TEC server is installed.

2. Set up the TEC environment.

- For Windows systems, enter the following commands to start the bash shell:
%SystemRoot%\system32\drivers\etc\Tivoli\setup_env.cmd

bash

- For Unix systems, enter the following command to set the TEC environment variables:
/etc/Tivoli/setup_env.sh

3. Enter the following command to display the most recent entries in the TEC server log:
wtdumprl –o DESC | more

4. Locate the entry for the event that timed out, and verify that the log indicates that it was processed. If an error appears, it explains what is incorrect with the data. You will need to modify the mapping to fix the problem. See Section 4.1.3, "Changing a Mapping" for additional information.

5. If the log indicates that TEC successfully processed the data, you need to verify that the TEC rule base invoked the tec2uniagt script located in the TEC Agent installation directory. Consult with your TEC administrator for information on setting up and viewing the rule logs.

Resolving Events from TEC

This section provides cause and solution information on troubleshooting common alert messages. 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 to diagnos and correct the problem.

Table 5-2 TEC 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

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

Invalid XML Format

10.2.0.4, 10.2.0.5

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

TEC Web Service IsDown, 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

Invalid Web Service Credentials

11.1.0.1

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

SSL Not Configured in Oracle Wallet Manager

11.1.0.1

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

TEC Web Service Is 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 TEC 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 TEC Connector.

5. Click the General tab.

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

SSL Not Configured in Oracle Enterprise Manager

Cause

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

Solution

You need to import the SSL certificate from the TEC web service into the certificate store. See Section 2.2.3, "Adding Signed Certificates to Enterprise Manager" on page 2-7 for details on setting up Oracle Enterprise Manager with the TEC SSL certificate.

Missing certdb.txt File

Cause

The TEC 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 TEC web service into the wallet manager. See Section 2.2.3, "Adding Signed Certificates to Enterprise Manager" on page 2-7 for details on setting up Oracle Enterprise Manager with the TEC SSL certificate.

TEC Web Service is Down

Cause

The TEC web service is down.

Solution

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

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

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

2. Change the working directory to the adapters/bin directory in the TEC 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 TEC web service is installed on a Windows system:

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

2. Change the working directory to the adapters/log directory in the TEC 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, start the web service based on how the web service is installed:

- If it is installed as a standalone application, change the working directory to the adapters/bin directory and run the startAdapters.bat command file.

- If it is installed as a Windows service, enter the net start iWaveAdapters command.

If the web service is not down, there must be a problem with the port number. Perform the steps specified in Section 5.2, "Using the Correct URL for TEC Web Service Operations" to identify the correct URL, including the port number.

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 TEC Web Service Operations" to identify the correct URL, including the port number.

Invalid XML Format

Cause

The request sent to the TEC 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 event in the fault string 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 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 TEC 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/tec/EventService?wsdl

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

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

Unknown Host

Cause

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

Solution

Select one of the following options to address this issue.

- Coordinate with the system administrator to change the system configuration to recognize the host name.

- Specify the IP address in the URL instead of the host name. To do this, perform the following steps:

1. Determine the IP address of the system where the TEC 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 TEC 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 TEC 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 TEC 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 TEC 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 IBM TEC event slots. 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/TEC_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 IBM TEC event format for the createEvent operation.

updateEvent_request.xsl

Transforms the Oracle Enterprise Manager alert data to the IBM TEC event format for the updateEvent operation.

getNewAlerts_response.xsl

Transforms data in the IBM TEC event 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 IBM TEC event 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 TEC connector. createEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to TEC event format. Table A–2 lists the default field mappings between the IBM TEC event and the Oracle Enterprise Manager alert.

Table A-2 createEvent Operation Mappings

TEC Slot

TEC Attribute Type

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

Class Name

String

Yes

Conditional based on the TargetType

Set to Database if Oracle Enterprise Manager target type is database instance or cluster database.

Set to Listener if Oracle Enterprise Manager target type is database listener.

Set to Host if Oracle Enterprise Manager target type is host.

Set to ApplicationServer if Oracle Enterprise Manager target type is Oracle application server.

Set to OracleEnterpriseManager for all other target types.

msg

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>Target Type — <TargetType>Target Name — <TargetName>Metric Name — <MetricName>Metric Column — <MetricColumn>* Key Values — <KeyValues>Severity — <Severity>* Notification Rule — <NotificationRuleName>* URL — <EventPageURL>Message — <Message>

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

status

String

Yes

Value defaulted

OPEN

severity

String

Yes

Conditional based on the Oracle Enterprise Manager severity.

Set to UNKNOWN if Oracle Enterprise Manager Severity is Unknown.

Set to HARMLESS 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.

repeat_count

String

No

Value defaulted.

0

date

String

No

Set to the Collection Time

<CollectionTime>

fqhostname

String

No

Set to the Target Host

<TargetHost>

hostname

String

No

Set to the Target Host

<TargetHost>

source

String

Yes

Value defaulted

OracleEnterpriseManager

origin

String

No

Set to the Target Type

<TargetType>

action_flag

String

No

Value defaulted

CREATE

ext_id

String

Yes

Set to the unique identifier for the Oracle Enterprise Manager Alert

<EventGuid>

sub_source

String

Yes

Value defaulted

OracleEnterpriseManager

sub_origin

String

No

Set to the Target Name

<TargetName>

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 TEC connector. updateEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to TEC event format. Table A–3 lists the default field mappings between the IBM TEC event and the Oracle Enterprise Manager alert.

Table A-3 updateEvent Operation Mappings

TEC Slot

TEC Attribute Type

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

Class Name

String

Yes

Conditional based on the TargetType

Set to Database if Oracle Enterprise Manager target type is database instance or cluster database.

Set to Listener if Oracle Enterprise Manager target type is database listener.

Set to Host if Oracle Enterprise Manager target type is host.

Set to ApplicationServer if Oracle Enterprise Manager target type is Oracle application server.

Set to OracleEnterpriseManager for all other target types.

msg

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>Target Type — <TargetType>Target Name — <TargetName>Metric Name — <MetricName>Metric Column — <MetricColumn>* Key Values — <KeyValues>Severity — <Severity>* Notification Rule — <NotificationRuleName>* URL — <EventPageURL>Message — <Message>

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

status

String

Yes

Value defaulted

OPEN

severity

String

Yes

Conditional based on the Oracle Enterprise Manager severity.

Set to UNKNOWN if Oracle Enterprise Manager Severity is Unknown.

Set to HARMLESS 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.

repeat_count

String

No

Value defaulted.

0

date

String

No

Set to the Collection Time

<CollectionTime>

fqhostname

String

No

Set to the Target Host

<TargetHost>

hostname

String

No

Set to the Target Host

<TargetHost>

source

String

Yes

Value defaulted

OracleEnterpriseManager

origin

String

No

Set to the Target Type

<TargetType>

action_flag

String

No

Conditional based on the Oracle Enterprise Manager severity.

Set to CLOSE if Oracle Enterprise Manager severity is Clear, Unreachable End, Blackout End, or Metric Error End.

Set to UPDATE for all other Oracle Enterprise Manager severity values.

ext_id

String

Yes

Set to the unique identifier for the Oracle Enterprise Manager Alert

<EventGuid>

sub_source

String

Yes

Value defaulted

OracleEnterpriseManager

sub_origin

String

No

Set to the Target Name

<TargetName>

getNewAlerts and getUpdatedAlerts Operations

The Oracle Enterprise Manager Connector Framework invokes the getNewAlerts operation on the poll cycle interval configured for the TEC connector. One step in the operation is to send a request to the IBM TEC web service for new alerts in IBM TEC. When the response comes back, the getNewAlerts_response.xsl file is invoked to transform the IBM TEC event data to the format required to create new alerts 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 IBM TEC web service for updated alerts. When the response comes back, the getUpdatedAlerts_response.xsl file is invoked to transform the IBM TEC event data to the format required to update the alerts in Oracle Enterprise Manager.

Table A–4 lists the default field mappings between the IBM TEC event 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

Attribute Type

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

key1

String

Yes

Set to the IBM TEC event identifier.

<Identifier>

message

String

Yes

Values from the event slot are listed in angle brackets in the Value column.

Identifier — <Identifier>Hostname — <hostname>Source — <source>Object — <Object>* Origin — <origin>Date — <date>

Fields precede with an asterisk ( * ) are only present if the corresponding TEC event slot has data.

comment

String

Yes

Set to message text.

Severity Identifier — <severity>Status — <status>Repeat Count — <repeat_count>Message — <msg>

producerID

String

No

Value defaulted.

TEC

targetName

String

Yes

Set to the host that reported the problem.

<hostname>

TargetType

String

No

Value defaulted.

tec_host

username

String

No

Value defaulted to no value.

password

String

No

Value default to no value.

metricName

String

Yes

Set to the event class name.

<Class Name>

category

String

Yes

Set to the event class name.

<Class Name>

value

String

Yes

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

<transactionID>

severity

String

Yes

Conditional based on the IBM TEC status and severity.

Set to Clear if the TEC status is set to CLOSED.

Set to Informational if the TEC status is not set to CLOSED and the TEC severity is HARMLESS.

Set to Critical if the TEC status is not set to CLOSED and the IBM TEC severity is CRITICAL or FATAL.

Set to Warning if the TEC status is not set to CLOSED and any other TEC 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

adding new Unix connector, 2.5

Agent, configuring, 2.3.1

alert event, example of, 1.2

alert message, example of, 1.2

alerts

to TEC events, Enterprise Manager and, 1.2

viewing, 3.4.3

B

back-end TEC Agent, 2.3.1

C

configuring

connector General page, 3.1

connector Targets page, 3.2

TEC Agent, 2.3.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

Microsoft SCOM Connector, 2.5

Enterprise Manager

alerts to TEC events, 1.2

alerts, XML format of, 4.1.2

Connector Framework (EMCF), A.2

event polling, TEC, 2.2.4

installing the connector in, 2.5

versions supported by connector, 1.3

viewing alerts, 3.4.3

event polling to TEC, Enterprise Manager and, 2.2.4

extended fields

XML path mappings, 4.1.1.2, 4.1.1.2

F

features of the connector, 1.1

G

General page settings

operation descriptions, 3.1

URL types, 3.1

H

HTTP or HTTPS, choosing, 2.2.1.1, 2.2.2.1

I

IBM TEC Connector

configuring Targets page, 3.2

testing, 3.3

IBM TEC event, example of, 1.2

IBM TEC, XML format of, 4.1.1

installed TEC connector, picture of, 2.5

installing web service, 2.2

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

Microsoft SCOM Connector

emctl parameters, 2.5

N

notification rules, 1.2

O

orapki utility, 2.2.3.1

P

poll cycle interval configured for connector, A.4

port numbers, changing defaults, 4.2

prerequisites, TEC Connector, 1.4

R

running

installation script, web service on Unix, 2.2.1.1

setup script, 2.3.1

S

sample format for IBM TEC web service, 4.1.1

setup script, running, 2.3.1

T

target settings, picture of, 3.2

TEC Connector

adding new Unix connector, 2.5

configuring General page, 3.1

features, 1.1

general settings, picture of, 3.1

installing the connector, 2.5

installing web service, 2.2

prerequisites, 1.4

target settings, picture of, 3.2

Wallet Manager, 2.2.3

TEC event, example of, 1.2

troubleshooting preparation, 5.1

trusted certificate, adding to Wallet Manager, 2.2.3.1

U

Unix

installing web service on, 2.2.1.1

running web service on, 2.2.1.2, 2.2.1.2, 2.2.1.3, 2.2.2.3

testing web service on, 2.2.1.3

V

viewing alerts, 3.4.3

W

Wallet Manager

adding trusted certificate, 2.2.3.1

orapki utility, 2.2.3

TEC Connector, 2.2.3

viewing content of wallet, 2.2.3.1

web service

installing web service on Unix, 2.2.1.1

installing web service on Windows, 2.2.2.1

running installation script, 2.2.1.1

running web service on, 2.2.1.2, 2.2.1.3, 2.2.2.3

running web service on Unix, 2.2.1.2

running web service on Windows, 2.2.2.2

testing web service on Unix, 2.2.1.3

testing web service on Windows, 2.2.2.3

Windows

installing web service on, 2.2.2.1

running web service on, 2.2.2.2

testing web service on, 2.2.2.3

X

XML format

Enterprise Manager alerts, 4.1.2

IBM TEC events, 4.1.1

message field names, mappings between, 4.1.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.