mtosi-pdf (1)

Tivoli® Netcool/OMNIbus MTOSI Northbound Interface

Reference GuideDecember 19, 2008

Version 0.0.5900

SC23-6097-01

��

NoteBefore 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 Contractwith IBM Corp.

Contents

Document control page . . . . . . . . v

IBM Tivoli Netcool/OMNIbus MTOSINorthbound Interface . . . . . . . . . 1Summary . . . . . . . . . . . . . . . 1System overview . . . . . . . . . . . . . 2

MTOSI Web application . . . . . . . . . 2NBI . . . . . . . . . . . . . . . . 2RMI registry . . . . . . . . . . . . . 3System diagram . . . . . . . . . . . . 3

Installation and configuration. . . . . . . . . 3Installing the NBI. . . . . . . . . . . . 3Configuring the SQL files supplied with the NBI . 4Deploying the Web application within Tomcat . . 5Configuring the interface . . . . . . . . . 5

Making JAXWS-RI libraries available . . . . . 6RMI registry . . . . . . . . . . . . . 6

Configuration . . . . . . . . . . . . . . 6MTOSI properties file . . . . . . . . . . 6NBI properties file . . . . . . . . . . . 7Mapping Netcool/OMNIbus data to MTOSIalarm format . . . . . . . . . . . . . 12

Running the interface . . . . . . . . . . . 14Error messages . . . . . . . . . . . . . 15Notifications and fields supported . . . . . . . 19Operations supported . . . . . . . . . . . 19

Appendix. Notices and Trademarks . . 21Notices . . . . . . . . . . . . . . . . 21Trademarks . . . . . . . . . . . . . . 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 isprovided 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

Documentversion

Publicationdate

Comments

00 May 03, 2007 First IBM publication.

01 December 19,2008

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

NBI properties: Conversions.TableName,Conversions.RefreshInterval added.

© Copyright IBM Corp. 2006, 2008 v



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 standardthat can connect together services and products from different vendors usingdifferent technologies.

The IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface (NBI) enables theTivoli Netcool/OMNIbus ObjectServer to communicate with clients that use theMTOSI protocol.

This guide contains the following sections:v “Summary”v “System overview” on page 2v “Installation and configuration” on page 3v “Configuration” on page 6v “Running the interface” on page 14v “Error messages” on page 15v “Notifications and fields supported” on page 19v “Operations supported” on page 19

Summary

The following table provides a summary of the MTOSI NBI.

Table 2. Summary

Interface target MTOSI version 1.1

Executable names nco_nbi (NBI)

mtosi.war (Web application)

Patch number 0.5

Supported on Solaris

For details of the operating system versions on whichthis interface is supported on, see the following page onthe 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 Webapplication is installed.

© Copyright IBM Corp. 2006, 2008 1




Table 2. Summary (continued)

Requirements A currently supported version of IBM TivoliNetcool/OMNIbus.

Tomcat version 5.5

Java 1.5

JAXWS-RI version 2.1Note: JAXWS is available from the following website:https://jax-ws.dev.java.net/

Remote connectivity No

Licensing Electronic licensing was deprecated with the release ofIBM Tivoli Netcool V7.2. All IBM Tivoli Netcool V7.2(and later) products use the IBM software licensingprocess.

Peer-to-peer failover functionality Available

IP environment IPv4

Federal Information ProtocolStandards (FIPS)

IBM Tivoli Netcool/OMNIbus V7.2.1 uses the FIPS140-2 approved cryptographic provider: IBM Crypto forC (ICC) certificate 384 for cryptography. This certificateis listed on the NIST web site at http://csrc.nist.gov/cryptval/140-1/1401val2004.htm For details aboutconfiguring Netcool/OMNIbus for FIPS 140-2 mode, seeIBM Tivoli Netcool/OMNIbus Installation and DeploymentGuide (SC23-6370).

System overviewThe Tivoli Netcool MTOSI NBI enables communication between an MTOSI clientand 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. IBMdoes not support the of head and body with different versions.

MTOSI Web applicationThe 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 thebody to do most of the required processing; for example, providing lists of eventsfor alarm retrieval requests, or subscribing clients for event notifications. The headis installed, run and managed using Apache Tomcat.

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

2 IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface: Reference Guide

https://jax-ws.dev.java.net/

http://csrc.nist.gov/cryptval/140-1/1401val2004.htm

http://csrc.nist.gov/cryptval/140-1/1401val2004.htm

requires specific tables and automations to be configured in the ObjectServer andmaintains several connections to the ObjectServer whilst it is running.

The body is responsible for notifying clients (subscribed using the MTOSINotificationProducer service provided by the head) of event activity whenappropriate. The body is a standalone Java process and can be started andmanaged as with other Tivoli Netcool/OMNIbus processes.

RMI registryWhile not directly included in the system, both the head and the body use an RMIregistry 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 TivoliNetcool/OMNIbus MTOSI Northbound Interface.

Installation and configurationInstall and configure the IBM Tivoli Netcool/OMNIbus MTOSI NorthboundInterface 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 NBIThis section provides instructions for installing the IBM Tivoli Netcool/OMNIbusMTOSI Northbound Interface.

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

IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface 3

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

4. Type Y when prompted to confirm that you want install the interface.

Configuring the SQL files supplied with the NBIThe NBI is supplied with a sample SQL script for creating the alert history tableand associated triggers within the ObjectServer required by the interface.

The default SQL file will also create an empty conversions.mtosi_nbi table. Thistable 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 thefollowing 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 toreflect these changes. The triggers in the sample SQL script only contain the fieldsrequired by the example NBI configuration provided. You can add additional fieldsto the triggers as required.

Note: The NBI is supplied with a new deduplication trigger. As you should onlyhave one deduplication trigger active, you should disable the default deduplicationtrigger. If you have made any customizations, you must make correspondingchanges to the new trigger.


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

Deploying the Web application within TomcatThe 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 instructionsin your Tomcat administration documentation.

One method of deploying the application may be to use the Tomcat ApplicationManager: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 listof web applications.

Note: To display the version of the MTOSI Web application that you havedeployed, 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 beuseful for troubleshooting purposes.

Making Java libraries available

Before starting the MTOSI Web application, you must make available the followingJava libraries from the JAXWS-RI project:activation.jarjaxb-api.jarjaxb-impl.jarjaxws-api.jarjaxws-rt.jarjsr173_api.jarjsr181-api.jarjsr250-api.jarresolver.jarsaaj-api.jarsaaj-impl.jarsjsxp.jarstax-ex.jarstreambuffer.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 configuredusing 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)


You can now use an XPath expression in a mapping to use a subset of text from anObjectServer field. Use the syntax XPATH{xpath expression}. Note this feature cannot be used in the same mapping pair as the SPLIT keyword.

You must adjust these configuration files to suit your local environment. For detailsof these configuration files, see “Configuration.”

Making JAXWS-RI libraries available

nco_nbi requires the following Java libraries from the JAXWS-RI project to beavailable at run time:tmf854.jarnco_nbi.jaractivation.jarjaxsb-api.jarjaxsb-impl.jarjaxws-api.jarjaxws-rt.jarjsr173_api.jarresolver.jarsjsxp.jar

These JAR files can be found in the $OMNIHOME/nbi/lib directory. To makethem available, set your CLASSPATH environment variable to include these JAR filesbefore 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 inthe $OMNIHOME/nbi/ directory, it will run automatically before starting nco_nbi.This enables you to run the NBI without having to set the environment variablesmanually.

RMI registryWhile not directly included in the system, both the head and the body use an RMIregistry to locate each other at the time of initialization.

An RMI registry server is a standard part of a Java Runtime Environment (JRE).

ConfigurationThe following sections describe how to configure the IBM TivoliNetcool/OMNIbus MTOSI Northbound Interface:

This section contains the following topics:v “MTOSI properties file”v “NBI properties file” on page 7v “Mapping Netcool/OMNIbus data to MTOSI alarm format” on page 12

MTOSI properties fileThe MTOSI Web application properties file (nco_nbi_head.props) contains theproperties required to enable the MTOSI web application to communicate with theNBI.


You must ensure that the values that you set within this file match those set for thecorresponding 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 Description

NBI.Rmi.NotificationMgr.Name

Name of the process with which the RMI middlewarecommunicates to send notifications.

The default is NBI.NotificationMgr.

NBI.Rmi.Resync.Name Name of the process with which the RMI middlewarecommunicates 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 fileThe Tivoli Netcool MTOSI Northbound Interface supports the following commandline options: -version, -help, -props, and -dumpprops.

The NBI is instead configured using a properties file. This is a text file thatcontains a set of properties and their corresponding values. These properties definehow data stored in the ObjectServer is manipulated to make it compatible with theMTOSI 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. Pointsto 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 theObjectServer table (specified by the Resync.TableName property) and MTOSIfields used in resynchronization filters. In most configurations, these settings willmirror settings in the MTOSI.map file.

v Ensure the RMI settings in the nco_nbi.props file match those set in thenco_nbi_head.props file.


Properties

The following table describes the properties used to configure the NBI.

Table 4. NBI properties


Conversions.TableName Use this property to specify the table used.

The default is conversions.mtosi_nbi.Note: The conversion table support is disabled if thisproperty 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 theinterface uses to log debug messages.

The default is $OMNIHOME/log/nco_nbi.log.

Log.Level Use this property to specify the level of error messagesthat 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 (inkilobytes) that the interface allows for the log file.


MappingFile Use this property to specify the name of the file that theinterface uses to map fields in the ObjectServer to fieldsin MTOSI formatted messages.

The default is MTOSI.map.

Notification.MaxQueueSize Use this property to specify the maximum number ofmessages that can be queued for a subscribed client. Thisproperty can be used to prevent slow clients fromexhausting all available memory. When the maximumnumber of events is reached, all new events for thatclient are dropped.

The default is 100.

Notification.RmiBindingName Use this property to specify the name of the process withwhich the RMI middleware communicates to sendnotifications.

The default is NBI.NotificationMgr.

Notification.StateChange.Attributes

Use this property to specify the attributes of thenotification which, when changed, trigger the creation ofan MTOSI StateChange notification instead of an MTOSIAttributeValueChange notification.

The default is PerceivedSeverity.


Table 4. NBI properties (continued)


Notification.TableName Use this property to specify the table in the ObjectServerto which the NBI sends details of notifications.

The default is alerts.nbi_status.

OS.Host Use this property to specify the host on which theObjectServer is running


OS.Port Use this property to specify the port on the ObjectServerhost on which the interface listens for alerts.


OS.Username Use this property to specify the username used to log into the ObjectServer.

The default is root.

OS.Password Use this property to specify the password used toauthenticate the OS.Username.

By default, this property value is omitted.

OS.SplitPattern Use this property to specify the character used toseparate the values within a multi-value MTOSI fieldwhen 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 ObjectServerwith which the MTOSI resynchronizes.

The default is alerts.status.

Resync.RmiBindingName Use this property to specify the name of the process withwhich the RMI middleware communicates to makeresynchronization requests.

The default is NBI.ResyncMgr.

Resync.Filter.AcknowledgeIndication

Use this property to specify the field within theObjectServer that corresponds to the MTOSIAcknowledgeIndication field of the filter used whenperforming resynchronization.

The default is Acknowledge.

Resync.Filter.InternalAlarmSourceSQL .

Use this property to specify the where clause that selectsinternal alarms. The interface uses this when source isset 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 theObjectServer that corresponds to ProbableCause withinMTOSI.

The default is ProbableCause.




Resync.Filter.Scope.osNm Use this property to specify the field in the ObjectServerwith which the MTOSI osNm field in the filter is comparedto determine whether to select the ObjectServer alert forresynchronization.

The default is Node.

Resync.Filter.Scope.mdNm Use this property to specify the field in the ObjectServerwith which the MTOSI mdNm field in the filter is comparedto determine whether to select the ObjectServer alert forresynchronization.


Resync.Filter.Scope.meNm Use this property to specify the field in the ObjectServerwith which the MTOSI meNm field in the filter is comparedto determine whether to select the ObjectServer alert forresynchronization.


Resync.Filter.Scope.ehNm Use this property to specify the field in the ObjectServerwith which the MTOSI ehNm field in the filter is comparedto determine whether to select the ObjectServer alert forresynchronization.


Resync.Filter.Scope.eqNm Use this property to specify the field in the ObjectServerwith which the MTOSI eqNm field in the filter is comparedto determine whether to select the ObjectServer alert forresynchronization.


Resync.Filter.Scope.ptpNm Use this property to specify the field in the ObjectServerwith which the MTOSI ptpNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter. Scope.ftpNm Use this property to specify the field in the ObjectServerwith which the MTOSI ftpNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter.Scope.ctpNm Use this property to specify the field in the ObjectServerwith which the MTOSI ctpNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization


Resync.Filter.Scope.tppoolNm Use this property to specify the field in the ObjectServerwith which the MTOSI tppoolNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.





Resync.Filter.Scope.pgpNm Use this property to specify the field in the ObjectServerwith which the MTOSI pgpNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter.Scope.epgpNm Use this property to specify the field in the ObjectServerwith which the MTOSI epgpNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter.Scope.mlsnNm Use this property to specify the field in the ObjectServerwith which the MTOSI mlsnNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter. Scope.sncNm Use this property to specify the field in the ObjectServerwith which the MTOSI sncNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter.Scope.tmdNm Use this property to specify the field in the ObjectServerwith which the MTOSI tmdNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter.Scope.tlNm Use this property to specify the field in the ObjectServerwith which the MTOSI tlNm field in the filter is comparedto determine whether to select the ObjectServer alert forresynchronization.


Resync.Filter.Scope.aidNm Use this property to specify the field in the ObjectServerwith which the MTOSI aidNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter.Scope.propNm Use this property to specify the field in the ObjectServerwith which the MTOSI propNm field in the filter iscompared to determine whether to select theObjectServer alert for resynchronization.


Resync.Filter.Severity Use this property to specify the field within theObjectServer that corresponds to the ResyncFilter fieldof the filter used when performing resynchronization.

The default is Severity.




Resync.Filter.Severity.Critical Use this property to specify the value in the ObjectServerthat corresponds to Critical within the filter used whenperforming resynchronization.

The default is 5.

Resync.Filter.Severity.Major. Use this property to specify the value in the ObjectServerthat corresponds to Major within the filter used whenperforming resynchronization.

The default is 4.

Resync.Filter.Severity.Minor Use this property to specify the value in the ObjectServerthat corresponds to Minor within the filter used whenperforming resynchronization.

The default is 3.

Resync.Filter. Severity.Warning Use this property to specify the value in the ObjectServerthat corresponds to Warning within the filter used whenperforming resynchronization.

The default is 2.

Resync.Filter.Severity.Indeterminate

Use this property to specify the value in the ObjectServerthat corresponds to Indeterminate within the filter usedwhen performing resynchronization.

The default is 1.

Resync.Filter. Severity.Cleared Use this property to specify the value in the ObjectServerthat corresponds to Cleared within the filter used whenperforming resynchronization.

The default is 0.

Rmi.Registry.Host Use this property to specify the host on which the RMImiddleware registry is running.


Rmi.Registry.Port Use this property to specify the port number of the RMIregistry.


Mapping Netcool/OMNIbus data to MTOSI alarm formatMappings 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,


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,


'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


Where filename is the path to the NBI properties file. If you omit the -propsoption, the NBI uses $OMNIHOME/etc/nco_nbi.props. If $OMNIHOME is notset, the NBI uses /opt/netcool/omnibus/etc/nco_nbi.props.

Note: Depending on your local environment, you may need to set theJAVA_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 theNotificationProducer service is mtosi/v1/NotificationProducer.

Once the Tivoli Netcool MTOSI NBI is running, it will be able to acceptresynchronization requests and subscription requests, and to forward events to anMTOSI client.

Error messagesError messages provide information about the problems that occur while runningthe produt, You can use the information that they contain to resolve suchproblems.

The following table describes the error messages specific to this probe. Forinformation about generic error messages, see the IBM Tivoli Netcool/OMNIbusProbe and Gateway Guide, (SC23-6373).

Table 5. Error messages

Error Description Action

duplicate fieldmtosi_field found in mapmapping_name

The field mtosi_field occursmore than once in themapping mapping_name.

Edit the mapping file to fixthe problem. Each MTOSIfield can only be listed oncein each mapping defined inthe mapping file.

error while trying tostart a thread:description

The body is shutting downdue to an error that occurredwhen a subsystem started.

Restart the MTOSI NBI. If theproblem persists, contact IBMSupport.

fatal error encountered.shutting down

The body is shutting downdue to an error.


IDUCMgr: failed toconnect to ObjectServer

The NBI failed to connect. Check that the OS.Usernameand OS.Password propertiesare set correctly.

IDUCMgr: failed toconnect to server:server_name

The NBI could not connect tothe Object Server.

Check that the OS.Usernameand OS.Password propertiesare set correctly.

IDUCMgr: failed toconnect to server:server_name

Indicates that the NBI hadproblems closing its IDUCconnection to theObjectServer.

This is an internal problem. Ifthe problem persists, contactIBM Support.

IDUCMgr: failed to loadsybase connection driver: driver_name

The NBI could not load thecom.sybase.jdbc2.jdbc.SybDriver class. .

Check yourNetcool/OMNIbusinstallation. The jConn3.jarfile should be located in$OMNIHOME/java/jars.


Table 5. Error messages (continued)


main thread has beeninterrupted duringshutdown: description

The body is shutting downdue to an error that occurredwhen a subsystem shut down.


NewAlarm: it should looklike this :aliasname;aliasvalue;aliasname;aliasvalue ...

NewAlarm: thealiasNameList field doesnot have the expectedformat, therefore cannotbe used. Ignoring

The aliasNameList field hasnot been correctly encoded inthe ObjectServer.Note: These two messageswill always appear together.

Check in the mapping file, tosee which ObjectServer fieldis mapped to the MTOSI field

AliasNameList. Then checkthat this ObjectServer fieldhas the following format:

aliasname;aliasvalue;aliasname;aliasvalue ...

Note: There should be aneven number of strings sincethis field should contain a setof name/value pairs.

If these values are notcorrectly encoded, it is likelythat there is an error in therules file of the client feedingdata into the ObjectServer.

The semicolon (;) in the aboveexamples is the characterspecified by theOS.SplitPattern property. Thecharacter need not be asemicolon.

NotificationBuilder:exception inforward_updated_event :event_number

There was a problem whiletrying to build an MTOSIAVC or SC. The event hasbeen dropped.


NotificationBuilder:exception inNotificationBuilder:sendSQLRequest :sql_request

NotificationBuilder:SQLCmdMgr couldn’t handlethe query, thereforedropping the JobRequest

The NBI has generated anSQL exception while trying toexecute an SQL request.Note: These two messageswill always appear together.





NotificationMgr :exception raised whiletrying to register objectwith rmi registry :object_name

The NBI could not beregistered with the RMIregistry process.

Check that the RMI registryprocess is running. Check thatthe RMI.Registry.Host andRMI.Registry.Port propertiesare set to the correct values.Check that there is notanother instance of nco_nbirunning in the background(there may already be anobject registered with thename specified by theNotification.RmiBindingName property).

NotificationMgr:exception in getAlarm :alarm_number

The Interrupted Exceptionmessage is generated whenone thread is waiting to getan alarm from the queue andanother thread calls theinterrupt method to interruptthe wait.


NotificationMgr:exception while trying toadd the newSubscribedClient :subscribed_client

An external client could notsubscribe to the NBI fornotifications. The exceptionprobably occurred during theinitialization of theSubscribedClient object. .

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

NotificationMgr:exception while trying toremoveClient :subscribed_client

The NBI could not removethe subscription from aremote client.

Check whether the client hasalready been unsubscribedfrom notifications.

ResyncMgr object failedto bind to RMI registry

The NBI could not beregistered with the RMIregistry process.

Check that the RMI registryprocess is running, and thatRMI.Registry.Host andRMI.Registry.Port propertiesare set to the correct values.Check that there is notanother instance of nco_nbirunning in the background(there may already be anobject registered with thename specified by theResync.RmiBindingNameproperty).

ResyncMgr: exception inthe mapping:mapping_name, ignoringcurrent event

The NBI generated anexception while trying tobuild an MTOSI alarm froman ObjectServer alarm.

Check that there are noproblems in the mapping file.Check for references tononexistent ObjectServerfields, invalid conversionsbeing attempted, and so forth.For details of the syntax ofthe mapping file, see“Mapping Netcool/OMNIbusdata to MTOSI alarm format”on page 12.




ResyncMgr: exceptionwhile trying to bindResyncMgr to RMIregistry: registry_entry

The NBI could not beregistered with the RMIregistry process. Check thatthe RMI registry process isrunning, and thatRMI.Registry.Host andRMI.Registry.Port propertiesare set to the correct values.

Check that there is notanother instance of nco_nbirunning in the background(there may already be anobject registered with thename specified by theResync.RmiBindingNameproperty).

ResyncMgr: the followingkey uri_reference doesn’tappear in the clientstable

The NBI received a get_active_alarms_iterator callwith an unknown URIprovided as a parameter.There is a problem with theMTOSI client.

The remote client shouldreuse theIteratorReferenceURIreturned in the header of theget_active_alarms method bythe NBI, to set thecorresponding field of theheader for the get_active_alarms_iteratorfunction call.

ResyncMgr: the followinguri uri_reference doesn’tappear in the clientstable, thereforereturning an emptyvehicle

The NBI received a get_active_alarms_iterator callwith an unknown URIprovided as a parameter.There is a problem with theMTOSI client.

The remote client shouldreuse theIteratorReferenceURIreturned in the header of theget_active_alarms method bythe NBI, to set thecorresponding field of theheader for the get_active_alarms_iterator function call.

SubscribedClient:exception while trying tonotify external client :subscribed_client

The NBI could not call thenotify method on the remoteclient (Web service).

This usually indicates a clientproblem. Check that the Webservice server in the remoteclient is running.

Thread has terminatedunexpectedly: description

The body is shutting downdue to an error that occurredwhen a subsystem started orshut down.


Unable to determine thelocal host name - usingamnesiac

The body was unable todetermine the hostname ofthe machine on which it isrunning. It will try tocontinue.

Check the resolver setup foryour operating system and/orJRE.

Utils: buildHashTables,exception while buildingResultSet object into aHashtable : table_name

The NBI encountered aproblem while trying to builda hashtable from theResultSet returned by theSQL query on theObjectServer.



Notifications and fields supportedThe IBM Tivoli Netcool/OMNIbus MTOSI Northbound Interface supports alarmnotification fields, attribute value change notification fields, and state changenotification fields.

Alarm notification fields supported:v notificationID

v objectName

v objectType

v osTime

v neTime

v layerRate

v aliasNameList

v nativeProbableCause

v isClearable

v probableCause

v 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 thealarm notification).

State 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 thealarm notification).

Operations supportedThe MTOSI NBI supports various alarm retrieval and notification brokeroperations.

Alarm retrieval operations supported:v getActiveAlarmsv getActiveAlarmsCount


Notification broker operartions supported:v subscribev unsubscribev notify


Appendix. Notices and Trademarks

This appendix contains the following sections:v Noticesv Trademarks

NoticesThis 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 inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing 2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

© Copyright IBM Corp. 2006, 2008 21

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct 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 itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM CorporationSoftware Interoperability Coordinator, Department 49XA3605 Highway 52 NRochester, MN 55901U.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 materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM’s suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.


COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs.

Each copy or any portion of these sample programs or any derivative work, mustinclude 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 rightsreserved.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

TrademarksIBM, the IBM logo, ibm.com, AIX, Tivoli, zSeries, and Netcool are trademarks ofInternational Business Machines Corporation in the United States, other countries,or both.

Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-basedtrademarks are either registered trademarks or trademarks of Adobe SystemsIncorporated in the United States, other countries, or both.

Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporationin the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, or service names may be trademarks or service marks ofothers.

Appendix. Notices and Trademarks 23

��

Printed in USA

SC23-6097-01

mtosi-pdf (1)

Documents