Sie sind auf Seite 1von 79

Netcool/OMNIbus Integration Best Practices May 2007

Tivoli Netcool/OMNIbus Integration Best Practices


Document version 1.1

Copyright International Business Machines Corporation 2007. All rights reserved US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

CONTENTS
List of Figures.................................................................................................................... v List of Tables .................................................................................................................... vi Revision History ...............................................................................................................vii 1 Getting Started ...................................................................................................... 1 1.1 1.2 Tivoli Netcool/OMNIbus Architecture and Overview.................................. 1 Tivoli Netcool/OMNIbus Integration Methods and Interfaces .................... 4
1.2.1 1.2.2 1.2.3 1.2.4 Creation of a Tivoli Netcool/OMNIbus Rules Files ................................... 4 Creation of a Tivoli Netcool/OMNIbus Tool .............................................. 5 Creation of Tivoli Netcool/OMNIbus Automations .................................... 6 Tivoli Netcool/OMNIbus Integration Option Architecture.......................... 7

1.3

Tivoli Netcool/OMNIbus Integration Development Environment................ 8


1.3.1 1.3.2 1.3.3 1.3.4 1.3.5 Tivoli Netcool/OMNIbus Software and Required Components ................ 8 Tivoli Netcool/OMNIbus Software Installation and Licensing ................... 9 Rules Files Editor...................................................................................... 9 Probe Configuration for Development and Testing Purposes ................ 10 Additional Resources.............................................................................. 14

Creation of Tivoli Netcool/OMNIbus Rules Files ................................................. 15 2.1 Probe and Rules Files: Function and Architecture .................................. 15
2.1.1 2.1.2 2.1.3 Introduction ............................................................................................. 15 Probe Architecture .................................................................................. 16 Importance of High Quality Rules Files .................................................. 20

2.2

Netcool/Knowledge Library and Include Files Structure .......................... 21


2.2.1 2.2.2 Netcool/Knowledge Library architecture................................................. 21 Structure of the SNMP Base Rules Files................................................ 23

ii

2.2.3 2.2.4 2.2.5 2.2.6 2.2.7

Developing SNMP Include Rules Files................................................... 24 Structure of the TL1 Base Rules Files.................................................... 26 Developing TL1 Include Rules Files ....................................................... 28 Structure of the Syslog Base Rules Files ............................................... 29 Developing Syslog Include Rules Files .................................................. 31

2.3 2.4

Standalone Rules Files Structure ............................................................ 32 Delivering the Basic 3 Functionality......................................................... 32


2.4.1 2.4.2 2.4.3 Basic 3 implementation and associated automations ............................ 32 ObjectServer alerts.status Table ............................................................ 36 Rules Files Standards............................................................................. 38

2.5 2.6 2.7

Rules Files Best Practices, Do and Dont ................................................ 49 Rules Files Frequently Asked Questions (FAQ) ...................................... 51 Rules Files Check List ............................................................................. 53
2.7.1 2.7.2 Overall Rules Files Readability and Content .......................................... 53 ObjectServer Fields Assignment ............................................................ 53

2.8 2.9 3

Rules Files Examples .............................................................................. 55 Documenting a Rules Files Based Integration......................................... 56

Creation of a Tivoli Netcool/OMNIbus Tool ......................................................... 57 3.1 3.2 3.3 3.4 3.5 Tool Function and Architecture................................................................ 57 Tool Creation Best Practices, Do and Dont ............................................ 58 Tools Frequently Asked Questions (FAQ) ............................................... 59 Tool Creation Check List ......................................................................... 60 Tool Examples ......................................................................................... 60

iii

3.5.1 3.5.2

Internal Effect Tool Example................................................................... 60 External Effect Tool Example ................................................................. 61

3.6 4

Documenting a Tool Based Integration ................................................... 61

Creation of a Tivoli Netcool/OMNIbus Automation .............................................. 62 4.1 4.2 4.3 4.4 4.5 4.6 Automation Function and Architecture..................................................... 62 Automation Creation Best Practices, Do and Dont ................................. 63 Automation Frequently Asked Questions (FAQ)...................................... 63 Automation Creation Check List .............................................................. 64 Automation Examples.............................................................................. 64 Documenting an Automation Based Integration ...................................... 65

Integration Submission Packaging ...................................................................... 66 5.1 5.2 Archiving tool ........................................................................................... 66 Files Names............................................................................................. 66

Appendix: Glossary of Terms ........................................................................................... vi References ........................................................................................................................ x

iv

LIST OF FIGURES
Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 CCAI Methodology ......................................................................................................... 2 Tivoli Netcool/OMNIbus Overall Architecture................................................................. 3 Tivoli Netcool/OMNIbus Integration Option Architecture ............................................... 7 Event Information and Alert Details.............................................................................. 10 Probe in the Tivoli Netcool/OMNIbus architecture ....................................................... 15 Processing of the events at the probe and rules files level.......................................... 19 Logical flow of the SNMP probe base rules files.......................................................... 23 Logical flow of the TL1 TSM base rules files................................................................ 26 Logical flow of the Syslog Probe base rules files ......................................................... 29

LIST OF TABLES
Table 1 Table 2 Table 3 Rules Files Editor Examples .......................................................................................... 9 Structure and purpose of NcKL and NcKL Lite directories .......................................... 22 Alerts.Status Schema................................................................................................... 36

vi

REVISION HISTORY
Date March 2007 Version 1.0 Revised By MSE Comments Initial version Mylene Stolpe-Evras May 2007 1.1 JAR Updated name and title, publish to OPAL.

vii

Getting Started
The Getting Started chapter provides an overview of Tivoli Netcool/OMNIbus and its integration methods and associated interfaces. The chapter also provides guidelines to set up the Tivoli Netcool/OMNIbus integration development environment.

1.1

Tivoli Netcool/OMNIbus Architecture and Overview

Tivoli Netcool/OMNIbus is at the core of the Netcool suite of software, a carrier-class service and business assurance system. The Tivoli Netcool/OMNIbus application focuses primarily on fault and event management. It collects and consolidates events and alarms from a wide variety of networking environments in real-time. These environments include servers, mainframes, Windows systems, UNIX applications, circuit switches, voice switches, IP routers, SNMP devices, network management applications and frameworks, among many others. Tivoli Netcool/OMNIbus can also consolidate information from different domain-limited network management platforms in remote locations.

Tivoli Netcool/OMNIbus presents this consolidated information in a meaningful, intuitive, point-and-click format and provides information of interest to specific users through individually configurable filters and views. Through Netcool/OMNIbus real-time monitoring, you can address problems before they cause disruptions in service, thereby supporting continuity of business operations with architectures that are responsive, scalable, and highly available.

The Netcool ObjectServer, the core component of Tivoli Netcool/OMNIbus, is a high-speed memory-resident database that acts as a centralized data repository for the fault information collected from the network infrastructure. Netcool Probes & Monitors collect fault messages throughout the network and forward them in a common format to the Netcool ObjectServer for further processing and filtering, and for display and management in customizable operator views. Using a point-and-click interface, you can prioritize events according to the business services they could potentially impact. You can react to events in real-time and see them in color-coded severity through Netcool EventLists, or monitor the availability of business services using service-level histogram summaries.

The primary user interface is the Native Desktop where Event Lists are displayed. The event list console shows events grouped into categories, each linked to an event list showing details of events in that category. Netcool/Webtop provides an additional Webbased desktop.

Getting Started

Fundamentally, Netcool solutions and Tivoli Netcool/OMNIbus in particular use a powerful Collect, Consolidate, Analyze & Automate, and Inform (CCAI) methodology, as depicted in the figure below.

NETCOOL BUSINESS AND SERVICE


Executive Customer Workflow Operations

INFORM
Realtime active dashboards and trended reporting views

ANALYZE & AUTOMATE


Dynamic service modeling, data enrichment, and problem

CONSOLIDATE
Industrys fastest, most scalable event processing engine

COLLECT
Industrys broadest coverage across business and IT data sources

Service VoIP

Application System Network Web Transactions CRM Wireless Cable

Hosting OSS ERP DSL Data Centers

1000+ UNIQUE EVENT AND DATA SOURCES

Figure 1

CCAI Methodology

Tivoli Netcool/OMNIbus provides technology support at each CCAI Tier. The figure below shows the overall architecture.

Getting Started

Figure 2

Tivoli Netcool/OMNIbus Overall Architecture

Getting Started

1.2

Tivoli Netcool/OMNIbus Integration Methods and Interfaces

Alert:

While this section presents the Tivoli Netcool/OMNIbus integration methods and interfaces options, it doesnt define criteria for technical validation. Please refer to the Ready for IBM Tivoli Software Product Requirements Document (PRD) for an exhaustive list of requirements and validation criteria.

1.2.1 Creation of a Tivoli Netcool/OMNIbus Rules Files


The rules file defines how the probe should process event data it receives in order to create a meaningful Tivoli Netcool/OMNIbus alert. The goals and objectives of the rules file development are listed below: The rules files created should be of production quality and provide "out-of-the-box" value. The rules files should not require any modifications to the ObjectServer (i.e. no additional event fields other than the default fields provided in Tivoli Netcool/Omnibus) The basic structure of the files should be easy to maintain and easily extendible, enabling the quick addition of event handling for new devices without affecting existing rules. Basic textual-conventions for the rules files should be determined and followed to ensure rules files created by different persons share a common format. The rules files should be sufficiently documented to allow each event to be understood without additional documentation. The structure of the rules file should be as efficient as possible to maximize throughput of events. The events formatted by the rules files should be "deduplicated" properly by the Tivoli Netcool/OMNIbus ObjectServer. The events formatted by the rules files should be compatible with the "GenericClear automation whenever possible.

Getting Started

At the minimum, the completed rules files should provide the following basic functionality (the Basic 3): Automated deduplication of events and alarms in the Tivoli Netcool/OMNIbus ObjectServer Automated 'Generic Clear' correlation of problem/ resolution events Informative and descriptive event presentation in Tivoli Netcool/OMNIbus ObjectServer

For the purpose of this integration, a Tivoli Netcool/OMNIbus rules files can be created for one of the standard-based probes (the SNMP, TL1 or Syslog probes). An SNMP, TL1 or Syslog integration can be created using one of the following methods: Development of a standalone rules files which will be the only rules files read by the probe at start time. Development of include rules files which will be added to an already-existing library of rules files called the Netcool Knowledge Library (NcKL). At start time, the probe will read the core NcKL rules files which will call (i.e. include) the device-specific or application-specific rules files written to process the information received from the products to be integrated.

Please refer to the following chapter for further information on the structure of both methods.

1.2.2 Creation of a Tivoli Netcool/OMNIbus Tool

Tools allow the control of alert management functions within Tivoli Netcool/OMNIbus from the EventList. Each tool has an associated SQL statement (called an internal effect), an executable (called an external effect), or both. Tools can be grouped in tools menus, which can then be associates with a class or classes of alert. Tools are created independently of menus, so a global set of tools can be used on different menus. They can be restricted by both Class and Group. This allows the tools to be event sensitive, and user based.

Getting Started

Tools can: Execute an external command on UNIX or Windows platforms. This gives the ability to launch other applications or run UNIX commands. Execute SQL statements internally on the events stored in the ObjectServer. Run an executable Gather more information from the user through the use of Prompts. Use field values from an event Use variables from the OS environment or those stored in the ObjectServer Can add a journal entry to track changes. These can be optional, or forced.

For the purpose of this integration, a Tivoli Netcool/OMNIbus tool can be created for the Netcool/Desktop which is the proprietary client interface into Tivoli Netcool/OMNIbus (a.k.a. Native Desktop) and/or for Netcool/Webtop which is considered the web-based version of the Netcool/Desktop.

1.2.3 Creation of Tivoli Netcool/OMNIbus Automations

Tivoli Netcool/OMNIbus automations provide automatic management of events in the ObjectServer. The automation will detect pre-defined changes in the ObjectServer and execute automated responses to these changes. This enables the ObjectServer to process many alerts without requiring an operator to take action. Automations can consist of triggers, procedures and/or user-defined signals. Automations can: Perform external command(s) automatically on the receipt of certain events. Incorporate escalation procedures. Allow correlation of events. Execute an external command on UNIX or Windows platforms. This gives the ability to launch other applications or run UNIX commands. Execute SQL statements internally on the events stored in the ObjectServer. Use field values from an event Use variables from the OS environment or those stored in the ObjectServer

Getting Started

Add a journal entry to track changes.

For the purpose of this integration, Tivoli Netcool/OMNIbus automation(s) can be created in the ObjectServer.

1.2.4 Tivoli Netcool/OMNIbus Integration Option Architecture

Figure 3

Tivoli Netcool/OMNIbus Integration Option Architecture

Getting Started

1.3

Tivoli Netcool/OMNIbus Integration Development Environment

Alert:

This section provides an overview and guidelines of the Tivoli Netcool/OMNIbus environment that can be set up to enable the development of Tivoli Netcool/OMNIbus integration. The aim of this section is not to replace the study of the Tivoli Netcool/OMNIbus product manuals or the attendance of Tivoli Netcool/OMNIbus trainings, both being highly encouraged.

1.3.1 Tivoli Netcool/OMNIbus Software and Required Components

Business Partners with an active PartnerWorld membership will be contacted by the Ready for IBM Tivoli development team after having nominated their products/ solution for the IBM Tivoli Open Process Automation Library (OPAL) catalog. The Ready for IBM Tivoli development team will then make the Tivoli Netcool/OMNIbus software available for download. At a minimum you will need the following Tivoli Netcool/OMNIbus components: One Object Server One desktop (Native Desktop or Netcool/Webtop) One Probe (at minimum) Licenses Manager License file(s) for all installed components Tivoli Netcool/OMNIbus Product Manuals Netcool/Knowledge Library (for rules files based integrations using the library)

For the most comprehensive set of software and hardware requirements please refer to the Tivoli Netcool/OMNIbus Supported Platforms and Requirements section of the Tivoli Netcool/OMNIbus Installation and Deployment Guide.

Getting Started

1.3.2 Tivoli Netcool/OMNIbus Software Installation and Licensing

To install Tivoli Netcool/OMNIbus, please refer to: Tivoli Netcool/OMNIbus Installation and Deployment Guide.

For details on Netcool licensing please refer to: Overview of Netcool Licensing

1.3.3 Rules Files Editor

The rules files can be edited by any text editor that can leave the file in a Unix readable format.

Table 1

Rules Files Editor Examples Platform Unix Unix Unix Windows Windows Editor Examples Vi Emacs Gedit Notepad Programmers File Editor (PFE32)

Getting Started

1.3.4 Probe Configuration for Development and Testing Purposes

The Details Statement


In the event list it is possible to display details information for an event. These details must be defined at the probe level. By default all events have no details information added. Details are extra tokens created by the probe from the event stream, which are not used to propagate a field value.

The ObjectServer details table (alerts.details) is used to store elements that are not added to the fields of the alert. These details can be viewed by double-clicking an event in the event list, and by selecting the Details tab.

Figure 4

Event Information and Alert Details

Details are added to the ObjectServer details table using the details statement. They are only added when an event is inserted, but not if an event is being deduplicated.

10

Getting Started

To add the elements $a and $b to the details table, you would include the following statement in the rules file: details($a,$b)

To add all of the event information into the details table, use: details ($*)

However, it is not recommended that you use ($*) in a production environment. If ($*) is used for long periods of time, the ObjectServer tables will become too large and the performance of the ObjectServer will suffer. The ($*) function should only be used to debug or write rules files; it is actually recommended to use it in that matter and it is a very useful development tool.

Raw Capture Mode and Events Replay

The Raw capture mode of any probe allows you to save the complete stream of event data acquired and processed by a probe into a file. This can be useful for auditing, recording and debugging the operation of a probe. Data captured in raw capture mode is in a format that can be replayed by the generic probe: You can then re-use this file to replay the events, and to help you creating/testing a rules file. That way there is no need to generate them again in your network to re-test the new version of your rules file. You can even replay them off-line. Raw capture mode is enabled using the command line option -raw or the probe property RawCapture. Here is an example of the RawCapture properties set for the mttrapd probe, in the mttrapd.props file: Example RawCapture : RawCaptureFile : RawCaptureFileAppend : 1 /opt/Omnibus/var/mttrapd.cap 1

Command line option can also be used Example

11

Getting Started

/opt/Omnibus/probes/nco_p_mttrapd -raw capturefile /opt/Omnibus/var/mttrapd.cap &

Note for the SNMP probe: Make sure the QuietOutput property is set to 1 in the mttrapd.props while running it in raw capture mode. To replay the raw events, you should use the Standard Input (stdin) probe, with the rules file you are creating. You can then work on the rules file, with an easy mean to replay the live event at your fingertips. The stdin probe does not probe any network management platforms or hardware. The stdin probe acquires raw data from the UNIX standard input. A possible syntax would be: cat <raw_capture_filename> | $OMNIHOME/probes/nco_p_stdin server <server> -propsfile /opt/Omnibus/probes/<arch>/stdin.props -rulesfile /opt/Omnibus/probes/<arch>/<probe>.rules -messagelevel debug &

Example cat opt/Omnibus/var/mttrapd.cap | /opt/Omnibus/probes/nco_p_stdin -server NCOMS -propsfile /opt/Omnibus/probes/solaris2/stdin.props -rulesfile /opt/Omnibus/probes/solaris2/snmp.rules -messagelevel debug &

Be aware that the generic probe uses s for demarcation of input data. You may encounter cases where an element contains these , so the generic probe wont parse correctly such a raw which does not necessary mean that your rules file is not correct. Most of the time, you wont have this case, and you will be able to get events in the object server as if they were received from the original source. If you are running a Log File type probe, like the syslog probe you can make sure you wont have the inconvenience of the , by using the replay option of the probe, instead of getting the raw capture and replaying them with the generic probe. Here is an example of the Replay property set for the syslog probe, in the syslog.props file: Example ReplayFile : 1

Command line option can also be used: Example /opt/Omnibus/probes/nco_p_syslog server NCOMS replayfile On &

12

Getting Started

Testing Rules Files Syntax

The syntax of a rules file can be tested using the syntax probe: nco_p_syntax. This methodology is more efficient than running a real probe to test the syntax of a rules file. The following example shows the format of the syntax probe: Example nco_p_syntax rulesfile /opt/Omnibus/probes/solaris2/syslog.rules

The syntax probe always runs in debug mode. The syntax probe connects to the ObjectServer, tests the rules files, displays any errors to the screen and then exits. If no errors are displayed, the syntax of the rules file is correct.

Debugging Rules Files

When making changes to the rules file, adding new rules or creating lookup tables it is useful to test the probe by executing it in debug mode. This will show exactly how an event is being parsed by the probe, and any possible problems with the rules file. You can set the probe to run in debug mode in two ways: on the command line, or in the properties file. To enable debug mode on the command line, enter the command: Example $OMNIHOME/probes/<arch>/<probename> -messagelevel DEBUG messagelog STDOUT

Alternatively enter the following in the properties file: Example MessageLevel: DEBUG MessageLog: STDOUT

13

Getting Started

If the MessageLog option is omitted, the debug information is sent to the probes log file in the $OMNIHOME/log directory rather than the screen.

1.3.5 Additional Resources

IBM Tivoli Netcool Documentation http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp

IBM Tivoli Training for Netcool http://www-306.ibm.com/software/tivoli/welcome/micromuse/education.html

IBM Software Access Catalog http://www.developer.ibm.com/welcome/softmall.html

14

Creation of Tivoli Netcool/OMNIbus Rules Files

Creation of Tivoli Netcool/OMNIbus Rules Files


This chapter provides an overview of probes and rules files function and architecture. The structure of the Netcool/Knowledge Library (NcKL) is then outlined in more details and the structure of the SNMP, TL1 and Syslog base files are presented. Guidelines are provided for the development of standalone rules files, which is the alternative rules files structure to NcKL. Last but not least, the basic 3 functionality are described and each of the ObjectServer fields required to enable these functionalities are reviewed in details. The Rules Files Standard that needs to be applied for the population of each identified field is provided along with meaningful examples and guidelines.

2.1

Probe and Rules Files: Function and Architecture

2.1.1 Introduction

A probe is an application that acquires data from an event source. Probes connect to an event source, detect and acquire events, and then forward them to the ObjectServer. When the probe receives a data stream it splits the stream into individual tokens, which together make up the event. The probe uses a rules file to propagate the field values within alerts.status. Extra information can also be added, within the rules file, to the event and mathematical calculations can be carried out. The figure below shows how probes fit into the Tivoli Netcool/OMNIbus architecture.

Figure 5

Probe in the Tivoli Netcool/OMNIbus architecture

15

Creation of Tivoli Netcool/OMNIbus Rules Files

A summary of the functions of a probe is as follows: Probes retrieve and send information It is through the probes that the ObjectServer obtains all the event data Probes tokenize event streams Propagate the field values within alerts.status Add extra information to the event Carry out mathematical calculations

2.1.2 Probe Architecture

A probe is made up of three primary components: an executable file a properties file a rules file

The Executable File


The executable file is the core of a probe. It manages the connection to the event source, the acquisition of events and the forwarding of events to the ObjectServer. All probe executable files are stored in the directory $OMNIHOME/probes/<arch>, where arch is the name of the architecture, for example: Example $OMNIHOME/probes/solaris2/nco_p_mttrapd

This example shows where the Solaris2.x executable of the mttrapd probe is stored. The first thing a probe executable file does when it is run is to configure its environment. To do this it reads the contents of the properties and rules files. Using the contents of these files, the executable file can define how it should control the connection between the event source and the ObjectServer. Once the rules file is correctly configured, it can read the event source and forward events to the ObjectServer.

16

Creation of Tivoli Netcool/OMNIbus Rules Files

The Properties File


The properties of a probe define the environment in which it will work. For example, the Server property defines the server where the events will be sent to. All of a probes properties are stored in a properties file. By default, all probe properties files are stored in the same directory as the executable file, with the extension .props . For example, the properties for the Solaris2.x version of the mttrapd probe are stored in the file: Example $OMNIHOME/probes/solaris2/mttraps.props

Properties files are formed of name-value pairs separated by a colon. Example Server : NCOMS

Where Server is the name of the property and NCOMS is the value the property is set to. You can display a list of the generic and probe specific properties and command line options available for use with a specific probe by using the -help and dumpprops command line option. For example, to display a list of the properties available from the command line for the Syslog probe, enter: Example $OMNIHOME/probes/nco_p_syslog help

The -dumpprops command line option can be used to provide the extensive list of properties to be set in the property file. For example, to display an extensive list of the properties available for use with the Syslog probe, enter: Example $OMNIHOME/probes/nco_p_syslog -dumpprops

You can change probe properties by editing the properties file using a text editor.

17

Creation of Tivoli Netcool/OMNIbus Rules Files

The Rules File

Not all of the data contained within an event is relevant to the processing of that event. The rules file defines how the probe should rationalize or add to the contents of an event to create a meaningful Tivoli Netcool/OMNIbus alert. In addition, the rules file creates a unique identifier for each event it acquires for deduplication purposesthe identifier field. By default, all probe rules files are stored in the same directory as the executable file with the extension .rules .

Example

$OMNIHOME/probes/solaris2/syslog.rules

All the field values of alerts.status are normally propagated by the rules file using the information from the incoming event.

Any changes made to the rules file will require the probe to be restarted or made to re-read the rules file (this is preferable, because the probe will not lose events). You can force the probe to re-read the rules file by issuing a kill -HUP pid command on the probe process ID (PID).

When the probe acquires raw data from the event source, it breaks it down into tokens. Each token represents a piece of event data. The probe then parses these tokens into elements. Elements are identified within the rules file by the $ symbol. For example, $Node is an element containing the node name of the event source.

18

Creation of Tivoli Netcool/OMNIbus Rules Files

Figure 6

Processing of the events at the probe and rules files level

The probe processes the elements according to the rules in the rules file to assign values to the fields which are available in the ObjectServer. When they have been processed, the field values contain the event details in the form used by the ObjectServer. At this stage, the unique @Identifier field is also generated. The probe then forwards the field values to the ObjectServer as a Tivoli Netcool/OMNIbus alert. Field values are identified within the rules file by the @ symbol. For example, @Node can be a field value containing the node name of the event source. There are three ways to assign elements to field values, which are: Direct assignment, for example: @Node = $Node. Concatenation, for example: @Summary = $Summary + $Group. Adding text, for example: @Summary = $Node + has problem + $Summary

Elements become details in the alert sent to the ObjectServer by using the details statement. The rules file allows you to create new elements dynamically.

Example

$newElem = "Here is a new detail field"

19

Creation of Tivoli Netcool/OMNIbus Rules Files

2.1.3 Importance of High Quality Rules Files

An important part of any IBM Tivoli Netcool Software implementation is a set of high quality rules files. Rules files which are implemented within the Tivoli Netcool/OMNIbus Probes are responsible for providing, or facilitating, a large part of the functionality which customers expect from the Netcool Suite. A well written rules file is an important part of the following, among many, IBM Tivoli Netcool Software features: Event Normalization - The rules files enable a common event format to be implemented regardless of the management system or device which generated the event. In addition the readability of an event can be directly influenced by the rules file. Deduplication - By properly setting the 'Identifier' field, the granularity of deduplication can be directly controlled. Event Correlation via Automations - Within the rules files the contents of ObjectServer fields can be determined which enable the use of Automations such as GenericClear. Business Impact - An event can be formatted in the rules files in such a way to allow/simplify the implementation of Tivoli Netcool/Impact. This is accomplished by filing ObjectServer fields with the appropriate raw event data, which is required for lookups/triggers in an Impact policy.

20

Creation of Tivoli Netcool/OMNIbus Rules Files

2.2

Netcool/Knowledge Library and Include Files Structure

This chapter outlines the overall structure of the Netcool/Knowledge Library and the Netcool/Knowledge Library Lite and provides details on the structure and location of the files of the library that are of most interest in the context of a rules files based integration project. Once the directory structure is detailed, the logical flow of the provided SNMP, Syslog and TL1 base files is described. Then this chapter focuses on providing the basic structure of the include files specifically developed for the purpose of this integration project.

2.2.1 Netcool/Knowledge Library architecture

The following table provide the structure and purpose of the directory and content created as a result of the installation of NcKL or NcKL Lite, and highlight with an arrow ( ) the directory of most interest.

Directory /rules

Description The base Netcool/Knowledge Library directory which contains the base rules files and other related files.

Alert:

snmptrap.rules and syslog.rules are installed for both the NcKL and NcKL Lite libraries where tl1.rules is only available for NcKL Lite.

This is the directory where the based files used in the context of this integration will be found. These based files should be edited to add the necessary include statement that will call the include files developed for this integration. /rules/include-common Contains include files that provide probeindependent logic for example, 3GPP and TMF814 specific log, lookup table to help convert between hex, decimal, and ASCII. Contains include files to activate support for various Netcool/Knowledge Library features.

/rules/include-compat

21

Creation of Tivoli Netcool/OMNIbus Rules Files

Directory /rules/include-snmptrap

Description Contains include files for processing events from the SNMP trap-based probes. This is the directory where the SNMP-based include files created in the context of this integration should be located.

/rules/include-snmptrap/generic

Contains SNMP trap-based include files that improve the handling of enterprise-specific implementations of the generic SNMP traps. This is the directory where the SNMP-based generic include files created in the context of this integration should be located.

/rules/include-syslog

Contains include files for processing events from the Syslog-based probes. Note that this includes the Windows version of the Syslog Daemon probe (nco_p_syslogd.exe), but does not include the Winsyslog probe (nco_p_winsyslog.exe). This is the directory where the Syslog-based include files created in the context of this integration should be located.

/rules/include-syslog/regmatch

Contains include files that use regular expressions or other matching techniques to make a best guess at the source of an event received by the Syslog-based probe. This is the directory where the Syslog-based regmatch include files created in the context of this integration should be located.

/rules/include-tl1/

Contains TL1-based include files for processing autonomous messages received by the TL1 TSM. This is the directory where the TL1-based include files created in the context of this integration should be located.

Table 2

Structure and purpose of NcKL and NcKL Lite directories

The SNMP and the Syslog probes as well as the TL1 TSM are designed to load a single rules file. Any other rules files to be used by the probe must be loaded via include statements from this rules file. The single rules file loaded by the probe is referred as the Base Rules File.

22

Creation of Tivoli Netcool/OMNIbus Rules Files

2.2.2 Structure of the SNMP Base Rules Files


The base rules file for the SNMP Probe contains logic that meets the following requirements and recommendations: Provides the basic logic and structure necessary to implement a chosen strategy for including vendor or MIB specific rules files. Handles ProbeWatch messages. Assigns default probe-specific values to the necessary ObjectServer fields. Performs pre-processing of tokens to adjust for differences in various versions of the SNMP Probe Normalizes tokens produced for SNMPv1 and SNMPv2 traps. Handles generic traps.

The following figure shows the simplified logical flow of a base rules file for the SNMP probe.

Begin

Set Default Values

Include Lookup Files

Pre-process Tokens

Probe Watch? No Yes Handle ProbeWatch

Normalize Tokens

Generic Trap? Yes Handle Probes Generic Traps No Include Vendor Rules Files

End

Figure 7

Logical flow of the SNMP probe base rules files

23

Creation of Tivoli Netcool/OMNIbus Rules Files

Once the incoming trap has traversed the SNMP file up to the point where it has been identified as an enterprise-specific trap, the enterprise and specific trap number can be considered to determine which rules file logic is applicable to the trap. This is accomplished by first using a switch/case statement to organize the rules file into segments, one segment for each enterprise. These segments are created as individual (include) rules files, which are then included into the base file. The include files would essentially be the case statements for the switch ($enterprise) statement:
switch($enterprise) { case "dummy case statement": ### This will prevent syntax errors in case no includes are added below. ############################################################ # Enter rules file Includes below with the following syntax: # # include "$NC_RULES_HOME/include-snmp/<rulesfile>.include.rules" ############################################################ include "<<<PATH TO INCLUDE FILE>>>" include "<<<PATH TO INCLUDE FILE>>>" ############################################################ # End of rules file Includes ############################################################ default: @Summary = "Enterprise ID Not Found (see details): " + $enterprise + " " + $generic-trap + " " + $specific-trap @Severity = 2 @Type = 0 @Identifier = @Node + " " + $enterprise + " " + $generic-trap + " " + $specific-trap + " " + @AlertGroup + " " + @AlertKey + " " + @Agent + " " + @Manager details($*) }

2.2.3 Developing SNMP Include Rules Files


In the SNMP base rules file, the enterprise-specific traps are handled based on the enterprise and specific trap number of the trap. A switch statement is then used against the $enterprise token, with corresponding case statements for each enterprise covered by the rules. These case statements are written as individual include files which are added to the base rules file using the include statement. These include files dedicated to the enterprisespecific traps are the integration rules files that can be packaged and submitted to validation.

24

Creation of Tivoli Netcool/OMNIbus Rules Files

Within each such segment, or include file, switch/case statements should be used to organize the rules file code necessary for each individual trap definition:

case "<<<ENTERPRISE OID>>>": @Agent = "<<<VENDOR-DEVICE/SYSTEM>>>" @Class = "<<<CLASS>>>" switch ($specific-trap) { case "1": <<<RULES LOGIC FOR SPECIFIC TRAP 1>>> case "2": <<<RULES LOGIC FOR SPECIFIC TRAP 2>>> default: @Summary = "Unknown Specific Trap Number (" + $specific-trap + ") Received for Enterprise " + $enterprise @Severity = 1 @Identifier = @Node + " " + @Agent + " " + @Manager + " " + $enterprise + " " + $generic-trap + " " + $specific-trap details($*) }

Alert:

In order to pass the technical validation, a rules file based integration for a certain product and release MUST support ALL traps for ALL enterprisespecific MIBS supported by the product and release in question. No MIB should be left unsupported and no specific trap should be left aside. Also, a default processing of the incoming event should be implemented to ensure no events are ignored, even if they didnt match the expected format. Also, a default processing of the incoming event should be implemented to ensure no events are ignored, even if they didnt match the expected format.

25

Creation of Tivoli Netcool/OMNIbus Rules Files

2.2.4 Structure of the TL1 Base Rules Files

Alert:

The TL1 base rules files and associated directory structure are ONLY available in the Netcool Knowledge Library Lite (a.k.a. NcKL Lite), and is not included in the full version of NcKL. The TL1 potion of the logic and directory structure of the NcKL Lite can either be used as is (i.e. in NcKL Lite) or be merged in the full version of NcKL.

The base rules file for the TL1 TSM contains logic that meets the following requirements and recommendations: Provides the basic logic and structure necessary to implement a chosen strategy for including vendor TL1 autonomous messages specific rules files. Handles TSMWatch messages. Assigns default probe-specific values to the necessary ObjectServer fields. Performs pre-processing and normalizations of tokens

Begin

Set Default Values

Include Lookup Files

Pre-process Tokens

TSM Watch? No Yes Handle TSMWatch

Normalize Tokens

Include Vendor Rules Files

End

Figure 8

Logical flow of the TL1 TSM base rules files

26

Creation of Tivoli Netcool/OMNIbus Rules Files

Once the incoming autonomous message has traversed the TL1 file up to the point where it has been identified as a vendor or device specific message, the SourceID and the Network Element Type (NEType) of the incoming event can be considered to determine which rules file logic is applicable to the message. This is accomplished by first using a switch/case statement to organize the rules file into segments, one segment for each NEType. These segments are created as individual (include) rules files, which are then included into the base file. The include files would essentially be the case statements for the switch ($NEType) statement:

switch(lookup($SID, NEType)) { case "DUMMY CASE STATEMENT": ### This will prevent syntax errors ### in case no includes are added below. ################################################################### # Enter rules file Includes below with the following syntax: # # include "$NC_RULES_HOME/include-tl1/<rulesfile>.include.rules" ################################################################### include "<<<PATH TO INCLUDE FILE>>>" include "<<<PATH TO INCLUDE FILE>>>" include "<<<PATH TO INCLUDE FILE>>>" ################################################################### # End of rules file Includes ################################################################### default: $Supported = "No" }

27

Creation of Tivoli Netcool/OMNIbus Rules Files

2.2.5 Developing TL1 Include Rules Files

In the TL1 base rules file, the vendor and devices specific autonomous messages are handled based on the Source ID (SID) of the message. A NEType lookup table is used to define the type (i.e. vendor and/or model) of each Network Element that the TL1 TSM will connect to based on the SID. A switch statement is then used against the $SID token, with corresponding case statements for each Network Element Type (NEType) covered by the rules. These case statements are written as individual include files which are added to the base rules file using the include statement. These include files dedicated to the vendor and devices specific autonomous messages are the integration rules files that can be packaged and submitted to validation. Within each such segment, or include file, switch/case statements should be used to organize the rules file code necessary for each individual NEType:

case "<<<NEType>>>": @Agent = "<<<VENDOR-DEVICE/SYSTEM>>>" @Class = "<<<CLASS>>>" Switch ($Verb + " " + $Modifier1) { case "REPT ALM": <<<RULES LOGIC FOR REPT ALM autonomous messages>>> case "REPT EVT": <<<RULES LOGIC FOR REPT EVT autonomous messages>>> case "REPT DBCHG": <<<RULES LOGIC FOR REPT DBCHG autonomous messages>>> default: <<<default RULES LOGIC>>> }

Alert:

In order to pass the technical validation, a rules file based integration for a certain product and release MUST support ALL autonomous messages supported by the product and release in question. Also, a default processing of the incoming event should be implemented to ensure no events are ignored, even if they didnt match the expected format.

28

Creation of Tivoli Netcool/OMNIbus Rules Files

2.2.6 Structure of the Syslog Base Rules Files

The base rules file for the Syslog probe contains logic that meets the following requirements and recommendations: Provides the basic logic and structure necessary to implement a chosen strategy for including vendor syslog messages specific rules files. Handles ProbeWatch messages. Assigns default probe-specific values to the necessary ObjectServer fields. Performs pre-processing and normalizations of tokens

Begin

Set Default Values

Include Lookup Files

Pre-process Tokens

Probe Watch? No Yes Handle ProbeWatch

Normalize Tokens

Include Vendor Rules Files

End

Figure 9

Logical flow of the Syslog Probe base rules files

Once the incoming syslog message has traversed the syslog file up to the point where it has been identified as a vendor or device specific syslog message, the Source Key (SrcKey, usually the Node) and the SourceType (SrcType) of the incoming event can be

29

Creation of Tivoli Netcool/OMNIbus Rules Files

considered to determine which rules file logic is applicable to the message. This is accomplished by first using a switch/case statement to organize the rules file into segments, one segment for each SrcType. These segments are created as individual (include) rules files, which are then included into the base file. The include files would essentially be the case statements for the switch ($SrcType) statement:

switch($SrcType) { case "dummy case statement": ### This will prevent syntax errors ### in case no includes are added below.

################################################################### # Enter rules file Includes below with the following syntax: # # include "$NC_RULES_HOME/include-syslog/<rulesfile>.include.rules" ################################################################### include "<<<PATH TO INCLUDE FILE>>>" include "<<<PATH TO INCLUDE FILE>>>" include "<<<PATH TO INCLUDE FILE>>>"

################################################################### # End of rules file Includes ################################################################### default: @AlertGroup = "[Generic Syslog]" @AlertKey = "" @Summary = $Details @Severity = 1 @Type = 1 @Identifier = @Node + " " + @AlertGroup + " " + @Manager + " " + $Details details($*) }

30

Creation of Tivoli Netcool/OMNIbus Rules Files

2.2.7 Developing Syslog Include Rules Files

In the Syslog base rules file, the vendor and devices specific syslog messages are handled based on the Source Key (SrcKey) of the message which is usually derived from the Node. A SrcType lookup table is used to define, based on the SrcKey, the type (i.e. vendor and/or model) of each source from which the syslog probe is receiving the syslog messages. A switch statement is then used against the $SrcType token, with corresponding case statements for each Source Type (SrcType) covered by the rules. These case statements are written as individual include files which are added to the base rules file using the include statement. These include files dedicated to the vendor and devices specific autonomous messages are the integration rules files that can be packaged and submitted to validation. Within each such segment, or include file, switch/case statements should be used to organize the rules file code necessary for each individual SrcType:

case "<<<SrcType>>>":

@Agent = "<<<VENDOR-DEVICE/SYSTEM>>>" @Class = "<<<CLASS>>>" <<<RULES LOGIC for syslog messages from SrcType>>>

Alert:

In order to pass the technical validation, a rules file based integration for a certain product and release MUST support ALL syslog messages supported by the syslog interface of the product and release in question. Also, a default processing of the incoming event should be implemented to ensure no events are ignored, even if they didnt match the expected format.

31

Creation of Tivoli Netcool/OMNIbus Rules Files

2.3

Standalone Rules Files Structure

While the structure of a standalone rules file is free, it must adhere to the goals and objectives of the rules file development as defined in chapter 1.2.1 of this document (Creation of a Tivoli Netcool/OMNIbus Rules Files).

Alert:

In order to pass the technical validation, a rules file based integration for a certain product and release MUST support messages supported by the interface of the product and release in question. Also, a default processing of the incoming event should be implemented to ensure no events are ignored, even if they didnt match the expected format.

2.4

Delivering the Basic 3 Functionality

2.4.1 Basic 3 implementation and associated automations

At the minimum, the developed rules files should provide the following basic functionality (the Basic 3): Automated deduplication of events and alarms in the Tivoli Netcool/OMNIbus ObjectServer Automated 'Generic Clear' correlation of problem/ resolution events Informative and descriptive event presentation in Tivoli Netcool/OMNIbus ObjectServer

32

Creation of Tivoli Netcool/OMNIbus Rules Files

Deduplication Automation

The ObjectServer database trigger to deduplicate the alerts.status table, commonly referred as the Deduplication automation, intercepts an attempted reinsert on the alerts.status table and increments the tally to show that a new row of this kind has arrived at the ObjectServer. It also sets the LastOccurrence field.

The deduplication automation is provided in the ObjectServer by default, out of the box and consists in the following:

create or replace trigger deduplication group default_triggers priority 1 comment 'Deduplication processing for ALERTS.STATUS' before reinsert on alerts.status for each row begin set old.Tally = old.Tally + 1; set old.LastOccurrence = new.LastOccurrence; set old.StateChange = getdate(); set old.InternalLast = getdate(); set old.Summary = new.Summary; set old.AlertKey = new.AlertKey; if ((old.Severity = 0) and (new.Severity > 0)) then set old.Severity = new.Severity; end if; end;

33

Creation of Tivoli Netcool/OMNIbus Rules Files

Generic Clear Automation

The ObjectServer database trigger to correlate the problem and resolution events in the alerts.status table, commonly referred as the Generic automation. The GenericClear automation is provided in the ObjectServer by default, out of the box and consists in the following:

-- A workspace table for the generic clear automation create table alerts.problem_events virtual ( Identifier varchar(255) primary key, LastOccurrence date, AlertKey varchar(255), AlertGroup varchar(64), Node varchar(64), Manager varchar(64), Resolved boolean ); go create or replace trigger generic_clear group default_triggers priority 1 comment 'Generic Problem/Resolution' every 5 seconds begin -- Populate a table with Type 1 events corresponding to any uncleared Type 2 events for each row problem in alerts.status where problem.Type = 1 and problem.Severity > 0 and (problem.Node + problem.AlertKey + problem.AlertGroup + problem.Manager) in ( select Node + AlertKey + AlertGroup + Manager from alerts.status where Severity > 0 and Type = 2 ) begin insert into alerts.problem_events values ( problem.Identifier, problem.LastOccurrence, problem.AlertKey, problem.AlertGroup, problem.Node, problem.Manager, false ); end;

34

Creation of Tivoli Netcool/OMNIbus Rules Files

-- For each resolution event, mark the corresponding problem_events entry as resolved and clear the resolution for each row resolution in alerts.status where resolution.Type = 2 and resolution.Severity > 0 begin set resolution.Severity = 0; update alerts.problem_events set Resolved = true where LastOccurrence < resolution.LastOccurrence and Manager = resolution.Manager and Node = resolution.Node and AlertKey = resolution.AlertKey and AlertGroup = resolution.AlertGroup ; end; -- Clear the resolved events for each row problem in alerts.problem_events where problem.Resolved = true begin update alerts.status via problem.Identifier set Severity = 0; end; -- Remove all entries from the problems table delete from alerts.problem_events; end; go

Alert:

Your integration should NOT alter in any way the deduplication and the generic clear automations. Any required customization should be performed at the rules files level as much as possible, and if you need to customize an already existing automation or to create a new automation for the purpose of your integration, then create a new automation without altering any of the default one.

35

Creation of Tivoli Netcool/OMNIbus Rules Files

2.4.2 ObjectServer alerts.status Table

Alert information is forwarded to the ObjectServer from the probes or TSMs, stored and managed in database tables, and displayed in the event list. The alerts.status ObjectServer table contains status information about problems that have been detected by the probes or the TSMs. The Alerts.Status fields are listed in the table below.

Table 3

Alerts.Status Schema Field Name Identifier Serial Node NodeAlias Manager Agent AlertGroup AlertKey Severity Summary StateChange FirstOccurrence LastOccurrence InternalLast Poll Type Tally Class Grade Location OwnerUID OwnerGID Acknowledged Flash ServerName Data Type Varchar(255) Incr Varchar(64) Varchar(64) Varchar(64) Varchar(64) Varchar(64) Varchar(255) Int Varchar(255) Time Time Time Time Int Int Int Int Int Varchar(64) Int Int Int Int Varchar(64)

36

Creation of Tivoli Netcool/OMNIbus Rules Files

Field Name ServerSerial EventId ExpireTime ProcessReq SuppressEscl Customer Service PhysicalSot PhysicalPort PhysicalCard TaskList NmosSerial NmosObjInst NmosCauseType LocalNodeAlias LocalPriObj LocalSecObj LocalRootObj RemoteNodeAlias RemotePriObj RemoteSecObj RemoteRootObj X733EventType X733ProbableCause X733SpecificProb X733CorrNotif MasterSerial URL

Data Type Int Varchar(64) Int Int Int Varchar(64) Varchar(64) Int Int Varchar(64) Int Varchar(64) Int Int Varchar(64 Varchar(255) Varchar(255) Varchar(255) Varchar(64) Varchar(255) Varchar(255) Varchar(255) Int Int Varchar(64) Varchar(255) Int Varchar(1024)

37

Creation of Tivoli Netcool/OMNIbus Rules Files

2.4.3 Rules Files Standards

The following describes in further detail the intended use of the ObjectServer fields to ensure a consistent normalization of events as well as proper deduplication and compatibility with the GenericClear automation. Only those fields are addressed below which are part of the default Tivoli Netcool/OMNIbus ObjectServer.

Identifier - varchar(255)
Required ObjectServer Field. Internal hash key/table identifier. The Identifier field controls the deduplication feature of the ObjectServer, as well as supports compatibility with the GenericClear automation by ensuring resolution events are properly inserted into the ObjectServer and not deduplicated with their respective problem events. Standard When the guidelines are followed for the other fields mentioned in this document the starting point for the assignment of the Identifier field should be as follows: @Identifier = @Node + + @AlertKey + + @AlertGroup + + @Type + + @Agent + + @Manager It may also be necessary to append additional information to the Identifier field to ensure proper deduplication and compatibility with the GenericClear automation. Example For an SNMP specific trap which contains a status enumeration value in one of its variable bindings (bgpBackwardTransition is a good example. BgpPeerState is the 2nd variable binding), the specific trap number and value of the relevant varbind should be appended to the Identifier field as follows:

@Identifier = @Node + + @AlertKey + + @AlertGroup + + @Type + + @Agent + + @Manager + + $specific-trap + + $2

38

Creation of Tivoli Netcool/OMNIbus Rules Files

Node - varchar(64)
Required ObjectServer Field. The Node field is used to identify the managed entity from which the alarm originated. This could be a host/device name, service name, customer, or other entity. Standard IP Devices For IP network devices or hosts the Node field contains the resolved name of the device or host. In cases where the name cannot be resolved the Node field should contain the layer-3 address (e.g. IP address) of the host or device. Non-IP Devices Alarms from non-IP devices should contain information equivalent to that of IP devices, i.e. the Node field should contain a name for the device that either directly allows, or can be resolved to allow, for direct communication with the device.

NodeAlias - varchar(64)
Default ObjectServer Field. Contains the Alias of the network entity referred to in the Node field. For network devices or hosts this should be the logical (layer-3) address of the entity, or other logical address which enables direct communication with the device. Standard IP Devices For IP devices or hosts this would the IP address. Non-IP Devices There are many possible addressing schemes that could be used for non-IP devices. The key to choosing a value for the NodeAlias field is that the value should allow for direct communication with the device. A good example would be a device managed via TL-1. The NodeAlias field could be filled via a lookup table and/or Netcool/Impact Policy with the IP address and port number of the terminal server through which the TL-1 device can be reached.

39

Creation of Tivoli Netcool/OMNIbus Rules Files

Manager - varchar(64)
Required ObjectServer Field. The Manager field contains a descriptive name of the Probe which collected and forwarded the alarm to the ObjectServer (Ex. MTTrapd Probe, HP OpenView NNM, etc.). Standard The Manager field must contain a descriptive name of the Probe which collected and forwarded the alarm to the ObjectServer (Ex. MTTrapd Probe, HP OpenView NNM, etc.). The Manager field should also contain the host on which the Probe is running (Ex. MTTrapd Probe on hostname). Ideally this is set in the Probes properties file, but the Rules File should check to ensure it is set properly, and modify if necessary. Example The following syntax can be used to set the Manager field:

@Manager = "MTTrapd Probe on " + hostname()

Agent - varchar(64)
Default ObjectServer Field. The Agent field contains a descriptive name of the submanager which generated the alert. (Ex. Manager = MTTrapd Probe, Agent = IETFBRIDGE- MIB). Standard SNMP Trap-related Probes Probes which process SNMP traps should set the Agent field to the name of the vendor or standards body which defined the trap as well as a description of the MIB, or MIB Definition Name, where the trap is defined. The format should be: vendor-MIB description Example Cisco-Accounting Control, Cisco-Health Monitor, IETFBRIDGEMIB, ATMF-ATM-FORUM-MIB

Optionally, vendor-specific information, such as device model numbers, can be appended to the Agent field for vendor-specifc implementations of standard traps. Example An example would be Extremes implementation of generic traps. The model of the device which sent the trap can be interpreted from the trap enterprise and appended to the Agent field as such: Generic-Extreme Summit48i

NOTE: The vendor name specified in the Agent field should be consistent with that name which is registered with IANA for the traps Enterprise ID.

40

Creation of Tivoli Netcool/OMNIbus Rules Files

Syslog Probe The Syslog Probe should set the Agent field to the name of the vendor which defined the received message as well as any logical description for the family of messages to which the received message belongs. Example An example would be system log messages from Cisco. Cisco defines messages from IOS-based devices in separate documentation to that of messages from the PIX Firewall. The format of the message differs slightly as well. So syslog messages from Cisco will have the Agent field set to either Cisco-IOS or Cisco- PIX Firewall.

TL-1 TSM Similar to the syslog probe, the TL-1 TSM should set the Agent field to the name of the vendor which defined the received message as well as any logical description for the family of messages to which the received message belongs.

AlertGroup - varchar(64)
Default ObjectServer Field. The AlertGroup field contains a descriptive name of the type of failure indicated by the alarm (Ex. Interface Status, CPU Utilization, etc). This field is important for proper correlation of events by the GenericClear automation. Standard The AlertGroup field must contain the same value for problem and resolution events which are related to each other. Example Generic SNMP traps 2 and 3, linkDown and linkUp respectively, should both contain the same AlertGroup value of Link Status.

TL-1 TSM Typically the AlertGroup field for a TL-1 message will be set to the value of the messages Alarm Type.

41

Creation of Tivoli Netcool/OMNIbus Rules Files

AlertKey - varchar(64)
Required ObjectServer Field. The AlertKey field contains a descriptive key which indicates the object instance referenced by the alarm (Ex. The disk partition indicated by a file system full alarm, or the switch port indicated by utilization alarm). This field is important for proper correlation of events by the GenericClear automation. Standard The primary goal of the value of the AlertKey field is to ensure proper deduplication of alarms and compatibility with the GenericClear automation. Readability of its value for display purposes is secondary. See Summary varchar(255) for more information. SNMP Trap-related Probes When applicable probes which process SNMP traps should set the AlertKey field to one of the following values, in order of preference: o The SNMP instance of the managed object which is represented by the alarm. This is usually obtained by extracted the instance from the OID of one of the traps variable bindings, but may also be contained in a combination of one or more of the traps variable binding values. The first variable binding of a linkDown trap contains the ifIndex value (i.e. interface number) of the interface which went down. AlertKey can be set with either of the following methods:

Example

@AlertKey = extract($OID1, \.([0-9]+)$) @AlertKey = $1 o A textual description of the instance derived from the trap name or trap description. A device with two power supplies, A and B, may be able to send two separate specific traps, without variable bindings, to indicate the failed status of one or the other power supply. The appropriate power supply instance would need to be derived from the MIBs trap definitions and then encoded in the rules file.

Example

switch($specific-trap) { case 1: @AlertKey = A case 2: @AlertKey = B default: } o A mixed combination of variable binding values and information derived from the from the trap name or trap description. In other words, any

42

Creation of Tivoli Netcool/OMNIbus Rules Files

instance information that is not available in the above two methods, but is required to ensure proper deduplication and GenericClear compatibility. Syslog Probe The Syslog Probe should set the AlertKey to a textual description of the instance derived from the log message text. Ideally this will be a textual name of the some managed entity. Example For the following syslog message

Nov 20 13:12:57 device.customer.net 195.180.208.193 19986: 37w0d: %LINK-3-UPDOWN: Interface FastEthernet0/13, changed state to down ...the AlertKey would be set to FastEthernet0/13 using the following syntax: @AlertKey = extract($Details, Interface (.*), changed)

TL-1 TSM Typically the AlertKey field for a TL-1 message will be set to the value of the messages Alarm Location.

Severity - int
Required ObjectServer Field. The Severity field can indicate any of six defined severity levels, which provide an indication of how it is perceived that the capability of the managed object has been affected. The displayed color of the alarm is also controlled by the Severity value. This field is important for proper correlation of events by the GenericClear automation. Those severity levels which represent service affecting conditions ordered from most severe to least severe are Critical, Major, Minor and Warning. Standard The levels defined for use with this mandatory parameter are: Clear (0) The Clear severity level indicates the clearing of one or more previously reported alarms. Alarms which are cleared have either been cleared manually by a network operator, or automatically by a process which has determined the fault condition no longer exists. These processes, such as the GenericClear automation, typically clear all alarms for this managed object (i.e. AlertKey) that have the same Alarm Type and/or Probable Cause (i.e. AlertGroup). Indeterminate (1) The Indeterminate severity level indicates that the severity level cannot be determined. Additionally, all problem resolving alarms are initially defined as indeterminate until they have been correlated with problem indicating alarms (for example by the GenericClear automation), at which point all correlated alarms are set to Clear.

43

Creation of Tivoli Netcool/OMNIbus Rules Files

Warning (2) The Warning severity level indicates the detection of a potential or impending service affecting fault, before any significant effects have been felt. Action should be taken to further diagnose (if necessary) and correct the problem in order to prevent it from becoming a more serious service affecting fault. Minor (3) The Minor severity level indicates the existence of a non-service affecting fault condition and that corrective action should be taken in order to prevent a more serious (for example, service affecting) fault. Such a severity can be reported, for example, when the detected alarm condition is not currently degrading the capacity of the managed object. Major (4) The Major severity level indicates that a service affecting condition has developed and an urgent corrective action is required. Such a severity can be reported, for example, when there is a severe degradation in the capability of the managed object and its full capability must be restored. Critical (5) The Critical severity level indicates that a service affecting condition has occurred and an immediate corrective action is required. Such a severity can be reported, for example, when a managed object becomes totally out of service and its capability must be restored.

Summary - varchar(255)
Required ObjectServer Field. The Summary field contains text which describes the alarm condition as well as the affected managed object instance. Standard Care should be taken to ensure that the Summary field is as compact as possible while still providing all of the necessary information. Example Based on the bgpBackwardTransition trap defined in BGP4-MIB the Summary field could read: A BGP Peer Connection has moved to the Idle state However a simplified Summary text provides the same information, while making easier for network operators to deal with the event quickly: BGP Peer Connection Idle The Summary field should contain, in parenthesis, the best textual description of the managed object instance provided by the available alarm data.

44

Creation of Tivoli Netcool/OMNIbus Rules Files

Example For the BGP alarm in the previous example this could be as follows: BGP Peer Connection Idle ( bgpPeerRemoteAddr = 18.120.10.10 ) A linkDown trap from a Cisco device will contain the ifDescr value in the 2nd variable binding. The Summary of such an event would be similar to the following: Link Down ( FastEthernet0/13 )

For alarms related to thresholds which contain the compared and/or threshold values one of the following formats should be chosen based on the available data: o No values provided:

Link Utilization High ( BRI2/0:1 ) o Compared Value Name provided:

Link Utilization High: inOctets Exceeded Threshold ( BRI2/0:1 ) o Compared Value Name and Value provides:

Link Utilization High: inOctets, 7100, Exceeded Threshold ( BRI2/0:1 ) o Threshold Name provided:

Link Utilization High: inOctetsMax Exceeded ( BRI2/0:1 ) o Threshold Value provided:

Link Utilization High: inOctetsMax, 7000, Exceeded ( BRI2/0:1 ) o Compared Value and Threshold Value provided:

Link Utilization High: 7100 Exceeded 7000 ( BRI2/0:1 ) o Both Names and Values provided:

Link Utilization High: inOctets, 7100, Exceeded inOctetsMax, 7000 ( BRI2/0:1 )

45

Creation of Tivoli Netcool/OMNIbus Rules Files

Type - int
Default ObjectServer Field. Specifies the type of alarm, where type refers to the problematic or resolving nature of the Alarm. This field is important for proper correlation of events by the GenericClear automation. The following values are valid values for the Type field: (0) Type not set (1) Problem (2) Resolution (3) Netcool/Visionary problem (4) Netcool/Visionary resolution (7) Netcool/ISMs new alarm (8) Netcool/ISMs old alarm (11) More Severe (12) Less Severe (13) Information

Standard Some scenarios are not well suited for strict definition as a problem (1) or resolution (2). There are numerous examples of events which are going down but dont yet represent a failure, as well events which are going up which do not yet indicate the failure has been fully corrected.

46

Creation of Tivoli Netcool/OMNIbus Rules Files

In these cases the Type field should be set to (1) Problem, (11) More Severe or (12) less severe in order to maintain compatibility with the GenericClear automation. Example The following rule file logic is for the handling of traps related to BGP Peer Connection Status

switch ($bgpPeerState) { case "1": ### idle @Severity = 4 @Type = 1 case "2": ### connect @Severity = 2 @Type = 12 case "3": ### active @Severity = 2 @Type = 12 case "4": ### opensent @Severity = 2 @Type = 12 case "5": ### openconfirm @Severity = 2 @Type = 12 case "6": ### established @Severity = 1 @Type = 2 default: @Severity = 2 @Type = 1 }

Class - int
Required ObjectServer Field. The Class of an alarm can be used to identify the Probe or vendor from which an alarm was generated. The Class field is used to control the applicability of context sensitive tools to the alarm. Standard Class numbers are issued by the IBM Ready for IBM Tivoli Software Solution team or by the Tivoli Netcool Technology Program. Once assigned, class numbers should be properly set within the relevant rules files.

47

Creation of Tivoli Netcool/OMNIbus Rules Files

EventId varchar(255)
Contains an Identifier for the event which is specific to the event source. This is a generic identifier in that it is not specific to the state or objects represented in the originating message. Standard SNMP Traps: SNMPTRAP-<vendor>-<MIB>-<specific-trap name> Example Example Example SNMPTRAP-cisco-MPLS-LDP-MIB-mplsLdpSessionDown SNMPTRAP-IEEE-IEEE802dot11-MIB-dot11Disassociate SNMPTRAP-IETF-ACCOUNTING-CONTROL-MIB-acctngFileFull

Syslog Messages: SYSLOG-<vendor>-<event-specific-trap id> Example Example SYSLOG-cisco-ios-LINK-UPDOWN SYSLOG-cisco-ios-LINEPROTO-UPDOWN

TL1 Autonomous Messages: TL1-<vendor>- <verb>[_<modifier1>][_<modifier2>]<condtype> Example Example Example TL1-movaz-REPT_ALM_EQPT-COMMLINK TL1-polaris-REPT_EVT_CHASSIS-FAN TL1-calix-REPT_RMV_OC12-OOS-AU

ExpireTime int
The number of seconds until the alert is cleared automatically. Used by the Expire automation, in conjunction with the Type field.

48

Creation of Tivoli Netcool/OMNIbus Rules Files

2.5

Rules Files Best Practices, Do and Dont

Always take a backup copy of a Rules File before amending it. Save it as .rules.date i.e. snmp.rules.070131. This is vital in case a roll-back is later required. Unless specifically required, do not match on device names within a Rules File. The customer devices or application will have its own name which will not match the rule, thus requiring an amendment. Any logic or amendments should be accompanied by a #comment line in the Rules File. Rules File additions should follow the existing structure of the Rules File. For example, if an event is currently matched in a switch case default statement, build another case statement to match a new event. Never build a separate If statement at the bottom of a Rules File unless you want to reset fields for all events. Use the Details($*) function with care, only use it whilst debugging Rules Files, or for default sections where the received data is unknown, or other specific requirements. Never leave Details($*) for all events in the final version of a rules file. The Switch/Case constructs must be used in preference to If/Else statements, as they are much more efficient. Switch/Case constructs can be used for exact matches. Use lookup tables wherever possible. When multiple values are linked to a single key, use a multi-column lookup table. It is recommended that lookup tables are defined within an external file based table, and that their extension is set up to be .lookup. This enables clear identification of the lookup tables. Also remember that lookup tables should be the first elements of the rules files that are read by the probe, i.e. the lookup files include statement are located at the top of base rules file. Ensure revision control is used on the probe rules file. This ensures identification of changes made to the rules file, when and by whom. Also specify which product(s), release(s) and interface(s) are supported by the rules, i.e. productA, release 1.0, MIB abc.mib rev. 200701310907Z Always check if a ObjectServer field exists prior to creating a new field that would have the same function Do not over deduplicate; this can be assessed/ tested by temporarily adding a timestamp to the @Identifier field Do not let field truncation in the code if it is impacting the deduplication automation, or the generic clear automation

49

Creation of Tivoli Netcool/OMNIbus Rules Files

Matching event pair (problem & resolution) must have exactly the same @AlertGroup and @AlertKey values, and appropriate @Type and @Severity values. Resolutions event must have a Severity of 1 (indeterminate) and a Type of 2 (resolution). Do not set the Severity of resolution events to be 0 (Clear) as it would prevent it to be processed by the Generic Clear automation

50

Creation of Tivoli Netcool/OMNIbus Rules Files

2.6

Rules Files Frequently Asked Questions (FAQ)


Where can I obtain the Tivoli Netcool/OMNIbus software? o Business Partners with an active PartnerWorld membership will be contacted by the Ready for IBM Tivoli team after having nominated their products/ solution for the Ready for IBM Tivoli / IBM Tivoli Open Process Automation Library (OPAL) catalog.

Where can I obtain the Tivoli Netcool/OMNIbus license? o Business Partners with an active PartnerWorld membership will be contacted by the Ready for IBM Tivoli team after having nominated their products/ solution for the Ready for IBM Tivoli / IBM Tivoli Open Process Automation Library (OPAL) catalog. The Ready for IBM Tivoli team will then make the Tivoli Netcool/OMNIbus licenses available to the Business Partner.

Where can I obtain the Class Number dedicated to the integration I am developing? o The Class Number dedicated to your integration will be provided by the Ready for IBM Tivoli team.

Where can I find the TL1 base files and associated directory structure? It doesnt seem to be included in the Netcool Knowledge Library (NcKL). o The TL1 base rules files and associated directory structure are ONLY available in the Netcool Knowledge Library Lite (a.k.a. NcKL Lite), and is not included in the full version of NcKL. The TL1 potion of the logic and directory structure of the NcKL Lite can either be used as is (i.e. in NcKL Lite) or be merged in the full version of NcKL.

Can I add a new field in the ObjectServer? o You can add a new field to the ObjectServer if there is no existing field in the ObjectServer that has the same purpose. Refer the Adding and Editing Table Columns section of the Configuring System Components for more details.

Can I alter an existing field in the ObjectServer? o While you can technically alter an existing field in the ObjectServer, your integration will not likely successfully pass the technical validation if it alters an existing field. Instead, a new field should be created.

Can I add a new automation in the ObjectServer? o You can add a new automation to the ObjectServer if there is no existing automation in the ObjectServer that has the same purpose. Refer the

51

Creation of Tivoli Netcool/OMNIbus Rules Files

Configuring Automations section of the Tivoli Netcool/OMNIbus manual for more details. Can I alter an existing automation in the ObjectServer? o While you can technically alter an existing automation in the ObjectServer, your integration will not likely successfully pass the technical validation if it alters an existing automation. Instead, a new automation should be created (which can be done by cut-and-pasting the existing automation, changing his name and description, and amending it as needed).

How should I configure the Raw Capture mode at the probe level to collect sample? o Please refer to chapter 1.3.4 Probe Configuration for Development and Testing Purposes of this Best Practices document.

What data should I generate to test the integration and submit it to IBM for validation? o This information is found in the Ready for IBM Tivoli software Product Requirements Document For Tivoli Netcool/OMNIbus 7.x Integrations (PRD) under the section entitled Tivoli Netcool/OMNIbus Minimum Test Scenario Requirements

52

Creation of Tivoli Netcool/OMNIbus Rules Files

2.7

Rules Files Check List

2.7.1 Overall Rules Files Readability and Content

Clear and regular indentation Consistency in field assignment order (per events/messages/traps) Comments where appropriate Line length of commented section should not exceed 85 characters Correct spelling Accurate processing of all the messages defined in the supporting documentation (ex: all traps, all syslog messages, etc.); no events left unprocessed.

2.7.2 ObjectServer Fields Assignment

The .rules files should at a minimum start with assignment statements for the following fields and tokens: @Agent and @Class The rules file section dedicated to the processing of each specific messages, traps etc. should contain the following, at a minimum: o o o o o o o o Commented section which describes the message/trap and the token received $token mapping (and preprocessing via lookup file where appropriate) @AlertGroup @AlertKey @Summary @Severity, @Type and $OS_ExpireTime (if applicable) Details ( ) @Identifier

53

Creation of Tivoli Netcool/OMNIbus Rules Files

Agent o o Class o Class should have been requested to IBM as they are specific to each Business Partner and to each integrated product. Descriptive name of the sub-manager which generated the alert Check the Rules Files Standards for more details and examples

AlertGroup o Descriptive name of the type of failure indicated by the alarm (as descriptive as possible based on information available in either the tokens received or the documentation) Exact same value for problem and resolution events which are related to each other No white space at the beginning or at the end of the field Check the Rules Files Standards for more details and examples

o o o

AlertKey o o o o o Descriptive key which indicates the object instance referenced by the alarm. Instance of the managed object which is represented by the alarm Exact same value for problem and resolution events which are related to each other Value Truncation should be avoided and if it occurs, it should not impact the deduplication and generic clear automation Check the Rules Files Standards for more details and examples

Severity o o o Any of six defined severity levels, except Indeterminate (1) as it is for resolution events and unknown events only Severity must be set to 1 for resolution events Check the Rules Files Standards for more details and examples

Summary o o o o Text which describes the alarm condition as well as the affected managed object instance. As compact as possible but extremely clear Provides all of the necessary information Contains in parenthesis, the best textual description of the managed object instance provided by the available alarm data. (usually AlertKey value or textual equivalent) Format example: @Summary = <$Summary> + " ( " + @AlertKey + " )" with two spaces in front of the opening parenthesis, and one in front of the closing parenthesis

54

Creation of Tivoli Netcool/OMNIbus Rules Files

Must be followed by update(@Summary) if the Summary value should be updated on deduplication (ex: summary field contains a metric such as CPU utilization) Check the Rules Files Standards for more details and examples

Type o o o Type of alarm must always be set, and should not be 0 (zero) Type must always be 2 for resolution events Check the Rules Files Standards for more details and examples

Identifier o o Controls the deduplication and GenericClear automation For SNMP traps, it should be @Identifier = @Node + + @AlertKey + + @AlertGroup + + @Type + + @Agent + + @Manager + + $specific-trap and additional information might be appended at the end to ensure proper deduplication and automation Must NOT contain any timestamp value Check the Rules Files Standards for more details and examples

o o

2.8

Rules Files Examples

Examples of SNMP, TL1 and Syslog based integration rules files can be found in the following libraries of rules files or integration modules: The Netcool Knowledge Library (NcKL) The Netcool Knowledge Library Lite (NcKL-Lite) The Tivoli Netcool/OMNIbus Integration Modules which can be downloaded from the Tivoli Netcool/OMNIbus catalog of the IBM Tivoli Open Process Automation Library (OPAL) at http://www.ibm.com/software/tivoli/opal/ncomnibus

55

Creation of Tivoli Netcool/OMNIbus Rules Files

2.9

Documenting a Rules Files Based Integration


Appropriate documentation should be written for submitted Integration and must contain at a minimum: o o o o o o o o o Name and version of the integration Name and version of the integrated product(s) Description of the integration Supported platforms List of Files contained in the integration List of other required files and dependencies if any Installation instructions References if any Description of events supported by the integration; For example: Enterprise OIDs supported for SNMP trap based integration, TL1 Autonomous Messages supported for TL1 based integration or syslog messages supported for a syslog based integration.

56

Creation of a Tivoli Netcool/OMNIbus Tool

Creation of a Tivoli Netcool/OMNIbus Tool


This chapter provides an overview of Tivoli Netcool/OMNIbus tools function and architecture. It then provides guidelines for creating and using tools. Alert: The aim of this section is not to replace the study of the Tivoli Netcool/OMNIbus product manuals or the attendance of Tivoli Netcool/OMNIbus trainings, both being highly encouraged.

3.1

Tool Function and Architecture


Tools allow the control of alert management functions within Tivoli Netcool/OMNIbus from the EventList. For example, tools can be created that enable operators to: Execute external commands (for example, launch a local application, batch file, or script) Execute SQL commands on the ObjectServer

Tools can be configured by going to the Menus section of the Tivoli Netcool/OMNIbus configuration tool after opening the ObjectServer you wish to add it to. Each ObjectServer can have its own set of tools, so you would need to add the tools to all ObjectServers that they pertain to. This basically means if you are running a Primary and a Backup, you would need to apply all changes to both. Each tool can have an internal effect, external effect, or both. An internal effect is created by using a SQL statement An External effect is created when you call a script or an executable from outside the system

A tool can include a prompt or a popup so the user can enter, or select from a menu, some additional information related to the event. A prompt can be included into an SQL statement, an external command, or a journal entry. Tools associated with a class or classes of alert (@Class field). By associating a tool with a specific class of alerts, the tool will only be available on the menu it has been assigned to when the selected event(s) belongs to the class associated to the tool.

57

Creation of a Tivoli Netcool/OMNIbus Tool

Scripts used for External Effect purposes can be written using any of the following; Bourne shell (/bin/sh) Korn shell (/bin/ksh) Perl Expect Awk/Nawk/Sed

For information about adding tools to event list menus, see Adding Tools, Sub-menus, and Separators to a Menu.

3.2

Tool Creation Best Practices, Do and Dont

All tools should utilize the journal functionality to enable inform other Tivoli Netcool/OMNIbus users that the tool has been executed. If for some reasons a journal entry is not implemented on purpose, please describe why while submitting your integration for technical validation All tools should have a meaningful description. Ensure that the tool is made available only from that events pertaining to your Class (be as specific as possible when defining the SQL select statements associated with the tool)

58

Creation of a Tivoli Netcool/OMNIbus Tool

3.3

Tools Frequently Asked Questions (FAQ)

Where can I obtain the Class Number dedicated to the integration I am developing? o The Class Number dedicated to your integration will be provided by the Ready for IBM Tivoli Development team.

Can I add a new field in the ObjectServer? o You can add a new field to the ObjectServer if there is no existing field in the ObjectServer that has the same purpose. Refer the Adding and Editing Table Columns section of the Configuring System Components for more details.

Can I alter an existing field in the ObjectServer? o While you can technically alter an existing field in the ObjectServer, your integration will not likely successfully pass the technical validation if it alters an existing field. Instead, a new field should be created.

Can I add a new automation in the ObjectServer? o You can add a new automation to the ObjectServer if there is no existing automation in the ObjectServer that has the same purpose. Refer the Configuring Automations section of the Tivoli Netcool/OMNIbus manual for more details.

Can I alter an existing automation in the ObjectServer? o While you can technically alter an existing automation in the ObjectServer, your integration will not likely successfully pass the technical validation if it alters an existing automation. Instead, a new automation should be created (which can be done by cut-and-pasting the existing automation, changing his name and description, and amending it as needed).

What data should I generate to test the integration and submit it to IBM for validation? o This information is found in the Ready for IBM Tivoli software Product Requirements Document For Tivoli Netcool/OMNIbus 7.x Integrations (PRD) under the section entitled Tivoli Netcool/OMNIbus Minimum Test Scenario Requirements

59

Creation of a Tivoli Netcool/OMNIbus Tool

3.4

Tool Creation Check List

Ensure that the tool has been set up to be available only on the platform it has been developed for Ensure that the tool has been set up to be available only for the Class of events it is meant for. Ensure that any SQL select statements are as narrow in scope as they can be Ensure that the tool is only available when the proper set of events is selected (in some cases that could mean none) Ensure that a journal entry is being created (forced or optionally) Ensure that Journal entries are selected for each row if the tool changes multiple events.

3.5

Tool Examples

Please refer to the default tools that are provided out of the box in the ObjectServer.

3.5.1 Internal Effect Tool Example

The Change Severity tool uses the following SQL to modify the event: update alerts.status set Severity=$prompt.Priority,Acknowledged=0 where Serial in ( $selected_rows.Serial );flush iduc; The access by default is set to all groups and all classes The Journal entry is not forced but is set for each row selected. The Platform is set to Windows and UNIX since it works the same for both.

60

Creation of a Tivoli Netcool/OMNIbus Tool

3.5.2 External Effect Tool Example


The telnet tool uses the following commands: . $(OMNIHOME)/utils/nco_functions nco_get_PATH export TELNET SLEEP $XTERM -e /bin/sh -c '$TELNET @Node ; $SLEEP 3'

The access by default is set to all groups and all classes. The Journal entry is not used. (This does not update an event) The Platform is set to UNIX. The description is: Example Telnet tool.

3.6

Documenting a Tool Based Integration

The following are required for tools integration documentation: Integration datasheet Users guide or equivalent (must include the description of the integration and the integration installation steps) List of all scripts or executables called by the tools, their functions and expected locations. (Can be included in Users Guide)

61

Creation of a Tivoli Netcool/OMNIbus Automation

Creation of a Tivoli Netcool/OMNIbus Automation


This chapter provides an overview of Tivoli Netcool/OMNIbus automation function and architecture. It then provides guidelines for creating and using tools. Alert: The aim of this section is not to replace the study of the Tivoli Netcool/OMNIbus product manuals or the attendance of Tivoli Netcool/OMNIbus trainings, both being highly encouraged.

4.1

Automation Function and Architecture

Tivoli Netcool/OMNIbus automations provide automatic management of events in the ObjectServer. The automation will detect pre-defined changes in the ObjectServer and execute automated responses to these changes. This enables the ObjectServer to process many alerts without requiring an operator to take action. Automations can consist of triggers, procedures and/or user-defined signals. Triggers form the basis of the ObjectServer automation subsystem. Triggers automatically fire (execute a trigger action) when the ObjectServer detects an incident associated with a trigger. In a trigger, you can execute SQL commands and call procedures in response to the change. Every trigger belongs to a trigger group, which is a collection of related triggers. You can enable or disable all triggers in a given group. For more details on Automations, please refer to Automation: Triggers and Trigger Groups.

62

Creation of a Tivoli Netcool/OMNIbus Automation

4.2

Automation Creation Best Practices, Do and Dont

Always check if an automation exists prior to creating a new automation that would have the same function In the automation condition, firstly compare integers, then characters and lastly the most intensive comparisons regular expressions Ensure that the automation trigger does not catch events it has already processed (especially important for external script) Stagger automation priority rates so they do no all fire at the same time Add a description to all newly created automations Do not execute a for each row within a database trigger Automations should update the journal entry if they modify events in the ObjectServer

4.3

Automation Frequently Asked Questions (FAQ)

Can I add a new field in the ObjectServer? o You can add a new field to the ObjectServer if there is no existing field in the ObjectServer that has the same purpose. Refer the Adding and Editing Table Columns section of the Configuring System Components for more details.

Can I alter an existing field in the ObjectServer? o While you can technically alter an existing field in the ObjectServer, your integration will not likely successfully pass the technical validation if it alters an existing field. Instead, a new field should be created.

Can I add a new automation in the ObjectServer? o You can add a new automation to the ObjectServer if there is no existing automation in the ObjectServer that has the same purpose. Refer the Configuring Automations section of the Tivoli Netcool/OMNIbus manual for more details.

63

Creation of a Tivoli Netcool/OMNIbus Automation

Can I alter an existing automation in the ObjectServer? o While you can technically alter an existing automation in the ObjectServer, your integration will not likely successfully pass the technical validation if it alters an existing automation. Instead, a new automation should be created (which can be done by cut-and-pasting the existing automation, changing his name and description, and amending it as needed).

What data should I generate to test the integration and submit it to IBM for validation? o This information is found in the Ready for IBM Tivoli software Product Requirements Document For Tivoli Netcool/OMNIbus 7.x Integrations (PRD) under the section entitled Tivoli Netcool/OMNIbus Minimum Test Scenario Requirements

4.4

Automation Creation Check List

All SQL select statements are as narrow in scope as they can be Automation works only on the events that are supposed to trigger the automations Comments are meaningful, clear and complete

4.5

Automation Examples

Please refer to the default automations that are provided out of the box in the ObjectServer. Other automations examples are documented in the Tivoli Netcool/OMNIbus manual: Standard Tivoli Netcool/OMNIbus Automations

64

Creation of a Tivoli Netcool/OMNIbus Automation

4.6

Documenting an Automation Based Integration

The following are required for automation integration documentation: Integration datasheet Users guide or equivalent (must include the description of the integration and the integration installation steps) List of all scripts or executables called by the tools, their functions and expected locations. (Can be included in Users Guide)

65

Integration Submission Packaging

Integration Submission Packaging

5.1

Archiving tool

The files submitted to IBM for validation purposes need to be packaged up. Please package them in either a .zip file or a compressed tar file like *.tar.gz or *.tar.Z. For the integrations that cross over multiple platforms, please ensure that any files created on the windows platforms are converted using a utility like dos2unix for compatibility with UNIX systems.

5.2

Files Names

The file name should begin with the company name or acronym followed by an underscore, then a descriptive of the integration, such as the name of the product we are integrating with, followed by _rft_OMNIbus. Example So for the company ABC with a product called Xyz, the integration files could be named any of the following: ABC_Xyz_rft_OMNIbus.tar.gz ABC_Xyz_rft_OMNIbus.tar.Z ABC_Xyz_rft_OMNIbus.zip

66

APPENDIX: GLOSSARY OF TERMS


This section provides a list of the terms and acronyms used within this document.

1-10

A
Automation Abstract Syntax Notation 1 (ASN.1) Abstract Syntax Notation 1 (ASN.1) - A language used for defining data types. ASN.1 is used in OSI standards and TCP/IP network management specifications.

C
CEF Common Event Format See Common Event Format. Events collected by probes and monitors are structured into a common format for consolidation at the ObjectServer. The default format is configurable through the ObjectServer schema and usermaintainable probe/monitor rules files.

D
Deduplication Deduplication is the technique applied to the management of alarms where a single device may generate the same error repeatedly until the problem is dealt with. Repeated alerts are identified and stored as a single alert to reduce the amount of data that the operator has to manage.

vi

G
Gateways Bi-directional interfaces that allow Netcool ObjectServer data to be shared with other ObjectServers, RDBMS archives, or troubleticketing applications.

H-J

K/L

M
Management Interface Base (MIB) Management Interface Base (MIB) - A logical database made up of the configuration, status and statistical information stored at a device.

vii

N-O
ObjectServer An in-memory database, optimized for collecting events and designing filters and views, which provides the core processing functions for the Netcool suite.

P
Probe Passive supersets of code that collect event data from more than 300 management data sources. Collected data is filtered, stored, viewed, and manipulated in the Netcool ObjectServer.

Q/R

S
Syslog Syslog is a standard for forwarding log messages in an IP network. The term "syslog" is often used for both the actual syslog protocol, as well as the application or library sending syslog messages. The syslog protocol is a very simplistic protocol: the syslog sender sends a small textual message (less than 1024 bytes) to the syslog receiver. The receiver is commonly called "syslogd", "syslog daemon" or "syslog server". Syslog messages can be sent via UDP and/or TCP. SNMP The simple network management protocol (SNMP) forms part of the internet protocol suite as defined by the Internet Engineering Task Force (IETF). SNMP is used by network management systems to monitor network-attached devices for conditions that warrant administrative attention. It consists of a set of standards for network management, including an Application Layer protocol, a database schema, and a set of data objects. The SNMP's extensible design is achieved with management information bases (MIBs), which specify the management data of a device subsystem, using a hierarchical namespace containing object identifiers, implemented via ASN.1.

viii

T
TL1 Transaction Language 1 (TL1) is a widely used, "legacy", management protocol in telecommunications. It is a cross-vendor, cross-technology man-machine language, and is widely used to manage optical (SONET) and broadband access infrastructure in North America. It is defined in GR-831 by Bellcore (now Telcordia Technologies). The TL1 language consists of a set of messages. There are 4 kinds of messages: 1. Input message - This is the command sent by the user or the OSS. 2. Output/Response message - This is reply sent by the NE in response to an input message. 3. Acknowledgment message - This is an acknowledgment of the receipt of a TL1 input message and is sent if the response message will be delayed by more than 2 seconds. 4. Autonomous message - These are asynchronous messages (usually events or alarms) sent by the NE.

U-Z

ix

REFERENCES
IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide

IBM Tivoli Netcool/OMNIbus User Guide

IBM Tivoli Netcool/OMNIbus Administration Guide

IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide

Ready for IBM Tivoli Software Product Requirements Document For Tivoli Netcool/OMNIbus 7.x Integrations (PRD)


Copyright IBM Corporation 2007 IBM United States of America Produced in the United States of America All Rights Reserved The e-business logo, the eServer logo, IBM, the IBM logo, OS/390, zSeries, SecureWay, S/390, Tivoli, DB2, Lotus and WebSphere are trademarks of International Business Machines Corporation in the United States, other countries or both. Lotus, Lotus Discovery Server, Lotus QuickPlace, Lotus Notes, Domino, and Sametime are trademarks of Lotus Development Corporation and/or IBM Corporation. Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries or both. Other company, product and service names may be trademarks or service marks of others. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PAPER 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. Information in this paper as to the availability of products (including portlets) was believed accurate as of the time of publication. IBM cannot guarantee that identified products (including portlets) will continue to be made available by their suppliers. This information could include technical inaccuracies or typographical errors. Changes may be made periodically to the information herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this paper at any time without notice. Any references in this document 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 have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation 4205 South Miami Boulevard Research Triangle Park, NC 27709 U.S.A.