Sie sind auf Seite 1von 34

Tivoli Netcool/OMNIbus MTOSI Northbound Interface

Version 0.0.5900

Reference Guide December 19, 2008

SC23-6097-01

Tivoli Netcool/OMNIbus MTOSI Northbound Interface

Version 0.0.5900

Reference Guide December 19, 2008

SC23-6097-01

Note Before using this information and the product it supports, read the information in Notices and Trademarks, on page 21.

Edition notice This edition applies to version 0.0.5900 of IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface (SC23-6097-01) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC23-6097-00. Copyright International Business Machines Corporation 2006, 2008. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Document control page . . . . . . . . v IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface . . . . . . . . . 1
Summary . . . . . . . . . . . . . . System overview . . . . . . . . . . . . MTOSI Web application . . . . . . . . NBI . . . . . . . . . . . . . . . RMI registry . . . . . . . . . . . . System diagram . . . . . . . . . . . Installation and configuration. . . . . . . . Installing the NBI. . . . . . . . . . . Configuring the SQL files supplied with the NBI Deploying the Web application within Tomcat . Configuring the interface . . . . . . . . . . . . . . . . . . . 1 2 2 2 3 3 3 3 4 5 5 Making JAXWS-RI libraries available . . . RMI registry . . . . . . . . . . . Configuration . . . . . . . . . . . . MTOSI properties file . . . . . . . . NBI properties file . . . . . . . . . Mapping Netcool/OMNIbus data to MTOSI alarm format . . . . . . . . . . . Running the interface . . . . . . . . . Error messages . . . . . . . . . . . Notifications and fields supported . . . . . Operations supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6 6 6 7

12 14 15 19 19

Appendix. Notices and Trademarks . . 21


Notices . . . Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . 21 . 23

Copyright IBM Corp. 2006, 2008

iii

iv

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Document control page


Use this information to track changes between versions of this guide. The IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface documentation is provided in softcopy format only. To obtain the most recent version, visit the IBM Tivoli Information Center: http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/ com.ibm.tivoli.nam.doc/welcome_ptsm.htm
Table 1. Document modification history Document version 00 01 Publication date May 03, 2007 December 19, 2008 Comments First IBM publication. All required JAWS libraries included in the latest patch. Patch number and version updated. Description of Log.Level property updated. Default value of Notification.StateChange.Attributes property updated. NBI properties: Conversions.TableName, Conversions.RefreshInterval added.

Copyright IBM Corp. 2006, 2008

vi

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface


The Multi-Technology Operations System Interface (MTOSI) is a single standard that can connect together services and products from different vendors using different technologies. The IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface (NBI) enables the Tivoli Netcool/OMNIbus ObjectServer to communicate with clients that use the MTOSI protocol. This guide contains the following sections: v Summary v System overview on page 2 v Installation and configuration on page 3 v Configuration on page 6 v Running the interface on page 14 v Error messages on page 15 v Notifications and fields supported on page 19 v Operations supported on page 19

Summary
The following table provides a summary of the MTOSI NBI.
Table 2. Summary Interface target Executable names MTOSI version 1.1 nco_nbi (NBI) mtosi.war (Web application) Patch number Supported on 0.5 Solaris For details of the operating system versions on which this interface is supported on, see the following page on the IBM Tivoli Netcool Information Center: http://publib.boulder.ibm.com/infocenter/tivihelp/ v8r1/index.jsp?topic=/com.ibm.netcool_OMNIbus.doc/ Supported_Platforms.htm Configuration files webapp_install/mtosi/WEB-INF/nco_nbi_head.props webapp_install/mtosi/WEB-INF/nco_nbi.props webapp_install/mtosi/WEB-INF/MTOSI.map Where webapp_install is the direcory in which the Web application is installed.

Copyright IBM Corp. 2006, 2008

Table 2. Summary (continued) Requirements A currently supported version of IBM Tivoli Netcool/OMNIbus. Tomcat version 5.5 Java 1.5 JAXWS-RI version 2.1 Note: JAXWS is available from the following website: https://jax-ws.dev.java.net/ Remote connectivity Licensing No Electronic licensing was deprecated with the release of IBM Tivoli Netcool V7.2. All IBM Tivoli Netcool V7.2 (and later) products use the IBM software licensing process.

Peer-to-peer failover functionality Available IP environment Federal Information Protocol Standards (FIPS) IPv4 IBM Tivoli Netcool/OMNIbus V7.2.1 uses the FIPS 140-2 approved cryptographic provider: IBM Crypto for C (ICC) certificate 384 for cryptography. This certificate is listed on the NIST web site at http://csrc.nist.gov/ cryptval/140-1/1401val2004.htm For details about configuring Netcool/OMNIbus for FIPS 140-2 mode, see IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide (SC23-6370).

System overview
The Tivoli Netcool MTOSI NBI enables communication between an MTOSI client and the IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface ObjectServer. The interface consists of two parts: the Northbound Interface (NBI) nco_nbi (referred to as the body) and the MTOSI Web application (referred to as the head). These two parts communicate using Java Remote Method Invocation (RMI). Note: The head and the body must always be deployed as a matching pair. IBM does not support the of head and body with different versions.

MTOSI Web application


The head is a Web application (supplied in the installation patch as a WAR file) and is intended for deployment within an Apache Tomcat servlet container. It provides the MTOSI AlarmRetrieval (HTTP) and MTOSI NotificationProducer (HTTP) services and is the point through which MTOSI clients contact the NBI. The head communicates with the body using Java RMI function calls and uses the body to do most of the required processing; for example, providing lists of events for alarm retrieval requests, or subscribing clients for event notifications. The head is installed, run and managed using Apache Tomcat.

NBI
The body is a long running process responsible for processing queries on behalf of the head and producing notifications based on activity within the ObjectServer. It

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

requires specific tables and automations to be configured in the ObjectServer and maintains several connections to the ObjectServer whilst it is running. The body is responsible for notifying clients (subscribed using the MTOSI NotificationProducer service provided by the head) of event activity when appropriate. The body is a standalone Java process and can be started and managed as with other Tivoli Netcool/OMNIbus processes.

RMI registry
While not directly included in the system, both the head and the body use an RMI registry to locate each other at the time of initialization. An RMI registry server is a standard part of a Java Runtime Environment (JRE).

System diagram
The following figure shows the flow of information within the IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface.

Figure 1. IBM Tivoli Netcool/OMNIbus MTOSI NBI information flow

Installation and configuration


Install and configure the IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface to communicate with devices that use the MTOSI protocol. Perform the following steps to install and configure the MTOSI NBI: 1. Install the NBI. 2. Configure and run the SQL scripts supplied with the interface. 3. Deploy the MTOSI Web application within Tomcat. 4. Configure the MTOSI NBI. 5. Run rmiregistry. The following sections describe each of these steps.

Installing the NBI


This section provides instructions for installing the IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

To install the NBI, use the following steps: 1. Make sure you have an ObjectServer running. 2. Download the NBI patch (omnibus-3.x-arch-nbi-nco-nbi-0_1.tar.Z) to a temporary directory (for example, /tmp/). 3. Run the patch utility script in the $OMNIHOME/install directory using the following command:
$OMNIHOME/install/nco_patch -install /tmp/omnibus-3.x-arch-nbi-nco-nbi-0_1.tar.Z

Where /tmp/ is the temporary directory to which you downloaded the NBI patch. 4. Type Y when prompted to confirm that you want install the interface.

Configuring the SQL files supplied with the NBI


The NBI is supplied with a sample SQL script for creating the alert history table and associated triggers within the ObjectServer required by the interface. The default SQL file will also create an empty conversions.mtosi_nbi table. This table enables certain data conversions to take place between fields. This conversion table contains the following syntax:
create database conversions; go create table conversions.mtosi_nbi persistent ( KeyField varchar(255) primary key, Colname varchar(255), OSValue varchar(255), Conversion varchar(255) ); go

The script is installed in the following location:


$OMNIHOME/nbi/nbi.sql

This script creates the alerts.nbi_status table, the nbi_triggers group, and the following triggers required by the NBI: v nbi_insert v nbi_housekeeping v nbi_update v nbi_delete v nbi_deduplication If you have changed the default alerts schema, you will need to edit this file to reflect these changes. The triggers in the sample SQL script only contain the fields required by the example NBI configuration provided. You can add additional fields to the triggers as required. Note: The NBI is supplied with a new deduplication trigger. As you should only have one deduplication trigger active, you should disable the default deduplication trigger. If you have made any customizations, you must make corresponding changes to the new trigger.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Once you have customized the SQL script, you can run it using nco_sql. For details of nco_sql, see the IBM Tivoli Netcool/OMNIbus Administration Guide.

Deploying the Web application within Tomcat


The NBI is supplied with a WAR file containing the Web application. It is installed in the following location: $OMNIHOME/nbi/webapps/mtosi.war. This application must be deployed within Tomcat. To do so, follow the instructions in your Tomcat administration documentation. One method of deploying the application may be to use the Tomcat Application Manager: 1. Start the Tomcat Application Manager. 2. Under Deploy war file to deploy, enter the pathname of the WAR file. 3. Select Deploy. The Tomcat Application Manager displays the Netcool MTOSI Interface in the list of web applications. Note: To display the version of the MTOSI Web application that you have deployed, access the base Web page of the application and view the page source. The build number appears as a comment after the title. This information may be useful for troubleshooting purposes.

Making Java libraries available


Before starting the MTOSI Web application, you must make available the following Java libraries from the JAXWS-RI project:
activation.jar jaxb-api.jar jaxb-impl.jar jaxws-api.jar jaxws-rt.jar jsr173_api.jar jsr181-api.jar jsr250-api.jar resolver.jar saaj-api.jar saaj-impl.jar sjsxp.jar stax-ex.jar streambuffer.jar

To do so, copy these JAR files from $OMNIHOME/nbi/lib to $CATALINA_HOME/shared/lib and restart Tomcat.

Configuring the interface


The IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface is configured using the following configuration files: v nco_nbi_head.props (used to configure the MTOSI web application) v nco_nbi.props (used to configure the NBI) v MTOSI.map (used to create mappings between the fields within the ObjectServer and the fields within MTOSI events)

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

You can now use an XPath expression in a mapping to use a subset of text from an ObjectServer field. Use the syntax XPATH{xpath expression}. Note this feature can not be used in the same mapping pair as the SPLIT keyword. You must adjust these configuration files to suit your local environment. For details of these configuration files, see Configuration.

Making JAXWS-RI libraries available


nco_nbi requires the following Java libraries from the JAXWS-RI project to be available at run time:
tmf854.jar nco_nbi.jar activation.jar jaxsb-api.jar jaxsb-impl.jar jaxws-api.jar jaxws-rt.jar jsr173_api.jar resolver.jar sjsxp.jar

These JAR files can be found in the $OMNIHOME/nbi/lib directory. To make them available, set your CLASSPATH environment variable to include these JAR files before starting nco_nbi.

Setting environment variables automatically


You can include the location of these JAR files in an environment variables file (nco_nbi.env) written in Bourne shell compatible syntax. If you place this file in the $OMNIHOME/nbi/ directory, it will run automatically before starting nco_nbi. This enables you to run the NBI without having to set the environment variables manually.

RMI registry
While not directly included in the system, both the head and the body use an RMI registry to locate each other at the time of initialization. An RMI registry server is a standard part of a Java Runtime Environment (JRE).

Configuration
The following sections describe how to configure the IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: This section contains the following topics: v MTOSI properties file v NBI properties file on page 7 v Mapping Netcool/OMNIbus data to MTOSI alarm format on page 12

MTOSI properties file


The MTOSI Web application properties file (nco_nbi_head.props) contains the properties required to enable the MTOSI web application to communicate with the NBI.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

You must ensure that the values that you set within this file match those set for the corresponding properties in the NBI properties file (nco_nbi.props).

Properties
The following table describes the properties used to configure the NBI:
Table 3. MTOSI web application properties Property name NBI.Rmi. NotificationMgr.Name Description Name of the process with which the RMI middleware communicates to send notifications. The default is NBI.NotificationMgr. NBI.Rmi.Resync.Name Name of the process with which the RMI middleware communicates to make resynchronization requests. The default is NBI.ResyncMgr. NBI.Rmi.Registry.Host Host on which the RMI middleware registry is running. The default is localhost. NBI.Rmi.Registry.Port Port number of the RMI registry. The default is 1099.

NBI properties file


The Tivoli Netcool MTOSI Northbound Interface supports the following command line options: -version, -help, -props, and -dumpprops. The NBI is instead configured using a properties file. This is a text file that contains a set of properties and their corresponding values. These properties define how data stored in the ObjectServer is manipulated to make it compatible with the MTOSI protocol. An example properties file is installed in the following location:
$OMNIHOME/nbi/nbi.props

You must copy this file and make changes appropriate to your environment. Points to note: v Environment variables are expanded when the NBI reads the properties file. . v Any properties that you want to set to an empty string should be left blank; the interface does not support the syntax. v The default location for the properties file for the interface is:
$OMNIHOME/etc/nbi.props

v The Resync.Filter properties control the mapping of fields between the ObjectServer table (specified by the Resync.TableName property) and MTOSI fields used in resynchronization filters. In most configurations, these settings will mirror settings in the MTOSI.map file. v Ensure the RMI settings in the nco_nbi.props file match those set in the nco_nbi_head.props file.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

Properties
The following table describes the properties used to configure the NBI.
Table 4. NBI properties Property name Conversions.TableName Description Use this property to specify the table used. The default is conversions.mtosi_nbi. Note: The conversion table support is disabled if this property is not set. Conversions.RefreshInterval Use this property to refresh the NBI cache periodically. To disable the refresh of the cache, set this property to 0. The default is 300. Log.FileName Use this property to specify the name of the file that the interface uses to log debug messages. The default is $OMNIHOME/log/nco_nbi.log. Log.Level Use this property to specify the level of error messages that the interface logs. The possible values are v INFO v DEBUG_MAX v DEBUG_MIN The default is INFO. Log.MaxSize Use this property to specify the maximum size (in kilobytes) that the interface allows for the log file. The default is 1024. MappingFile Use this property to specify the name of the file that the interface uses to map fields in the ObjectServer to fields in MTOSI formatted messages. The default is MTOSI.map. Notification.MaxQueueSize Use this property to specify the maximum number of messages that can be queued for a subscribed client. This property can be used to prevent slow clients from exhausting all available memory. When the maximum number of events is reached, all new events for that client are dropped. The default is 100. Notification.RmiBindingName Use this property to specify the name of the process with which the RMI middleware communicates to send notifications. The default is NBI.NotificationMgr. Notification.StateChange. Attributes Use this property to specify the attributes of the notification which, when changed, trigger the creation of an MTOSI StateChange notification instead of an MTOSI AttributeValueChange notification. The default is PerceivedSeverity.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Table 4. NBI properties (continued) Property name Notification.TableName Description Use this property to specify the table in the ObjectServer to which the NBI sends details of notifications. The default is alerts.nbi_status. OS.Host Use this property to specify the host on which the ObjectServer is running The default is localhost. OS.Port Use this property to specify the port on the ObjectServer host on which the interface listens for alerts. The default is 4100. OS.Username Use this property to specify the username used to log in to the ObjectServer. The default is root. OS.Password Use this property to specify the password used to authenticate the OS.Username. By default, this property value is omitted. OS.SplitPattern Use this property to specify the character used to separate the values within a multi-value MTOSI field when it is mapped to a single value ObjectServer field. The default is ; (the semicolon character). Resync.TableName Use this property to specify the table in the ObjectServer with which the MTOSI resynchronizes. The default is alerts.status. Resync.RmiBindingName Use this property to specify the name of the process with which the RMI middleware communicates to make resynchronization requests. The default is NBI.ResyncMgr. Resync.Filter.Acknowledge Indication Use this property to specify the field within the ObjectServer that corresponds to the MTOSI AcknowledgeIndication field of the filter used when performing resynchronization. The default is Acknowledge. Resync.Filter.InternalAlarm SourceSQL . Use this property to specify the where clause that selects internal alarms. The interface uses this when source is set to internal in an Active Alarm Filter The default is Manager = ConnectionWatch OR Manager = SecurityWatch OR Manager = ProbeWatch. Resync.Filter.ProbableCause. Type Use this property to specify the field within the ObjectServer that corresponds to ProbableCause within MTOSI. The default is ProbableCause.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

Table 4. NBI properties (continued) Property name Resync.Filter.Scope.osNm Description Use this property to specify the field in the ObjectServer with which the MTOSI osNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.mdNm Use this property to specify the field in the ObjectServer with which the MTOSI mdNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.meNm Use this property to specify the field in the ObjectServer with which the MTOSI meNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.ehNm Use this property to specify the field in the ObjectServer with which the MTOSI ehNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.eqNm Use this property to specify the field in the ObjectServer with which the MTOSI eqNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.ptpNm Use this property to specify the field in the ObjectServer with which the MTOSI ptpNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter. Scope.ftpNm Use this property to specify the field in the ObjectServer with which the MTOSI ftpNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.ctpNm Use this property to specify the field in the ObjectServer with which the MTOSI ctpNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization The default is Node. Resync.Filter.Scope.tppoolNm Use this property to specify the field in the ObjectServer with which the MTOSI tppoolNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node.

10

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Table 4. NBI properties (continued) Property name Resync.Filter.Scope.pgpNm Description Use this property to specify the field in the ObjectServer with which the MTOSI pgpNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.epgpNm Use this property to specify the field in the ObjectServer with which the MTOSI epgpNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.mlsnNm Use this property to specify the field in the ObjectServer with which the MTOSI mlsnNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter. Scope.sncNm Use this property to specify the field in the ObjectServer with which the MTOSI sncNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.tmdNm Use this property to specify the field in the ObjectServer with which the MTOSI tmdNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.tlNm Use this property to specify the field in the ObjectServer with which the MTOSI tlNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.aidNm Use this property to specify the field in the ObjectServer with which the MTOSI aidNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Scope.propNm Use this property to specify the field in the ObjectServer with which the MTOSI propNm field in the filter is compared to determine whether to select the ObjectServer alert for resynchronization. The default is Node. Resync.Filter.Severity Use this property to specify the field within the ObjectServer that corresponds to the ResyncFilter field of the filter used when performing resynchronization. The default is Severity.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

11

Table 4. NBI properties (continued) Property name Resync.Filter.Severity.Critical Description Use this property to specify the value in the ObjectServer that corresponds to Critical within the filter used when performing resynchronization. The default is 5. Resync.Filter.Severity.Major. Use this property to specify the value in the ObjectServer that corresponds to Major within the filter used when performing resynchronization. The default is 4. Resync.Filter.Severity.Minor Use this property to specify the value in the ObjectServer that corresponds to Minor within the filter used when performing resynchronization. The default is 3. Resync.Filter. Severity.Warning Use this property to specify the value in the ObjectServer that corresponds to Warning within the filter used when performing resynchronization. The default is 2. Resync.Filter. Severity.Indeterminate Use this property to specify the value in the ObjectServer that corresponds to Indeterminate within the filter used when performing resynchronization. The default is 1. Resync.Filter. Severity.Cleared Use this property to specify the value in the ObjectServer that corresponds to Cleared within the filter used when performing resynchronization. The default is 0. Rmi.Registry.Host Use this property to specify the host on which the RMI middleware registry is running. The default is localhost. Rmi.Registry.Port Use this property to specify the port number of the RMI registry. The default is 1099.

Mapping Netcool/OMNIbus data to MTOSI alarm format


Mappings between the Netcool/OMNIbus to MTOSI use the following syntax:
CREATE MAPPING MTOSIAlarmNotificationMap ( 'notificationId' = '@EventId' MANDATORY, CREATE MAPPING MTOSIAVCNotificationMap ( 'notificationId' = '@EventId' MANDATORY, CREATE MAPPING MTOSIStateChangeNotificationMap ( 'notificationId' = '@EventId' MANDATORY,

12

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Example
Following is a sample mappings in the MTOSI.map file:
# # Example configuration for the MTOSI NBI # # CREATE MAPPING MTOSIAlarmNotificationMap ( 'notificationId' = '@EventId' MANDATORY, # ObjectName is a complex type, its components are listed here. 'osNm' = '@Node' MANDATORY, 'mdNm' = '@Node' MANDATORY, 'meNm' = '@Node' MANDATORY, 'ehNm' = '@Node' MANDATORY, 'eqNm' = '@Node' MANDATORY, 'ptpNm' = '@Node' MANDATORY, 'ftpNm' = '@Node' MANDATORY, 'ctpNm' = '@Node' MANDATORY, 'tppoolNm' = '@Node' MANDATORY, 'pgpNm' = '@Node' MANDATORY, 'epgpNm' = '@Node' MANDATORY, 'mlsnNm' = '@Node' MANDATORY, 'sncNm' = '@Node' MANDATORY, 'tmdNm' = '@Node' MANDATORY, 'tlNm' = '@Node' MANDATORY, 'aidNm' = '@Node' MANDATORY, 'propNm' = '@Node' MANDATORY, # 'objectName' = '@Identifier' MANDATORY, 'objectType' = '@Node' MANDATORY, 'osTime' = '@InternalLast' CONVERT TO DATE MANDATORY, 'neTime' = '@FirstOccurrence' CONVERT TO DATE MANDATORY, 'layerRate' = '@Agent' MANDATORY, 'aliasNameList' = '@NodeAlias' MANDATORY SPLIT, 'nativeProbableCause' = '@AlertGroup' MANDATORY, 'isClearable' = '@Summary' MANDATORY, 'probableCause' = '@X733ProbableCause' MANDATORY, 'perceivedSeverity' = '@Severity' MANDATORY, 'serviceAffecting' = '@Poll' MANDATORY, 'additionalText' = '@Summary' MANDATORY, 'rcaiIndicator' = '@Tally' MANDATORY ); CREATE MAPPING MTOSIAVCNotificationMap ( # Mandatory attributes 'notificationId' = '@EventId' MANDATORY, 'osNm' = '@Node' MANDATORY, 'mdNm' = '@Node' MANDATORY, 'meNm' = '@Node' MANDATORY, 'ehNm' = '@Node' MANDATORY, 'eqNm' = '@Node' MANDATORY, 'ptpNm' = '@Node' MANDATORY, 'ftpNm' = '@Node' MANDATORY, 'ctpNm' = '@Node' MANDATORY, 'tppoolNm' = '@Node' MANDATORY, 'pgpNm' = '@Node' MANDATORY, 'epgpNm' = '@Node' MANDATORY, 'mlsnNm' = '@Node' MANDATORY, 'sncNm' = '@Node' MANDATORY, 'tmdNm' = '@Node' MANDATORY, 'tlNm' = '@Node' MANDATORY, 'aidNm' = '@Node' MANDATORY, 'propNm' = '@Node' MANDATORY, #'objectName' = '@Identifier' MANDATORY, 'objectType' = '@Node' MANDATORY,
IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

13

'osTime' = '@InternalLast' CONVERT TO DATE MANDATORY, 'neTime' = '@FirstOccurrence' CONVERT TO DATE MANDATORY, # # Then, we have the optional attributes that would have changed so need # to put them all here, so that we can identify which one has changed # 'layerRate' = '@Agent', 'aliasNameList' = '@AlertGroup', 'nativeProbableCause' = '@AlertGroup', 'isClearable' = '@Summary', 'probableCause' = '@X733ProbableCause', 'perceivedSeverity' = '@Severity', 'serviceAffecting' = '@Poll', 'additionalText' = '@Summary', 'rcaiIndicator' = '@Tally' ); CREATE MAPPING MTOSIStateChangeNotificationMap ( # Mandatory attributes 'notificationId' = '@EventId' MANDATORY, 'osNm' = '@Node' MANDATORY, 'mdNm' = '@Node' MANDATORY, 'meNm' = '@Node' MANDATORY, 'ehNm' = '@Node' MANDATORY, 'eqNm' = '@Node' MANDATORY, 'ptpNm' = '@Node' MANDATORY, 'ftpNm' = '@Node' MANDATORY, 'ctpNm' = '@Node' MANDATORY, 'tppoolNm' = '@Node' MANDATORY, 'pgpNm' = '@Node' MANDATORY, 'epgpNm' = '@Node' MANDATORY, 'mlsnNm' = '@Node' MANDATORY, 'sncNm' = '@Node' MANDATORY, 'tmdNm' = '@Node' MANDATORY, 'tlNm' = '@Node' MANDATORY, 'aidNm' = '@Node' MANDATORY, 'propNm' = '@Node' MANDATORY, #'objectName' = '@Identifier' MANDATORY, 'objectType' = '@Node' MANDATORY, 'osTime' = '@InternalLast' CONVERT TO DATE MANDATORY, 'neTime' = '@FirstOccurrence' CONVERT TO DATE MANDATORY, # # Then, we have the optional attributes that would have changed so need # to put them all here, so that we can identify which one has changed # 'layerRate' = '@Agent', 'aliasNameList' = '@AlertGroup', 'nativeProbableCause' = '@AlertGroup', 'isClearable' = '@Summary', 'probableCause' = '@X733ProbableCause', 'perceivedSeverity' = '@Severity', 'serviceAffecting' = '@Poll', 'additionalText' = '@Summary', 'rcaiIndicator' = '@Tally' );

Running the interface


To run the interface, use the following steps: 1. Execute the following command:
$OMNIHOME/bin/nco_nbi -props filename

14

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Where filename is the path to the NBI properties file. If you omit the -props option, the NBI uses $OMNIHOME/etc/nco_nbi.props. If $OMNIHOME is not set, the NBI uses /opt/netcool/omnibus/etc/nco_nbi.props. Note: Depending on your local environment, you may need to set the JAVA_HOME environment variable. 2. Start the Netcool MTOSI Interface Web application. For details about doing this, see your Tomcat documentation. By default the published path of the AlarmRetrieval service is /mtosi/v1/AlarmRetrieval and the published path of the NotificationProducer service is mtosi/v1/NotificationProducer. Once the Tivoli Netcool MTOSI NBI is running, it will be able to accept resynchronization requests and subscription requests, and to forward events to an MTOSI client.

Error messages
Error messages provide information about the problems that occur while running the produt, You can use the information that they contain to resolve such problems. The following table describes the error messages specific to this probe. For information about generic error messages, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide, (SC23-6373).
Table 5. Error messages Error duplicate field mtosi_field found in map mapping_name Description The field mtosi_field occurs more than once in the mapping mapping_name. Action Edit the mapping file to fix the problem. Each MTOSI field can only be listed once in each mapping defined in the mapping file. Restart the MTOSI NBI. If the problem persists, contact IBM Support. Restart the MTOSI NBI. If the problem persists, contact IBM Support. Check that the OS.Username and OS.Password properties are set correctly. Check that the OS.Username and OS.Password properties are set correctly. This is an internal problem. If the problem persists, contact IBM Support. Check your Netcool/OMNIbus installation. The jConn3.jar file should be located in $OMNIHOME/java/jars.

error while trying to start a thread: description fatal error encountered. shutting down IDUCMgr: failed to connect to ObjectServer IDUCMgr: failed to connect to server: server_name IDUCMgr: failed to connect to server: server_name IDUCMgr: failed to load sybase connection driver : driver_name

The body is shutting down due to an error that occurred when a subsystem started. The body is shutting down due to an error. The NBI failed to connect.

The NBI could not connect to the Object Server. Indicates that the NBI had problems closing its IDUC connection to the ObjectServer. The NBI could not load the com.sybase.jdbc2.jdbc. SybDriver class. .

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

15

Table 5. Error messages (continued) Error main thread has been interrupted during shutdown: description NewAlarm: it should look like this : aliasname;aliasvalue ;aliasname;aliasvalue ... NewAlarm: the aliasNameList field does not have the expected format, therefore cannot be used. Ignoring Description Action

The body is shutting down Restart the MTOSI NBI. If the due to an error that occurred problem persists, contact IBM when a subsystem shut down. Support. The aliasNameList field has not been correctly encoded in the ObjectServer. Note: These two messages will always appear together. Check in the mapping file, to see which ObjectServer field is mapped to the MTOSI field AliasNameList. Then check that this ObjectServer field has the following format: aliasname;aliasvalue; aliasname;aliasvalue ... Note: There should be an even number of strings since this field should contain a set of name/value pairs. If these values are not correctly encoded, it is likely that there is an error in the rules file of the client feeding data into the ObjectServer. The semicolon (;) in the above examples is the character specified by the OS.SplitPattern property. The character need not be a semicolon.

NotificationBuilder: exception in forward_updated_event : event_number NotificationBuilder: exception in NotificationBuilder: sendSQLRequest : sql_request NotificationBuilder: SQLCmdMgr couldnt handle the query, therefore dropping the JobRequest

There was a problem while trying to build an MTOSI AVC or SC. The event has been dropped.

This is an internal problem. If the problem persists, contact IBM Support.

This is an internal problem. If The NBI has generated an SQL exception while trying to the problem persists, contact IBM Support. execute an SQL request. Note: These two messages will always appear together.

16

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Table 5. Error messages (continued) Error Description Action Check that the RMI registry process is running. Check that the RMI.Registry.Host and RMI.Registry.Port properties are set to the correct values. Check that there is not another instance of nco_nbi running in the background (there may already be an object registered with the name specified by the Notification.RmiBinding Name property). This is an internal problem. If the problem persists, contact IBM Support.

NotificationMgr : The NBI could not be exception raised while registered with the RMI trying to register object registry process. with rmi registry : object_name

NotificationMgr: exception in getAlarm : alarm_number

The Interrupted Exception message is generated when one thread is waiting to get an alarm from the queue and another thread calls the interrupt method to interrupt the wait.

An external client could not NotificationMgr: exception while trying to subscribe to the NBI for notifications. The exception add the new probably occurred during the SubscribedClient : initialization of the subscribed_client SubscribedClient object. . The NBI could not remove NotificationMgr: exception while trying to the subscription from a remote client. removeClient : subscribed_client ResyncMgr object failed to bind to RMI registry The NBI could not be registered with the RMI registry process.

Check the wsdlocation, filter, and topic provided by the remote client.

Check whether the client has already been unsubscribed from notifications. Check that the RMI registry process is running, and that RMI.Registry.Host and RMI.Registry.Port properties are set to the correct values. Check that there is not another instance of nco_nbi running in the background (there may already be an object registered with the name specified by the Resync.RmiBindingName property). Check that there are no problems in the mapping file. Check for references to nonexistent ObjectServer fields, invalid conversions being attempted, and so forth. For details of the syntax of the mapping file, see Mapping Netcool/OMNIbus data to MTOSI alarm format on page 12.

ResyncMgr: exception in the mapping: mapping_name, ignoring current event

The NBI generated an exception while trying to build an MTOSI alarm from an ObjectServer alarm.

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

17

Table 5. Error messages (continued) Error ResyncMgr: exception while trying to bind ResyncMgr to RMI registry: registry_entry Description The NBI could not be registered with the RMI registry process. Check that the RMI registry process is running, and that RMI.Registry.Host and RMI.Registry.Port properties are set to the correct values. The NBI received a get_ active_alarms_iterator call with an unknown URI provided as a parameter. There is a problem with the MTOSI client. Action Check that there is not another instance of nco_nbi running in the background (there may already be an object registered with the name specified by the Resync.RmiBindingName property). The remote client should reuse the IteratorReferenceURI returned in the header of the get_active_alarms method by the NBI, to set the corresponding field of the header for the get_ active_alarms_iterator function call. The remote client should reuse the IteratorReferenceURI returned in the header of the get_active_alarms method by the NBI, to set the corresponding field of the header for the get_active_ alarms_iterator function call. This usually indicates a client problem. Check that the Web service server in the remote client is running. Restart the MTOSI NBI. If the problem persists, contact IBM Support. Check the resolver setup for your operating system and/or JRE.

ResyncMgr: the following key uri_reference doesnt appear in the clients table

ResyncMgr: the following uri uri_reference doesnt appear in the clients table, therefore returning an empty vehicle

The NBI received a get_ active_alarms_iterator call with an unknown URI provided as a parameter. There is a problem with the MTOSI client.

The NBI could not call the SubscribedClient: exception while trying to notify method on the remote notify external client : client (Web service). subscribed_client Thread has terminated The body is shutting down unexpectedly: description due to an error that occurred when a subsystem started or shut down. Unable to determine the local host name - using amnesiac The body was unable to determine the hostname of the machine on which it is running. It will try to continue.

Utils: buildHashTables, exception while building ResultSet object into a Hashtable : table_name

The NBI encountered a This is an internal problem. If problem while trying to build the problem persists, contact IBM Support. a hashtable from the ResultSet returned by the SQL query on the ObjectServer.

18

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Notifications and fields supported


The IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface supports alarm notification fields, attribute value change notification fields, and state change notification fields. Alarm notification fields supported: v notificationID v objectName v objectType v osTime v v v v v v v neTime layerRate aliasNameList nativeProbableCause isClearable probableCause perceivedSeverity

v serviceAffectingr v additionalText v rcaiIndicato Attribute value change notification fields supported: v notificationID v objectName v objectType v osTime v neTime v attributeList (will include changes on one of the attributes supported by the alarm notification). State change notification fields supported: v notificationID v v v v v objectName objectType osTime neTime attributeList (will include changes on one of the attributes supported by the alarm notification).

Operations supported
The MTOSI NBI supports various alarm retrieval and notification broker operations. Alarm retrieval operations supported: v getActiveAlarms v getActiveAlarmsCount

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface

19

Notification broker operartions supported: v subscribe v unsubscribe v notify

20

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Appendix. Notices and Trademarks


This appendix contains the following sections: v Notices v Trademarks

Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Copyright IBM Corp. 2006, 2008

21

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Software Interoperability Coordinator, Department 49XA 3605 Highway 52 N Rochester, MN 55901 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBMs future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. All IBM prices shown are IBMs suggested retail prices, are current and are subject to change without notice. Dealer prices may vary. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

22

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Trademarks
IBM, the IBM logo, ibm.com, AIX, Tivoli, zSeries, and Netcool are trademarks of International Business Machines Corporation in the United States, other countries, or both. Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based trademarks are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both. Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, or service names may be trademarks or service marks of others.

Appendix. Notices and Trademarks

23

24

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

Printed in USA

SC23-6097-01