Oracle® Enterprise Manager

IBM Netcool/OMNIbus Connector Installation and Configuration Guide

Release 11.1.0.1.0

E37395-02

February 2014

Oracle Enterprise Manager IBM Netcool/OMNIbus Connector Installation and Configuration Guide, Release 11.1.0.1.0

E37395-02

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

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 is software or related documentation that 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 END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware 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 that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware 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.

Contents

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

1 Introduction to the Connector

- 1.1 Connector Features

- 1.2 Oracle Enterprise Manager Alerts Transmitted to Netcool/OMNIbus Events

- 1.3 Oracle Enterprise Manager Event Polling to Netcool/OMNIbus

- 1.4 Versions Supported

- 1.5 Prerequisites

2 Installing the Connector

- 2.1 Installation Platforms

- 2.2 Installing the IBM Netcool/OMNIbus Web Service

- 2.3 IBM Netcool/OMNIbus Web Service on Unix

- 2.3.1 Installing the Web Service on Unix

- 2.3.2 Running the Web Service on Unix

- 2.3.3 Testing the Web Service on Unix

- 2.3.4 Copying the Required .jar Files

- 2.4 IBM Netcool/OMNIbus Web Service on Windows

- 2.4.1 Installing the Web Service on Windows

- 2.4.2 Running the Web Service on Windows

- 2.4.3 Testing the Web Service on Windows

- 2.5 Adding Signed Certificates to Enterprise Manager

- 2.5.1 Adding Signed Certificates to cacerts

- 2.6 Oracle Enterprise Manager Event Polling to Netcool/OMNIbus

- 2.7 Installing and Running the IBM Netcool/OMNIbus Agent

- 2.7.1 Installing the Agent

- 2.7.2 Running and Stopping the Agent

- 2.8 Installing the IBM Netcool/OMNIbus Connector in Oracle Enterprise Manager

- 2.9 Registering Templates

3 Configuring the Connector

- 3.1 Configuring the General Page

- 3.2 Configuring the Targets Page

- 3.3 Testing the IBM Netcool/OMNIbus Connector

- 3.4 Sending Oracle Enterprise Manager Alerts to IBM Netcool/OMNIbus

- 3.4.1 Creating Notification Rules

- 3.4.2 Updating Notification Rules

- 3.4.3 Viewing Oracle Enterprise Manager Alerts

- 3.5 Sending IBM Netcool/OMNIbus Events to Oracle Enterprise Manager

4 Changing Default Configurations

- 4.1 Customizing Mappings

- 4.1.1 XML Format of IBM Netcool/OMNIbus Events

- 4.1.1.1 Mappings Between XML Format and Event Field Names

- 4.1.1.2 Extended Fields

- 4.1.2 XML Format of Oracle Enterprise Manager Alerts

- 4.1.3 Changing a Mapping

- 4.2 Changing Default Port Numbers

5 Troubleshooting the Connector

- 5.1 Preparing for Troubleshooting

- 5.2 Using the Correct URL for Netcool/OMNIbus Web Service Operations

- 5.3 Diagnosing Problems with Event Generation and Updates

- 5.3.1 Alerts from Oracle Enterprise Manager to Netcool/OMNIbus

- 5.3.2 Events from Netcool/OMNIbus to Oracle Enterprise Manager

- 5.4 Resolving Alerts from Oracle Enterprise Manager

- 5.4.1 Invalid Web Service Credentials

- 5.4.2 SSL Not Configured in Enterprise Manager

- 5.4.3 Netcool/OMNIbus Web Service Is Down

- 5.4.4 Unknown Host

- 5.4.5 Invalid IP Address or Port Number

- 5.4.6 Invalid URL Path

- 5.4.7 Netcool/OMNIbus Server Not Operational

- 5.4.8 Netcool/OMNIbus Server Timeout

- 5.4.9 Probe is not Running or Invalid Port Specified in the Configuration

- 5.5 Resolving Events from Netcool/OMNIbus

- 5.5.1 Invalid Web Service Credentials

- 5.5.2 SSL Not Configured in Oracle Enterprise Manager

- 5.5.3 Netcool/OMNIbus Web Service Is Down

- 5.5.4 Invalid Port Number

- 5.5.5 Unknown Host

- 5.5.6 Invalid IP Address

- 5.5.7 Invalid URL Path

A Default Mappings

- A.1 Data Translation Files

- A.1.1 createEvent Operation

- A.1.2 updateEvent Operation

- A.1.3 getNewAlerts and getUpdatedAlerts Operations

Index

Preface

This Installation and Configuration Guide for IBM Tivoli Netcool/OMNIbus 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 Tivoli Netcool/OMNIbus Connector to enable integration between Oracle Enterprise Manager and IBM Netcool/OMNIbus.

You should already be familiar with Oracle Enterprise Manager.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

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 Basic Installation Guide

- Oracle Enterprise Manager Grid Control Advanced Installation and Configuration Guide

- 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://docs.oracle.com/cd/E11857_01/index.htm

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 Netcool/OMNIbus Connector (version 11.1.0.1.0) integrates Oracle Enterprise Manager with IBM Netcool/OMNIbus through web services, enabling you to exchange event information between the two systems.

1.1 Connector Features

The Oracle Management Connector for IBM Netcool/OMNIbus connector enables sharing of event information between Oracle Enterprise Manager and IBM Netcool/OMNIbus:

- With the connector, you can forward alerts detected by Oracle Enterprise Manager to IBM Netcool/OMNIbus. Any changes in alert severity are also forwarded to Netcool/OMNIbus.

- Likewise, you can send events detected by Netcool/OMNIbus to Oracle Enterprise Manager.

This sharing enables Enterprise Manager administrators to get a complete summary of events happening within the entire data center.

The connector supports the following features:

- Flow of alert information from Oracle Enterprise Manager to IBM Netcool/OMNIBus and vice-versa.

- Synchronization of the alert life cycle on both ends.

- Customization of alert mappings during the alert information exchange.

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 Netcool/OMNIbus, all the state changes in Enterprise Manager are reflected in Netcool/OMNIbus. However, if you change the state of the alert in Netcool/OMNIbus, 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 sends events from Oracle Enterprise Manager to IBM Netcool/OMNIbus and vice-versa.

1.2 Oracle Enterprise Manager Alerts Transmitted to Netcool/OMNIbus Events

Conceptually, alerts in Oracle Enterprise Manager are equivalent to events in Netcool/OMNIbus. Whenever an alert is triggered in Oracle Enterprise Manager, the Netcool/OMNIbus Connector can automatically create or update an event in Netcool/OMNIbus. 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 Netcool/OMNIbus, any subsequent change of the alert severity is propagated to IBM Netcool/OMNIbus. When the severity of the alert changes to Clear in Oracle Enterprise Manager, the corresponding event is closed in Netcool/OMNIbus.

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

Figure 1-1 Oracle Enterprise Manager Alert Event Example

Figure 1-2 shows an example of an IBM Netcool/OMNIbus event.

Figure 1-2 IBM Netcool/OMNIbus Event Example

1.3 Oracle Enterprise Manager Event Polling to Netcool/OMNIbus

After installation and configuration, the event connector automatically polls the Netcool/OMNIbus web service for events to exchange alerts and messages with Oracle Enterprise Manager. The poll cycle is configurable, where the duration is specified in minutes with a minimum possible duration of five minutes. Every poll cycle, the event connector polls for up to 200 new or updated events in Netcool/OMNIbus. The Oracle Enterprise Manager connector framework processes and acknowledges all of the events provided in the poll response.

1.4 Versions Supported

This connector supports the following versions of Oracle Enterprise Manager and IBM Netcool/OMNIbus:

- Oracle Enterprise Manager Grid Control 11g.

- IBM Netcool/OMNIbus versions 7.2, 7.2.1, 7.3, and 7.3.1.

You can install the Netcool/OMNIbus Agent on the following platforms:

- Microsoft Windows (2000, 2003, 2008, XP)

- IBM AIX (RS/6000 OS version 5.2+, 5.3, 6.x, and 7.x)

- Linux RHEL (64-bit) 5.3, 5.4, 5.6

- Oracle Solaris (8, 9, and 10)

The base Enterprise Manager version number for the IBM Netcool/OMNIbus Connector Release 11.1.0.1.0 is Enterprise Manager 11g.

1.5 Prerequisites

Before using the IBM Netcool/OMNIbus connector, ensure that you meet the following prerequisites:

- Oracle Java Runtime Environment (JRE) version 6 Update 11 or higher is installed on the system where the Netcool/OMNIbus Web Service will be installed.

2 Installing the Connector

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

Figure 2-1 Connector Communication Between Components

The following sections in this chapter discuss these topics:

- Installing the IBM Netcool/OMNIbus Web Service

- IBM Netcool/OMNIbus Web Service on Unix

- IBM Netcool/OMNIbus Web Service on Windows

- Adding Signed Certificates to Enterprise Manager

- Oracle Enterprise Manager Event Polling to Netcool/OMNIbus

- Installing and Running the IBM Netcool/OMNIbus Agent

- Installing the IBM Netcool/OMNIbus Connector in Oracle Enterprise Manager

- Registering Templates

2.1 Installation Platforms

You can install the Netcool/OMNIbus web service on the following platforms that support Oracle JRE version 6 Update 11 or higher:

- Microsoft Windows

- Oracle Solaris

- HP-UX

- Linux

You can install the Netcool/OMNIbus Agent on the following platforms:

- Microsoft Windows (2000, 2003, 2008, XP)

- IBM AIX (RS/6000 OS version 5.2+, 5.3, 6.x, and 7.x)

- Linux RHEL (64-bit) 5.3, 5.4, 5.6

- Oracle Solaris (8, 9, and 10)

2.2 Installing the IBM Netcool/OMNIbus Web Service

The Netcool/OMNIbus web service acts as a front-end for all data flowing into and out of Netcool/OMNIbus. 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 Netcool/OMNIbus.

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

2.3 IBM Netcool/OMNIbus Web Service on Unix

The following sections explain how to install and then subsequently run the Web Service on a Unix platform:

- Installing the Web Service on Unix

- Running the Web Service on Unix

- Testing the Web Service on Unix

2.3.1 Installing the Web Service on Unix

To install the web service on a Unix platform:

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

$JAVA_HOME/bin/jar xvf omnibus_connector_bundle.jar

4. Make sure the JAVA_HOME environment variable is set to the directory where Oracle JDK version 6 Update 11 or higher is installed.

5. Enter the following command to unzip and extract the OMNIBUS_webservices_adapter.jar file, which is one of the components of the omnibus_connector_bundle.jar file:

$JAVA_HOME/bin/jar xvf OMNIBUS_webservices_adapter.jar

This creates the adapters directory that contains the installation files.

Note:
If the system where the Netcool/OMNIbus 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/omnibus

7. 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 a user name that must be provided to access the web service for Netcool/OMNIbus. The user name can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Make a note of this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager.

10. When the script prompts for the password of the web service, enter the password that must be provided to access the web service for Netcool/OMNIbus. The password can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Note this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager.

11. When the script prompts for the username to access the Object Server database, enter the username of an account that has read access to the alerts.status, alerts.details, and alerts.journals database tables.

12. When the script prompts for the password to access the Object Server database, enter the password for the account specified in the previous step.

13. When the script prompts for the host name of the Object Server system, enter the host name or IP address of the system where the Object Server is installed. You will not be allowed to specify a host name of localhost, because the web service will fail when attempting to connect to the Object Server database.

14. When the script prompts for the Object Server database port number, enter the port number to use when connecting to the Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window.

15. The web service can be configured to attempt to connect to a backup Object Server database if there are problems connecting to the primary Object Server database. You are prompted to specify whether you want to configure the web service to connect to a backup Object Server instance. If you answer N to the prompt, skip to step 18.

16. When the script prompts for the host name of the backup Object Server system, enter the host name or IP address of the system where the backup Object Server is installed. You are not allowed to specify a host name of localhost, because the web service will fail when attempting to connect to the Object Server database.

17. When the script prompts for the backup Object Server database port number, enter the port number to use when connecting to the backup Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window.

18. When the script prompts for the master EIF probe host name, enter the host name or IP address of the system where the master Netcool/OMNIbus EIF probe is installed.

19. When the script prompts for the master EIF probe port number, enter the port number to use when connecting to the master Netcool/OMNIbus EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

20. The web service can be configured to also send events to a slave EIF probe when sending events to the master EIF probe. You will be prompted to specify whether you want to configure the web service to send events to a slave EIF probe. If you answer N to the prompt, skip to step 23.

21. When the script prompts for the slave EIF probe host name, enter the host name or IP address of the system where the slave Netcool/OMNIbus EIF probe is installed.

22. When the script prompts for the slave EIF probe port number, enter the port number to use when connecting to the slave Netcool/OMNIbus EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

23. After the script displays the message "Netcool/OMNIbus Adapter Install Complete," press Enter to complete the installation.

24. Copy required jar files as described in Copying the Required .jar Files.

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

2.3.2 Running the Web Service on Unix

To run the IBM Netcool/OMNIbus 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

2.3.3 Testing the Web Service on Unix

To verify that the IBM Netcool/OMNIbus Web Service is functional:

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

2. 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 Testing the IBM Netcool/OMNIbus Connector.

2.3.4 Copying the Required .jar Files

The web service for Netcool/OMNIbus requires you to copy the following .jar files to the lib/adapters directory:

- log.jar — Used by the EIF probe

- evd.jar — Used by the EIF probe

- jconn4.jar — Sybase JDBC driver file

To copy the appropriate .jar files, complete the following steps:

1. From the Object Server system, access the following directory:
Unix:

$OMNIHOME/probes/<platform>

Windows:

%OMNIHOME%\probes\<platform>

Where:

<platform> is the actual platform name (such as win32).

2. Copy the log.jar and evd.jar files to the lib/adapters directory in the web service installation directory.

3. Access the following URL to download the Sybase JDBC driver file:

http://downloads.sybase.com/swd/summary.do?client=support&baseprod=63

4. Create an account, which is required to download the driver. After you have created an account, select All from the drop-down list next to "Display" and in all months next to "platforms."

5. Click Go to get a list of drivers available for download.

6. Select latest version 7 release of jConnect for JDBC and download.

7. Extract the contents of the .tgz file into a temporary directory.

8. Navigate to the jConnect installation directory for the appropriate platform:

- For Windows: navigate to the ebfxxxxx\windows\Disk1\InstData directory.

- For Unix: navigate to the ebfxxxxx/unix/Disk1/InstData directory.

Where xxxxx is the version of the jar file.

9. Run the setup executable to install jConnect.

10. Navigate to the jConnect-7_0/classes directory in the jConnect installation directory.

11. Copy the jconn4.jar file to the lib/adapters directory.

Note:
If version 7 of the jConnect is not available for download, you can download the latest version available. With each major version release, the name of the jconn jar file changes; so, the name of the jar file will likely be different.
Whenever the jar file name changes, a configuration change must be made to the OMNIbus Web Service. Listed below are the steps required to make the configuration change to the Web Service:

1. Navigate to the conf directory of the Web Service installation directory.

2. Open the framework.properties file in a text editor.

3. Change the omnibus.sql.driver property to the path of the SybDriver class in the jconn jar file that was downloaded. For example:
If the jar file is named jconn3.jar, then the path should be:

com.sybase.jdbc3.jdbc.SybDriver

If the jar file is named jconn4.jar, then the path should be:

com.sybase.jdbc4.jdbc.SybDriver

If there are any problems using those paths, you can use the jar utility to determine the correct path to the SybDriver class as shown below

jar tvf /path/to/jconnx.jar | grep SybDriver

4. Save the update to the framework.properties file.

5. Restart the OMNIbus Web Service.

2.4 IBM Netcool/OMNIbus Web Service on Windows

The following sections explain how to install and then subsequently run the Web Service on a Windows platform:

- Installing the Web Service on Windows

- Running the Web Service on Windows

- Testing the Web Service on Windows

2.4.1 Installing the Web Service on Windows

To install the web service on a Windows platform:

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

$JAVA_HOME/bin/jar xvf omnibus_connector_bundle.jar

4. Make sure the JAVA_HOME environment variable is set to the directory where Oracle JDK version 6 Update 11 is installed.

5. Unzip and extract the OMNIBUS_webservices_adapter.jar file, which is one of the components of the omnibus_connector_bundle.jar file:

%JAVA_HOME%\bin\jar xvf OMNIBUS_webservices_adapter.jar

This creates the adapters directory that contains the installation files.

Note:
If the system where the Netcool/OMNIbus 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. Change to the working directory:

cd adapters\endpoints\omnibus

7. 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 a user name that must be provided to access the Netcool/OMNIbus Web Service. The user name can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Note this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager.

10. When the script prompts for the password of the web service, enter the password that must be provided to access the Netcool/OMNIbus Web Service. The password can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Note this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager

11. When the script prompts for the username to access the Object Server database, enter the username of an account that has read access to the alerts.status, alerts.details, and alerts.journals database tables.

12. When the script prompts for the password to access the Object Server database, enter the password for the account specified in the previous step.

13. When the script prompts for the host name of the Object Server system, enter the host name or IP address of the system where the Object Server is installed. You will not be allowed to specify a host name of localhost, because the web service will fail when attempting to connect to the Object Server database.

14. When the script prompts for the Object Server database port number, enter the port number to use when connecting to the Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window.

15. The web service can be configured to attempt to connect to a backup Object Server database if there are problems connecting to the primary Object Server database. You are prompted to specify whether you want to configure the web service to connect to a backup Object Server instance. If you answer N to the prompt, skip to step 18.

16. When the script prompts for the host name of the backup Object Server system, enter the host name or IP address of the system where the backup Object Server is installed. You are not allowed to specify a host name of localhost, because the web service will fail when attempting to connect to the Object Server database

17. When the script prompts for the backup Object Server database port number, enter the port number to use when connecting to the backup Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window

18. When the script prompts for the master EIF probe host name, enter the host name or IP address of the system where the master Netcool/OMNIbus EIF probe is installed.

19. When the script prompts for the master EIF probe port number, enter the port number to use when connecting to the master Netcool/OMNIbus EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

20. The web service can be configured to also send events to a slave EIF probe when sending events to the master EIF probe. You will be prompted to specify whether you want to configure the web service to send events to a slave EIF probe. If you answer N to the prompt, skip to step 23.

21. When the script prompts for the slave EIF probe host name, enter the host name or IP address of the system where the slave Netcool/OMNIbus EIF probe is installed.

22. When the script prompts for the slave EIF probe port number, enter the port number to use when connecting to the slave Netcool/OMNIbus EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

23. After the script displays the message "Netcool/OMNIbus Adapter Install Complete," press Enter to complete the installation.

24. Copy the required jar files as described in Copying the Required .jar Files.

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

1. Change to the working directory to the \bin directory:

cd ..\..\bin

2. Install the web service as a Windows service:

service.bat install

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

If the IBM Netcool/OMNIbus Web Service was configured to use the HTTPS protocol, the certificate must be imported into Enterprise Manager. See Adding Signed Certificates to Enterprise Manager for instructions.

2.4.2 Running the Web Service on Windows

Standalone Service

To start the Netcool/OMNIbus 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 Netcool/OMNIbus web service framework, close the window where you started the adapter.

Windows Service

To start the Netcool/OMNIbus web service framework when set up to run as a Windows service:

net start iWaveAdapters

To shut down the Netcool/OMNIbus web service framework:

net stop iWaveAdapters

2.4.3 Testing the Web Service on Windows

To verify that the IBM Netcool/OMNIbus Web Service is functional.

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

2. 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 Testing the IBM Netcool/OMNIbus Connector.

2.5 Adding Signed Certificates to Enterprise Manager

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

2.5.1 Adding Signed Certificates to cacerts

To add signed certificates to the Java cacerts keystore for Oracle Enterprise Manager version 11.1.0.1:

1. Obtain a copy of the certificate that the Netcool/OMNIbus web service is using.

2. Copy the certificate to the machine where Enterprise Manager is installed.

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

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

5. Add the certificate to the cacerts keystore:

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

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

2.6 Oracle Enterprise Manager Event Polling to Netcool/OMNIbus

After installation and configuration, the event connector automatically polls the Netcool/OMNIbus 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 Netcool/OMNIbus. The Oracle Enterprise Manager connector framework processes and acknowledges all of the events provided in the poll response.

2.7 Installing and Running the IBM Netcool/OMNIbus Agent

The following sections provide procedures for installing and running the Netcool/OMNIbus Agent:

- Installing the Agent

- Running and Stopping the Agent

2.7.1 Installing the Agent

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

To install the Netcool/OMNIbus Agent:

1. Download omnibus_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 Netcool/OMNIbus Agent.

Note:
You need to do this on the IBM Netcool/OMNIbus 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

OMNIbusAgentAIX.tar.gz

Oracle Solaris

OMNIbusAgentSolaris.tar.gz

Microsoft Windows

OMNIbusAgentWindows.zip

Linux

OMNIbusAgentLinux.tar.gz

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

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

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

- For IBM AIX, issue the following commands to unzip and untar the files:

gunzip OMNIbusAgentAIX.tar.gz
tar xvf OMNIbusAgentAIX.tar

- For Solaris, issue the following commands to unzip and untar the files:

gunzip OMNIbusAgentSolaris.tar.gz
tar xvf OMNIbusAgentSolaris.tar

- For Linux platforms, issue the following commands to unzip and untar the files:

gunzip OMNIbusAgentLinux.tar.gz
tar xvf OMNIbusAgentLinux.tar

4. Change the working directory to the agent directory.

5. Run the setup script to configure the agent.
The file name depends on the platform. If the platform is Windows, the setup script is named Setup.cmd. For all other platforms, the setup script is named setup.sh and should be called using the following command:

sh ./setup.sh

6. When the script prompts for the web service host name, enter the host name or IP address where the web service for Netcool/OMNIbus is installed.

7. When the script prompts for the web service port, enter the port number the web service for Netcool/OMNIbus uses to receive transactions from the Agent. Specify the default value of 8080 unless the web service has been reconfigured to use a different port.

8. When the script prompts for the user ID to specify when creating event journal entries in Netcool/OMNIbus, enter the user ID of a user that has permission to add journal entries. If no value is specified, the user ID will default to 0 (root). The value specified must be an integer value and will not work properly if a different value is entered.
The script generates the necessary configuration files and places them in the Agent directory. The Agent is now installed, but you need to make some modifications in Netcool/OMNIbus for everything to function properly.

2.7.2 Running and Stopping the Agent

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

2.8 Installing the IBM Netcool/OMNIbus Connector in Oracle Enterprise Manager

The following procedure explains how to add the new Netcool/OMNIbus Connector. 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 Enterprise Manager version 11.1.0.1, this is the oms11g directory.

Example settings of the OMS_HOME variable include C:\Oracle\Middleware2\oms11g on a Windows platform running version 11.1.0.1.

1. Download the omnibus_connector_bundle.jar from the Oracle Technology Network to the installation directory, then extract the omnibus_connector.jar file.

2. Enter the following command to extract the connector.jar file:

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

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/omnibus_connector.jar" –cname "OMNIBUS Connector"

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

3. 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. See Table 2-2 for a description of the parameters.

- Enterprise Manager version 11.1.0.1

$OMS_HOME/bin/emctl register_connector connector -dd "<deployment_file>" -repos_pwd <password>

Command Example

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

The new Netcool/OMNIbus 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 Netcool/OMNIbus 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 "OMNIBUS Connector". The double quotes ( "" ) are mandatory.

connector_type_name

Connector type name. Specify "OMNIBUS 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 OMNIBUSConnector.xml file resides in the OMNIbus connector directory $OMS_HOME/sysman/connector/OMNIBUS_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 omnibus_connector.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.

2.9 Registering Templates

To register templates for various Enterprise Manager versions:

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

- For Enterprise Manager version 11.1.0.1:

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

2. Replace <template.xml>, <internal_name>, <template_name> and <template_type> with the values listed in Table 2-3, which lists the properties of each template for the IBM Netcool/OMNIbus Connector.

Table 2-3 Possible Replacement Values for register_template Parameters

template.xsl and template.xml

internal_name

template_name

template_type

acknowledge_request.xsl

acknowledgeAlerts

Acknowledge Alerts

2

createEvent_request.xsl

createEvent

Create Event Request

2

createEvent_response.xsl

createEvent

Create Event Response

1

generic_request_acknowledgealerts.xml

acknowledgeAlerts

Acknowledge Alerts

3

getNewAlert_request.xsl

getNewAlerts

Get New Alerts Request

2

getNewAlerts_response.xsl

getNewAlerts

Get New Alerts Response

1

getUpdatedAlert_request.xsl

getUpdatedAlerts

Get Updated Alerts Request

2

getUpdatedAlerts_response.xsl

getUpdatedAlerts

Get Update Alerts Response

1

updateEvent_request.xsl

updateEvent

Update Event Request

2

updateEvent_response.xsl

updateEvent

Update Event Response

1

The following Enterprise Manager version 11.1.0.1 examples are based on the template values shown in Table 2-3.

- Request XSL File for acknowledgeAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/acknowledge_request.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Acknowledge Alerts" -iname "acknowledgeAlerts" -ttype 2 -d "This is the request xsl file for acknowledgeAlerts method"

- Request XSL File for createEvent Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/createEvent_request.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Create Event Request" -iname "createEvent" -ttype 2 -d "This is the request xsl file for createEvent method"

- Response XSL File for createEvent Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/createEvent_response.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Create Event Response" -iname "createEvent" -ttype 1 -d "This is the response xsl file for createEvent method"

- Request XML File for acknowledgeAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/generic_request_acknowledgealerts.xml -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Acknowledge Alerts" -iname "acknowledgeAlerts" -ttype 3 -d "This is the request xml file for acknowledgeAlerts method"

- Request XSL File for getNewAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/getNewAlert_request.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Get New Alerts Request" -iname "getNewAlerts" -ttype 2 -d "This is the request xsl file for getNewAlerts method"

- Response XSL File for getNewAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/getNewAlerts_response.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Get New Alerts Response" -iname "getNewAlerts" -ttype 1 -d "This is the response xsl file for getNewAlerts method"

- Request XSL File for getUpdatedAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/getUpdatedAlert_request.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Get Updated Alerts Request" -iname "getUpdatedAlerts" -ttype 2 -d "This is the request xsl file for getUpdatedAlerts method"

- Response XSL File for getUpdatedAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/getUpdatedAlerts_response.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Get Updated Alerts Response" -iname "getUpdatedAlerts" -ttype 1 -d "This is the response xsl file for getUpdatedAlerts method"

- Request XSL File for updateEvent Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/updateEvent_request.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Update Event Request" -iname "updateEvent" -ttype 2 -d "This is the request xsl file for updateEvent method"

- Response XSL File for updateEvent Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/updateEvent_response.xsl -repos_pwd <password> -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Update Event Response" -iname "updateEvent" -ttype 1 -d "This is the response xsl file for updateEvent method"

3 Configuring the Connector

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

This chapter discusses the following topics:

- Configuring the General Page

- Configuring the Targets Page

- Testing the IBM Netcool/OMNIbus Connector

- Sending Oracle Enterprise Manager Alerts to IBM Netcool/OMNIbus

- Sending IBM Netcool/OMNIbus Events to Oracle Enterprise Manager

3.1 Configuring the General Page

To configure the General page:

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

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

The Netcool/OMNIbus connector uses the following operations (web methods) to exchange data with the Netcool/OMNIbus Web Service:

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

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

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

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

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

URL Types

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

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

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

http://[Hostname]:8080/services/omnibus/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 Netcool/OMNIbus 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 Netcool/OMNIbus 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 Netcool/OMNIbus web service certificate in Oracle Wallet Manager as described in Adding Signed Certificates to Enterprise Manager.

3. Enter the user name and password you specified when you installed the Netcool/OMNIbus web service, which is discussed in steps 9 and 10 of Installing the Web Service on Unix and section steps 9 and 10 of Installing the Web Service on Windows.
The Netcool/OMNIbus web service installer prompts for the user name and password that should be supplied when accessing the Netcool/OMNIbus 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.

Note:
The Enterprise Manager credentials are not used directly by the connector. The connector credentials are required by the connector framework.

5. Optionally enter a polling interval to specify how often Oracle Enterprise Manager should poll the IBM Netcool/OMNIbus 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.

3.2 Configuring the Targets Page

Whenever an IBM Netcool/OMNIbus event is translated into an Oracle Enterprise Manager alert, the IBM Netcool/OMNIbus 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_omnibus_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 Netcool/OMNIbus Connector Target Settings

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

3. Provide the Netcool/OMNIbus host name in the OMNIBUS 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.

3.3 Testing the IBM Netcool/OMNIbus Connector

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 Netcool/OMNIbus 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/omnibus/EventService?wsdl

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

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

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 Netcool/OMNIbus web service is installed.

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

3.4 Sending Oracle Enterprise Manager Alerts to IBM Netcool/OMNIbus

Alerts generated or updated in Oracle Enterprise Manager are not transferred to Netcool/OMNIbus unless you create notification rules to invoke the IBM Netcool/OMNIbus 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

- Updating Notification Rules

- Viewing Oracle Enterprise Manager Alerts

3.4.1 Creating Notification Rules

The following procedure explains how to create a new notification rule to invoke the Netcool/OMNIbus 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 OMNIBUS Connector to assign the Netcool/OMNIbus notification method to the notification rule.

8. Click OK to complete the setup.

3.4.2 Updating Notification Rules

The following procedure explains how to update an existing notification rule to invoke the Netcool/OMNIbus 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 Netcool/OMNIbus Connector to assign the Netcool/OMNIbus notification method to the notification rule.

5. Click OK to complete the update.

3.4.3 Viewing Oracle Enterprise Manager Alerts

Whenever an event is created in IBM Netcool/OMNIbus 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.

3.5 Sending IBM Netcool/OMNIbus Events to Oracle Enterprise Manager

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

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

4.1 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 Netcool/OMNIbus Events

- XML Format of Oracle Enterprise Manager Alerts

- Changing a Mapping

Note:
It is assumed that you already have a good understanding of XSL.
For reference information on the default mappings, see Appendix A, "Default Mappings."

4.1.1 XML Format of IBM Netcool/OMNIbus Events

Example 4-1 represents the format that the IBM Netcool/OMNIbus web service expects for creating new events in IBM Netcool/OMNIbus. 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 Netcool/OMNIbus Web Service

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

4.1.1.1 Mappings Between XML Format and Event Field Names

Table 4-1 identifies the mappings between the IBM Netcool/OMNIbus base event slot names and the XML format that the IBM Netcool/OMNIbus web services uses. The XML document presented to the IBM Netcool/OMNIbus web service must have the corresponding fields set. This must be handled in the appropriate translation file identified in Table A-1, "XSL Files that Perform Mappings".

Table 4-1 Event Attributes and XML Path Mappings

IBM Netcool/OMNIbus Slot Names

XML Path

Identifier

/create/event/identifier

Node

/create/event/source/displayName

NodeAlias

/create/event/source/name

AlertGroup

/create/event/metric/category

AlertKey

/create/ event/object/identifier

Severity

/create/event/severity

Summary

/create/event/description

Type

/create/event/type

All other slot names

See Extended Fields below.

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

4.1.2 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

EventGuide

Unique identifier of the alert in Oracle Enterprise Manager.

ExternalEventId

Unique identifier of the event in IBM Netcool/OMNIbus. 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 Netcool/OMNIbus.

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.

4.1.3 Changing a Mapping

This section explains how to customize the mapping between Enterprise Manager and the IBM Netcool/OMNIbus 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 XML Format of IBM Netcool/OMNIbus Events and Mappings Between XML Format and Event Field Names. These sections describe the data formats of the IBM Netcool/OMNIbus events and Oracle Enterprise Manager alerts.

5. Save your changes.

6. Rerun the register command for the template that was modified to pick up the changes. See Registering Templates for details.

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 Netcool/OMNIbus 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 Netcool/OMNIbus. 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:

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

2. The sub_origin slot is not set to any value.

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

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

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

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

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

8. 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>
<!-- OMNIbus slot = source -->
<name>OracleEnterpriseManager</name>
<!-- OMNIbus slot = origin -->
<computerName>
<xsl:value-of select="a:TargetType"/>
</computerName>
</source>
…
<extended-fields>
<!-- OMNIbus 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>
<!-- OMNIbus slot = source -->
<name>OracleEnterpriseManager</name>
<!-- OMNIbus slot = origin -->
<computerName>Oracle Enterprise Manager</computerName>
</source>
…
<extended-fields>
<!-- OMNIbus 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>

9. Save your changes after making the updates.

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

11. Save your changes after making the updates.

12. Run the following register command for the template that was modified to enable OMS to pick up the changes:

emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/createEvent_request.xsl -repos_pwd testPass -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Create Event Request" -iname "createEvent" -ttype 2 -d "This is the request xsl file for createEvent method"

4.2 Changing Default Port Numbers

In most cases, you can use the default port numbers that the IBM Netcool/OMNIbus 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 Netcool/OMNIbus web services are installed. Replace

<OMNIBUSWS_INSTALL> with the directory where the IBM Netcool/OMNIbus web services are installed.

1. Open a command prompt window and change the working directory to:

<OMNIBUSWS_INSTALL>/adapters/conf

2. Enter the following command to configure the web service to connect to the IBM Netcool/OMNIbus 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 Netcool/OMNIbus 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 Netcool/OMNIbus 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 Netcool/OMNIbus 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 Netcool/OMNIbus. 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 Netcool/OMNIbus Web Service Operations

- Diagnosing Problems with Event Generation and Updates

- Resolving Alerts from Oracle Enterprise Manager

- Resolving Events from Netcool/OMNIbus

5.1 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:
Enterprise Manager version 11.1.0.1

<ORACLE_HOME>/oms11g/sysman/config

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

5.2 Using the Correct URL for Netcool/OMNIbus Web Service Operations

To identify and configure the connector to use the correct URL for Netcool/OMNIbus Web Service operations:

1. Open a command terminal on the system where the Netcool/OMNIbus web service is installed.

2. Change the working directory to the adapters/log directory in the Netcool/OMNIbus 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 Netcool/OMNIbus 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.

5.3 Diagnosing Problems with Event Generation and Updates

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

- Events from Netcool/OMNIbus to Oracle Enterprise Manager

5.3.1 Alerts from Oracle Enterprise Manager to Netcool/OMNIbus

Netcool/OMNIbus can generate or update events from alerts that have originated in Oracle Enterprise Manager. Perform the following diagnostic steps if Netcool/OMNIbus 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 Setup in the upper right corner of the Oracle Enterprise Manager console.

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

4. Locate the Netcool/OMNIbus 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 Preferences in the upper right corner.

6. Click Notification Rules 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 Netcool/OMNIbus 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 Netcool/OMNIbus.
For example, if the Memory Utilization % metric was set up to invoke the Netcool/OMNIbus 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 the Alerts tab.

2.) Click the Critical sub-tab.

3.) Click 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 Netcool/OMNIbus 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.

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

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 Resolving Alerts from Oracle Enterprise Manager for information on troubleshooting common error events.

5.3.2 Events from Netcool/OMNIbus to Oracle Enterprise Manager

Oracle Enterprise Manager can generate or update alerts resulting from events that have originated in Netcool/OMNIbus. 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:
Enterprise Manager 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

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 Resolving Events from Netcool/OMNIbus 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.

5.4 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

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 Enterprise Manager

11.1.0.1

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

Netcool/OMNIbus 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 Netcool/OMNIbus failed

Netcool/OMNIbus Server Not Operational

11.1.0.1

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

Netcool/OMNIbus Server Timeout

11.1.0.1

com.iwave.operations.OperationsException.OperationsException: Attempt to insert the event into the master probe failed

Probe is not Running or Invalid Port Specified in the Configuration

11.1.0.1

5.4.1 Invalid Web Service Credentials

Cause

The user name or password for accessing the Netcool/OMNIbus 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 Netcool/OMNIbus Connector.

5. Click the General tab.

6. Correct the Netcool/OMNIbus Web Service Username and Netcool/OMNIbus Web Service Password fields, then click OK.

5.4.2 SSL Not Configured in Enterprise Manager

Cause

The SSL handshake between the Oracle Enterprise Manager Connector Framework and the Netcool/OMNIbus web service failed. This failure occurs because Oracle Enterprise Manager is not configured correctly with the SSL certificate for the Netcool/OMNIbus web service. The SSL certificate the Netcool/OMNIbus 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 Netcool/OMNIbus web service.

Solution

Import the SSL certificate from the Netcool/OMNIbus web service into the certificate store. See Adding Signed Certificates to Enterprise Manager for details on setting up Oracle Enterprise Manager with the Netcool/OMNIbus SSL certificate.

5.4.3 Netcool/OMNIbus Web Service Is Down

Cause

The Netcool/OMNIbus web service is down.

Solution

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

If the Netcool/OMNIbus web service is installed on a Unix system:

1. Open a command terminal on the system where the Netcool/OMNIbus web service is installed.

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

1. Open a command terminal on the system where the Netcool/OMNIbus web service is installed.

2. Change the working directory to the adapters/log directory in the Netcool/OMNIbus 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.

5.4.4 Unknown Host

Cause

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

Solution

To address this issue:

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

2. 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 Netcool/OMNIbus 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 Netcool/OMNIbus 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.

5.4.5 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 Netcool/OMNIbus 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 Netcool/OMNIbus web service is installed using the hostname/IP address. If the ping fails, the system administrator needs to investigate why there is no connectivity.

5.4.6 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 for Enterprise Manager version 11.1.0.1 is:

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

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. 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 Netcool/OMNIbus 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/omnibus/EventService?wsdl

Where [Hostname] is the actual host name or IP address where the Netcool/OMNIbus 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 Using the Correct URL for Netcool/OMNIbus Web Service Operations to configure the connector to use the correct URL.

5.4.7 Netcool/OMNIbus Server Not Operational

Cause

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

- The Netcool/OMNIbus server is down.

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

- A network outage is preventing the Netcool/OMNIbus web service from connecting to the Netcool/OMNIbus server.

Solution

To determine and correct the root cause of the problem:

1. Open a command terminal on the system where the Netcool/OMNIbus web service is installed.

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

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

4. Search for the omnibus.sql.url parameter. This parameter specifies the hostname/IP address to use when connecting to the Netcool/OMNIbus 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 Netcool/OMNIbus 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. If the hostname/IP address is valid and reachable, and the port number is correct, the Netcool/OMNIbus server must be down.

7. To start Netcool/OMNIbus server use

emctl start oms

5.4.8 Netcool/OMNIbus Server Timeout

Cause

The web service received the request and successfully sent the request to the TEC EIF probe. The web service timed out waiting for Netcool/OMNIbus to send a notification that the requested alert that was created/updated. This error occurs because Netcool/OMNIbus is not properly configured to send the response to the web service.

Listed below is a summary of the sequence of events that occur whenever an event is created/updated in Netcool/OMNIbus.

1. Enterprise Manager makes a web service call for a create/update operation.

2. The web service makes an API call to the EIF probe to insert an event.

3. The EIF Probe inserts a row in the custom.oracle_status table for the event.

4. The oracle_insert_alert trigger fires and creates/updates the appropriate alert in the alerts.status, alerts.details, and alerts.journal database tables.

5. The oracle_alert_created, oracle_alert_reinserted, or oracle_alert_updated trigger fires calling the oracle_send external procedure.

6. The oracle_send external procedure calls the oracle_send.cmd (Windows) or oracle_send.sh (Unix) script to send a notification to the web service.

7. The oracle_send.cmd/oracle_send.sh script calls the universal agent utility (uniagt.exe) to send the notification to the web service.

8. Upon receipt of the notification, the web service makes a JDBC call to retrieve field information for the alert.

9. The web service sends a response to Enterprise Manager with the alert information.

A failure in steps 3 through 8 results in a timeout being reported by the web service for Netcool/OMNIbus.

Solution

Perform the following steps to identify the location of the failure:

1. Verify that the Object Server and EIF Probe are operational. Correct any issues that are found and retry.

2. Open the Netcool/OMNIbus console and determine whether an alert was created/updated.
If the alert was NOT created/updated, the failure occurred in Cause step 3 or 4. Perform the following steps to determine the reason for the failure:

1. Check the EIF Probe log file for errors. If there are errors, you will need to determine the cause of the error and fix the problem. Most likely the error will be caused by a lack of connectivity between the probe system and the object server system.

2. If there are no errors in the EIF Probe log file, verify that a row was added to the custom.oracle_status table for the event. If a row was not added, there must be a problem with the configuration of the EIF probe. Enable debug in the EIF Probe and run another test. Look in the EIF Probe log file to see if there is any information about what the probe did with the event.

3. If a row was added to the custom.oracle_status table, examine the ErrorMessage column for any error information.

4. Examine the object server log file to verify that the oracle_insert_alert trigger fired. If the trigger did not fire, open the definition for the trigger and verify it is enabled.

5. If the trigger fired, look for any errors that occurred while running the trigger.

3. If the alert was created/updated, the failure occurred somewhere in Cause steps 5 through 8. Perform the following steps to determine the reason for the failure:

1. Examine the object server log file to verify that one of the oracle_alert_created, oracle_alert_reinserted, or oracle_alert_updated triggers fired. If none of the triggers fired, open the definition for the triggers and look for anything that might prevent the trigger from firing. One possibility is that the trigger has been disabled.

2. If one of the triggers fired, look for any errors that occurred while running the trigger. If there are no errors in the object server log, you will need to enable debug in the script to see if it is being called. Step c below gives instructions for enabling debug in a Windows environment and step d gives instructions for enabling debug in a Unix environment.

3. For Windows environments, perform the following steps to enable debug in the notification script.
Open the oracle_send.cmd script with a text editor.

Uncomment the following lines by removing the REM at the beginning of the line:

echo %DATE% %TIME% %* >> "%AGENT_DIR%\oracle_send.out"

"%AGENT_DIR%\bin\uniagt" -r %OMNIBUS_WS_URL% -v 1 -O "%AGENT_DIR%\agent%1.log"

Comment the following line by prepending REM to the beginning of the line:

"%AGENT_DIR%\bin\uniagt" -r %OMNIBUS_WS_URL%

Save the file and exit.

4. For Unix environments, perform the following steps to enable debug in the notification script:
Open the oracle_send.sh script with a text editor.

Uncomment the following lines by removing the # at the beginning of the line:

echo `date` $* >> ${AGENT_DIR}/oracle_send.out

${AGENT_DIR}/bin/uniagt -r ${OMNIBUS_WS_URL} -v 1 -O ${AGENT_DIR}/agent/{1}.log

Comment the following line by prepending # to the beginning of the line:

${AGENT_DIR}/bin/uniagt -r ${OMNIBUS_WS_URL}

Save the file and exit.

5. After enabling debug, run another test and determine whether the oracle_send.out log file was created. If the file was created, open it with a text editor and look at the last line in the file to get the serial number. The line starts with the date/time the script was called followed by the serial number and the name of the trigger that fired.

6. Verify that an agent log was created for the serial number. The agent log should be named agent<serialno>.log where <serialno> is the serial number from the oracle_send.out log file.

7. If the file exists, open it with a text editor and look for errors sending to the web service. If errors occur, it will likely be caused by a connectivity issue or an invalid URL specified in the OMNIBUS_WS_URL environment variable. Check the hostname/IP address and port number in the URL. Unless specifically changed, the port number should be 8080. If the notification was sent successfully, you will see something similar to the following in the log.

2012/06/13 11:20:52 response headers: <HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 0
Server: Jetty(6.1.14)

8. If the agent log indicates the notification was successfully sent to the web service, look in the web service log for errors. The web service log is located in the adapters/log directory of the web service installation directory and is named framework.log. Most likely the error will be caused by a failure to connect to the database to retrieve the alert information.

5.4.9 Probe is not Running or Invalid Port Specified in the Configuration

Cause

The web service could not insert the event into Netcool/OMNIbus because it could not connect to the Netcool/OMNIbus probe.

Solution

1. Open a command terminal on the system where the Netcool/OMNIbus web service is installed.

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

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

4. Search for the omnibus.probe.master.t_ServerLocation parameter. This parameter specifies the server name where Netcool/OMNIbus probe is located.
Verify that the server name is correct.

5. Search for the omnibus.probe.master.t_Port parameter. This parameter specifies the port where Netcool/OMNIbus probe is located.
Verify that the port number is correct.

5.5 Resolving Events from Netcool/OMNIbus

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 diagnose and correct the problem.

Table 5-2 Netcool/OMNIbus Error Messages

Alert Message

Possible Cause

Applicable Versions

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 Enterprise Manager

11.1.0.1

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

Netcool/OMNIbus 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

5.5.1 Invalid Web Service Credentials

Cause

The user name or password for accessing the Netcool/OMNIbus 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 Netcool/OMNIbus Connector.

5. Click the General tab.

6. Correct the Netcool/OMNIbus Web Service Username and Netcool/OMNIbus Web Service Password fields and click OK.

5.5.2 SSL Not Configured in Oracle Enterprise Manager

Cause

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

Solution

You need to import the SSL certificate from the Netcool/OMNIbus web service into the certificate store. See Adding Signed Certificates to Enterprise Manager for details on setting up Oracle Enterprise Manager with the Netcool/OMNIbus SSL certificate.

5.5.3 Netcool/OMNIbus Web Service Is Down

Cause

The Netcool/OMNIbus web service is down.

Solution

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

If the Netcool/OMNIbus web service is installed on a Unix system:

1. Open a command terminal on the system where the Netcool/OMNIbus web service is installed.

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

1. Open a command terminal on the system where the Netcool/OMNIbus web service is installed.

2. Change the working directory to the adapters/log directory in the Netcool/OMNIbus 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 Using the Correct URL for Netcool/OMNIbus Web Service Operations to identify the correct URL, including the port number.

5.5.4 Invalid Port Number

Cause

The port number in the URL is incorrect.

Solution

Perform the steps specified in Using the Correct URL for Netcool/OMNIbus Web Service Operations to identify the correct URL, including the port number.

5.5.5 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 Netcool/OMNIbus 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 Netcool/OMNIbus 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.

5.5.6 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 Netcool/OMNIbus 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 is 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 Netcool/OMNIbus web service is installed using the hostname/IP address. If the ping fails, the system administrator needs to investigate why there is no connectivity.

5.5.7 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 Using the Correct URL for Netcool/OMNIbus 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 Netcool/OMNIbus 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."

A.1 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/OMNIBUS_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 Netcool/OMNIbus event format for the createEvent operation.

updateEvent_request.xsl

Transforms the Oracle Enterprise Manager alert data to the IBM Netcool/OMNIbus event format for the updateEvent operation.

getNewAlerts_response.xsl

Transforms data in the IBM Netcool/OMNIbus 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 Netcool/OMNIbus 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

- updateEvent Operation

- getNewAlerts and getUpdatedAlerts Operations

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

Table A-2 createEvent Operation Mappings

Netcool/Omnibus

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

Slot

Attribute Type

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>

A.1.2 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 Netcool/OMNIbus connector.

The updateEvent_request.xsl file is invoked during the process to transform the data from Oracle Enterprise Manager format to Netcool/OMNIbus event format. Table A-3 lists the default field mappings between the IBM Netcool/OMNIbus event and the Oracle Enterprise Manager alert.

Table A-3 updateEvent Operation Mappings

Netcool/Omnibus

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

Slot

Attribute Type

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>

A.1.3 getNewAlerts and getUpdatedAlerts Operations

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

Req'd?

Oracle Enterprise Manager Alert Attributes

Value

Event Attribute

Attribute Type

key1

String

Yes

Set to the IBM Netcool/OMNIbus 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 Netcool/OMNIbus 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.

OMNIBUS

targetName

String

No

Set to the host that reported the problem.

<hostname>

TargetType

String

No

Value defaulted.

omnibus_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

No

Conditional based on the IBM Netcool/OMNIbus status and severity.

Set to Clear if the Netcool/OMNIbus status is set to CLOSED.

Set to Informational if the Netcool/OMNIbus status is not set to CLOSED and the Netcool/OMNIbus severity is HARMLESS.

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

Set to Warning if the Netcool/OMNIbus status is not set to CLOSED and any other Netcool/OMNIbus severity value is specified.

Index
A  C  E  I  N  O  P  R  S  T  U  W  X

A

add signed certificates

Java cacerts, 2.5.1

C

change default mappings, 4

change default port numbers, 4, 4.2

configure general page, 3.1

configure targets page, 3.2

connector features, 1.1

create and update notification rules, 3.4

E

emctl parameters, 2.8

event polling, 1.3

I

installation platforms, 2.1

N

Netcool/OMNIbus Agent, 2.7

install, 2.7.1

O

Oracle Enterprise Manager

install the connector, 2.8

Oracle Enterprise Manager alerts, 4.1.2

P

poll cycle, 2.6

polling, 2.6

R

register templates, 2.9

S

Service Manager SSL certificate, 2.5

supported versions, 1.4

T

test the connector, 3.3

U

Unix, 2.3

install web service, 2.3.1

run web service, 2.3.2

test web service, 2.3.3

W

web service

install on Unix, 2.3.1

install on Windows, 2.4.1

run on Unix, 2.3.2

run on Windows as standalone service, 2.4.2

run on Windows as Windows service, 2.4.2

test on Unix, 2.3.3

test on Windows, 2.4.3

Windows, 2.4

install web service, 2.4.1

run web service, 2.4.2

test web service, 2.4.3

X

XML format, 4.1.1, 4.1.2

XML path mappings, 4.1.1.1

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2014, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

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.

Warranty Disclaimer

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.

Restricted Rights Notice

If this is software or related documentation that 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 END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware 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 that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware 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.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.