Tsrmgw PDF

8/17/2019 Tsrmgw PDF

1/66

IBM® Tivoli® Netcool/OMNIbus Gateway for TSRM Version 4.0

Reference Guide November 8, 2013

SC27-2703-07


2/66


3/66

IBM® Tivoli® Netcool/OMNIbus Gateway for TSRM Version 4.0

Reference Guide November 8, 2013

SC27-2703-07


4/66

NoteBefore using this information and the product it supports, read the information in “Notices and Trademarks,” on page 51.

Edition notice

This edition (SC27-2703-07) applies to version 4.0 of IBM Tivoli Netcool/OMNIbus Gateway for TSRM and to allsubsequent releases and modifications until otherwise indicated in new editions.

This edition replaces SC27-2703-06.

© Copyright IBM Corporation 2009, 2013.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.


5/66

Contents

About this guide . . . . . . . . . . . vDocument control page . . . . . . . . . . . v

Conventions used in this guide . . . . . . . vi i

IBM Tivoli Netcool/OMNIbus Gateway forTSRM . . . . . . . . . . . . . . . . 1Summary . . . . . . . . . . . . . . . 1Overview . . . . . . . . . . . . . . . 3

Bidirectional data flow . . . . . . . . . . 4XML template files . . . . . . . . . . . 5

Installing the gateway . . . . . . . . . . . 6Installing the gateway . . . . . . . . . . 6Installing the TAL library . . . . . . . . . 9Configuring the gateway server . . . . . . 1 0Setting environment variables . . . . . . . 1 0

Configuring the gateway . . . . . . . . . . 1 0Properties file. . . . . . . . . . . . . 11Map definition file . . . . . . . . . . . 26Startup command file . . . . . . . . . . 2 9Table replication definition file . . . . . . . 3 0Advanced properties . . . . . . . . . . 3 1

Configuring SSL connections . . . . . . . . 3 6Configuring TSRM . . . . . . . . . . . . 36

Configuring TSRM to receive journal entries fromNetcool/OMNIbus events . . . . . . . . 3 7

Retrieving additional fields from TSRM . . . . 3 8Configuring the TSRM event summary field . . 39Configuring TSRM for improved incidentreporting performance . . . . . . . . . . 4 0Fine tuning TSRM gateway event processing . . 42

Configuring Netcool/OMNIbus . . . . . . . 4 2Configuring log ticketing functions inNetcool/OMNIbus . . . . . . . . . . . 4 3Configuring the Netcool/OMNIbus Event List touse the launch-in-context tool . . . . . . . 4 3

Running the gateway . . . . . . . . . . . 4 4FIPS mode and encryption . . . . . . . . . 4 5Testing Netcool/OMNIbus communication withTSRM . . . . . . . . . . . . . . . . 46

Error messages . . . . . . . . . . . . . 46GatewayWatch messages . . . . . . . . . . 4 9Known issues. . . . . . . . . . . . . . 49

Appendix. Notices and Trademarks . . 51Notices . . . . . . . . . . . . . . . . 51Trademarks . . . . . . . . . . . . . . 53

© Copyright IBM Corp. 2009, 2013 iii


6/66

iv IBM Tivoli Netcool/OMNIbus Gateway for TSRM: Reference Guide


7/66

About this guide

The following sections contain important information about using this guide.

Document control pageUse this information to track changes between versions of this guide.

The IBM Tivoli Netcool/OMNIbus Gateway for TSRM documentation is providedin softcopy format only. To obtain the most recent version, visit the IBM TivoliNetcool Information Center:

http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.tivoli.namomnibus.doc/welcome_ptsm.htm

Table 1. Document modification history

Documentversion

Publicationdate Comments

SC27-2703-00 June 30, 2009 First IBM publication.

SC27-2703-01 June 4, 2010 Summary table updated.

Support for TSRM 7.2 added.

Updated installation information added.

Error handling information added to “Advancedproperties” on page 31.

Descriptions for the following properties added to“Properties and command line options” on page 11:v

Gate.TAL.StateChange FieldNamev Gate.TSRM.Optional UpdateURLListv Gate.TSRM.MapObject StructureSeparatorv Gate.TSRM. CloseOnDeleteListv Gate.TSRM. NonApplication ErrorTitlesv Gate.TSRM.ErrorCode FieldNamev Gate.TSRM.Timeout

Note added to the Gate.TAL.NBScriptFileName property.

Details about how to add sub-object structures to theincidents created in TSRM; see “Adding sub-objectstructures” on page 28.

© Copyright IBM Corp. 2009, 2013 v

http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.tivoli.namomnibus.doc/welcome_ptsm.htmhttp://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.tivoli.namomnibus.doc/welcome_ptsm.htmhttp://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.tivoli.namomnibus.doc/welcome_ptsm.htmhttp://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.tivoli.namomnibus.doc/welcome_ptsm.htm


8/66

Table 1. Document modification history (continued)

Documentversion


SC27-2703-02 February 25,2011

Information about using this guide added in“Conventions used in this guide” on page vii.

Summary information updated in “Summary” on page1.

New installation information added in “Installing thegateway” on page 6.

Gateway configuration information updated in“Configuring the properties file” on page 11.

Added descriptions for the following propertiesin“Properties and command line options” on page 11:v Gate.TSRM.Attribute TokenSeparatorv Gate.TSRM.Optional QueryURLListv Gate.TSRM.Socket Timeout

Removed references to the Gate.TAL.StateChangeFieldName property.

Added new Step 10 to configuration procedure in“Configuring TSRM to receive journal entries fromNetcool/OMNIbus events” on page 37.

TSRM event summary configuration information addedin “Configuring the TSRM event summary field” onpage 39.

Instructions for running the gateway updated in“Running the gateway” on page 44.

Error messages updated in “Error messages” on page46.

SC27-2703-03 August 26, 2011 Information about configuring SSL connections addedin “Configuring SSL connections” on page 36.

SC27-2703-04 March 2, 2012 Information about configuring SSL connections updatedin “Configuring SSL connections” on page 36.

vi IBM Tivoli Netcool/OMNIbus Gateway for TSRM: Reference Guide


9/66

Table 1. Document modification history (continued)

Documentversion


SC27-2703-05 September 30,2012

Descriptions for the following properties added to“Properties and command line options” on page 11:v Gate.TSRM.DateTimeFormatv Gate.TSRM.FilterExclusionListv Gate.TSRM.FilterRepeatedValuesv Gate.TSRM.PollTimeIntervalWindow

“Polling TSRM for unread tickets” on page 34 updatedwith filtering repeated values information.

“Removing reliance on the Maximo host clock” on page34 added.

Information about configuring SSL connections updatedin “Configuring SSL connections” on page 36.

“Configuring TSRM for improved incident reporting

performance” on page 40 added.“Fine tuning TSRM gateway event processing” on page42 added.

“Configuring the Netcool/OMNIbus Event List to usethe launch-in-context tool” on page 43

SC27-2703-06 November 30 ,2012

“Summary” on page 1 updated.

Support for TSRM 7.5 added.

“Installing the gateway” on page 6 updated.

Description for the following properties in “Configuringthe properties file” on page 11 updated:v Gate.TSRM.CloseOnDeletev Gate.TSRM.Version

“Table replication definition file” on page 30 updated.

“Known issues” on page 49 added.

SC27-2703-07 November 8,2013

“Summary” on page 1 updated.

“FIPS mode and encryption” on page 45 updated.

“Startup command file” on page 29 added to the guide.

“Table replication definition file” on page 30 updated.

Conventions used in this guideAll gateway guides use standard conventions for operating system-dependentenvironment variables and directory paths.

About this guide vii


10/66

Operating system-dependent variables and paths

All gateway guides use standard conventions for specifying environment variablesand describing directory paths, depending on what operating systems the gatewayis supported on.

For gateways supported on UNIX and Linux operating systems, gateway guidesuse the standard UNIX conventions such as $variable for environment variables andforward slashes ( / ) in directory paths. For example:

$OMNIHOME/gates

For gateways supported only on Windows operating systems, gateway guides usethe standard Windows conventions such as %variable% for environment variablesand backward slashes ( \ ) in directory paths. For example:

%OMNIHOME%\gates

For gateways supported on UNIX, Linux, and Windows operating systems,gateway guides use the standard UNIX conventions for specifying environmentvariables and describing directory paths. When using the Windows command linewith these gateways, replace the UNIX conventions used in the guide withWindows conventions. If you are using the bash shell on a Windows system, youcan use the UNIX conventions.

Note: The names of environment variables are not always the same in Windowsand UNIX environments. For example, %TEMP% in Windows environments isequivalent to $TMPDIR in UNIX and Linux environments.

Operating system-specific directory names

Where Tivoli Netcool/OMNIbus files are identified as located within an arch

directory under NCHOME or OMNIHOME, arch is a variable that represents youroperating system directory. For example:

$OMNIHOME/gates/arch /

The following table lists the directory names used for each supported operatingsystem.

Table 2. Directory names for the arch variable

Operating system Directory name represented by arch

AIX® systems aix5

HP-UX PA-RISC-based systems hpux11

HP-UX Integrity-based systems hpux11hpiaRed Hat Linux and SUSE systems linux2x86

Linux for System z ® linux2s390

Solaris systems solaris2

Windows systems win32

viii IBM Tivoli Netcool/OMNIbus Gateway for TSRM: Reference Guide


11/66

IBM Tivoli Netcool/OMNIbus Gateway for TSRM

The IBM Tivoli Netcool/OMNIbus Gateway for TSRM provides bidirectionalcommunication between Netcool/OMNIbus and Tivoli Service Request Manager(TSRM).

The gateway supports TSRM version 7.1 (Fix Pack 4 and later), TSRM version 7.2,IBM SmartCloud Control Desk V7.5, and IBM ® Maximo ® Base Services (MBS)version 7.1.1.5.

Note: IBM Maximo is also known as IBM Tivoli ® Process Automation Engine(TPAE).

This guide contains the following sections:v “Summary”v “Overview” on page 3v “Installing the gateway” on page 6v “Configuring the gateway” on page 10v “Configuring SSL connections” on page 36v “Configuring TSRM” on page 36v “Configuring Netcool/OMNIbus” on page 42v “Running the gateway” on page 44v “Testing Netcool/OMNIbus communication with TSRM” on page 46v “Error messages” on page 46v “GatewayWatch messages” on page 49

SummaryEach gateway works in a different way to provide an interface with theObjectServer. Use this summary information to learn about the Gateway for TSRM.

The following table provides a summary of the gateway:

Table 3. Summary

Gateway target TSRM v7.1 (Fix Pack 4 and above)

TSRM v7.2 running with MBS 7.1.1.5

TSRM v7.5

Gateway executable file name nco_g_tsrm

Gateway installation package omnibus-arch -gateway-nco_g_tsrm-version

Package version 4.0

Gateway supported on For details of supported operating systems, see thefollowing Release Notice on the IBM Software Supportwebsite:

https://www-304.ibm.com/support/docview.wss?uid=swg21610165

© Copyright IBM Corp. 2009, 2013 1

https://www-304.ibm.com/support/docview.wss?uid=swg21610165https://www-304.ibm.com/support/docview.wss?uid=swg21610165https://www-304.ibm.com/support/docview.wss?uid=swg21610165https://www-304.ibm.com/support/docview.wss?uid=swg21610165


12/66

Table 3. Summary (continued)

Configuration files $OMNIHOME/etc/NCO_GATE.props

$OMNIHOME/gates/tsrm/tsrm.map

$OMNIHOME/gates/tsrm/tsrm.script

$OMNIHOME/gates/tsrm/tools.sql

$OMNIHOME/gates/tsrm/tsrm.rdrwtr.tblrep.def

$OMNIHOME/gates/tsrm/create.xml.template

$OMNIHOME/gates/tsrm/journal.xml.template

$OMNIHOME/gates/tsrm/query.xml.template

$OMNIHOME/gates/tsrm/update.xml.template

Additional binaries nco_g_tsrm.jar

Requirements IBM Tivoli Netcool/OMNIbus V7.2.1 (and above)

Maximo Business Services (MBS) version 7.1.1.5

Service Request Manager ® (SRM) version 7.1.0.4 with FixPack 4 (and above)

Java™ Gateway Infrastructure library: libngjava-3_0

Ticketing Abstraction Layer (TAL) library: libtal-5_0

Gateway NGtkTK Support Package: gateway-libngtktk-2_0

Note: libngjava and libtal require one of the followingversions of Netcool/OMNIbus:v V7.2.1 with Fix Pack 3 (and above)v V7.3.0v V7.3.1v V7.4.0

Note: On the Windows operating system a minimum of Java 1.5 is required.

Failover/failback functionality Available

Multicultural support Available

For information about configuring multicultural support,including language options, see the IBM TivoliNetcool/OMNIbus Installation and Deployment Guide.

Note: Installations of the gateway on Windows operatingsystems do not support UTF-8 character encoding. Forsome languages, such as Traditional Chinese, the gatewayis therefore unable to correctly pass events from theObjectServer to TSRM. UTF-8 character encoding isavailable for installations of the gateway on UNIX andLinux operating systems.

2 IBM Tivoli Netcool/OMNIbus Gateway for TSRM: Reference Guide


13/66

Table 3. Summary (continued)

IP environment IPv4 and IPv6

Note: IPv6 is supported on Netcool/OMNIbus V7.2.0 orlater on UNIX and Linux operating systems, and onNetcool/OMNIbus V7.2.1 or later on Windows operatingsystems.

Federal InformationProcessing Standards (FIPS)

IBM Tivoli Netcool/OMNIbus V7.3.0, 7.3.1 and 7.4.0 usethe FIPS 140-2 approved cryptographic provider: IBMCrypto for C (ICC) certificate 384 for cryptography. Thiscertificate is listed on the NIST web site athttp://csrc.nist.gov/cryptval/140-1/1401val2004.htm. Fordetails about configuring Netcool/OMNIbus for FIPS 140-2mode, see the IBM Tivoli Netcool/OMNIbus Installation andDeployment Guide.

OverviewIBM Tivoli Service Request Manager (TSRM) is an incident management system.

TSRM can function as a service desk for both internal IT assets and internal non-ITassets (such as facilities or fleet). TSRM helps to improve IT performance byproviding automation of processes and better visibility of service supportfunctions, commitments, and measurements.

The Gateway for TSRM is a bidirectional gateway that allows you to create,update, and close tickets (either incidents or service requests) in TSRM, using XMLover HTTP. The gateway allows you to create and maintain TSRM tickets fromNetcool/OMNIbus events, either manually (using a TSRM user interface withinNetcool/OMNIbus) or automatically (using scripts). There is a one-to-one mapping between a single Netcool/OMNIbus event and a single TSRM ticket.

The gateway supports the following functions:v Flexible filtering that allows you to specify which event details are sent from

Netcool/OMNIbus to TSRM.v Mapping of Netcool/OMNIbus alerts.status fields to any fields in the TSRM

schema.v Assignment of literal values (for example, varchar, int, date) to specified fields in

the TSRM schema.v Conversion of data types.v Failover between Netcool/OMNIbus and TSRM.v Failback between Netcool/OMNIbus and TSRM can be configured using the

Gate.RdrWtr.FailbackEnabled property.v Sub-object structures within TSRM.v Reporting within Netcool/OMNIbus of TSRM operation failures.v Separate URLs for creating new incidents and updating existing incidents.v Mapping of Netcool/OMNIbus severities to any TSRM priorities, for more

information see “Mapping attributes” on page 27v Closing tickets in TSRM when the associated event in Netcool/OMNIbus is

deleted can be configured by specifying the Gate.TSRM.CloseOnDeleteListproperty.

v Creation of journal entries, for more information see “Configuring TSRM toreceive journal entries from Netcool/OMNIbus events” on page 37.

IBM Tivoli Netcool/OMNIbus Gateway for TSRM 3

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


14/66

To facilitate bidirectional operation, the gateway uses IBM Tivoli Maximo and theTicket Abstraction Layer (TAL) library. Maximo provides the integration frameworkrequired to integrate TSRM with external applications. In the context of thisintegration, the gateway is regarded as an external application. The TAL library issupplied as a separate patch. It provides the infrastructure required to generateTSRM tickets from Netcool/OMNIbus events and to exchange ticket data withTSRM.

Note: Not all fields have bidirectional data flow enabled by default. You can add bidirectional support to additional fields, for more information see “Mappingattributes” on page 27 and “Sending data from TSRM to the ObjectServer” on page29.

Note: The gateway can generate either incidents or service requests, but not both.If you want to create both incidents and service requests from Netcool/OMINbusevents, you must run two instances of the gateway. The bidirectional transfer of journals is not currently supported. Journal entries within the ObjectServer arecreated in TSRM as work log entries, but work log entries are not forwarded fromTSRM to the ObjectServer as journals.

Bidirectional data flowThe Gateway for TSRM enables bidirectional flow of data between theObjectServer and TSRM.

The following diagram shows the flow of data between the ObjectServer andTSRM.



15/66

The gateway can create a TSRM ticket from an event in the Netcool/OMNIbus

Event List by mapping fields in the ObjectServer to fields in TSRM.

Once a ticket is created, you can add a journal to the original event in theObjectServer. The gateway passes the data to the TSRM where it is converted intoa work log.

If the status of the ticket within TSRM changes, the gateway passes the changedstatus back to the ObjectServer.

XML template filesThe gateway is supplied with a set of XML template files that determine how thegateway exchanges data between Netcool/OMNIbus and TSRM.

The XML template files define how the gateway performs the following functions:v Creating TSRM tickets from Netcool/OMNIbus events.v Querying TSRM for ticket details.v Updating existing TSRM tickets.v Creating TSRM work logs from Netcool/OMNIbus journal entries.

Figure 1. Data flow between the ObjectServer and TSRM



16/66

Before you can use the XML template files, you must add the structure for incidentand work log objects to the TSRM object structure using Maximo. For details of how to do this, see “Configuring TSRM to receive journal entries fromNetcool/OMNIbus events” on page 37.

If your implementation of TSRM uses sub-object structures (for example, toassociate one or more assets with a ticket), you can define the sub-object structurethat the gateway must add to incidents created within Netcool/OMNIbus bycustomizing the map definition file. This adds the appropriate code to the XMLtemplate files. For details, see “Adding sub-object structures” on page 28.

Installing the gatewayThe Gateway for TSRM and its related patches are installed as described below.

To install the Gateway for TSRM, use the following steps:1. Install the gateway.2. Install the TAL library and automations.

Note: The TAL library and automations are installed by default with OMNIbus7.3.0 and above.

3. Configure the gateway server.4. Set environment variables.

Installing the gatewayThere are separate procedures for installing the gateway on TivoliNetcool/OMNIbus V7.3.0, or later and on Tivoli Netcool/OMNIbus V7.2.1.

Follow the procedure for the version of Tivoli Netcool/OMNIbus that your siteuses.

Installing the gateway on Tivoli Netcool/OMNIbus V7.3.0 or laterWith the introduction of Tivoli Netcool/OMNIbus V7.3.0 and later versions, allgateways are installed using the Tivoli Netcool/OMNIbus installer.

You can install the gateway using any of the following:v “The installation wizard” on page 7v A text-based installer ( “Console mode” on page 7)v Settings predefined in a text file ( “Silent mode” on page 7)

The installation package and patches for the gateway are supplied as archives. Thearchive management application that you use to extract the files must be able topreserve the directory structure contained in the archive on extraction.

Note: If you are installing a 32-bit gateway on a system that runs a 64-bit UNIX orLinux operating system, you will need to install additional, 32-bit operating systemlibraries. See the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide formore information.

Obtaining the installation package

To obtain the installation package and prepare it for installation use the followingsteps:



17/66

1. Download the installation package for the gateway from the PassportAdvantage Online Web site:http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

2. Make a backup of any existing configuration files that you want to retain.3. Extract the contents of the installation package to a temporary directory.

Now use one of the installation methods to install your gateway. In each case, thegateway is installed in the following directory:

Linux UNIX $NCHOME/omnibus/gatesWindows %NCHOME%\omnibus\gates

The installation wizard

To install the gateway using the installation wizard:1. Run the installer for your operating system:

Linux UNIX $NCHOME/omnibus/install/nco_install_integrationWindows %NCHOME%\omnibus\install\nco_install_integration

2. When the installation wizard starts, specify the extracted directory that containsthe README.txt file as the location of the gateway installation files.

3. Accept the license conditions.

Console mode

To install the gateway in console mode:1. Run the installer for your operating system:

Linux UNIX $NCHOME/omnibus/install/nco_install_integration -iconsole

Windows %NCHOME%\omnibus\install\nco_install_integration -i console2. When the text-based installer starts, specify the extracted directory that contains

the README.txt file as the location of the gateway installation files.3. Accept the license conditions.

Silent mode

To install the gateway in silent mode:1. Create a text file named reponse.txt and add the following entries:

PROBE_OR_GATE_LOCATION=README_directorypathLICENSE_ACCEPTED=true

where README_directorypath is the path to the directory containing theREADME.txt file in the extracted package.2. Run the installer for your operating system:

Linux UNIX $NCHOME/omnibus/install/nco_install_integration -isilent -f response_path /response.txt

Windows %NCHOME%\omnibus\install\nco_install_integration -i silent-f response_path \response.txt

where response_path is the full path to the response.txt file.


http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htmhttp://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htmhttp://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htmhttp://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm


18/66

Installing the gateway on Tivoli Netcool/OMNIbus V7.2.1The process of installing gateways on Tivoli Netcool/OMNIbus V7.2.1 consists of downloading the appropriate gateway installation package, downloading thepackages for each gateway dependency, installing the gateway patch contained inthe gateway package, and installing the patch for each dependency contained intheir respective packages.

The installation package for the gateway is supplied as a compressed archive. Itcontains the patch version of the gateway in the patches subdirectory and aREADME.txt file that lists the gateway dependencies. The dependencies are suppliedas packages that you must download separately. Each dependency packagecontains the patch version of the dependency in its patches subdirectory.

Note: The archive management application that you use to extract the files must be able to preserve the directory structure contained in the archive on extraction.

To install the gateway:1. Download the installation package for the gateway from the Passport

Advantage Online Web site:

http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

2. Make a backup of any existing configuration files that you want to retain.3. Extract the contents of the installation package to a temporary directory.4. In the temporary directory, locate and read the README.txt file.

The README.txt file will tell you if you need to download any furtherdependencies from the Passport Advantage Online Web site.

5. Download the install packages for all dependencies listed in the README.txtfile.

6. Extract the contents of each dependency installation package to a temporarydirectory.

7. Locate the patches directory for the gateway (under the directory containingthe README.txt file).This directory contains the patch for the gateway.

8. Windows Extract the patch files for the gateway and its dependencies to thefollowing directory:%OMNIHOME%

9. Linux UNIX Consult the README.txt file to determine the order inwhich the gateway and any dependency patches must be installed.

10. Linux UNIX Install each patch, in the correct order, by running thefollowing command:$OMNIHOME/install/nco_patch -install patch_pathwhere patch_path is the path to the extracted patch file.

Note: Linux UNIX At any point in the installation process, you can seewhat patches have been installed by running the following command:

$OMNIHOME/install/nco_patch -print=id


http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htmhttp://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htmhttp://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htmhttp://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm


19/66

Installing the TAL libraryThe Ticket Abstraction Layer (TAL) library provides the infrastructure required togenerate TSRM tickets from Netcool/OMNIbus events and to exchange ticket datawith TSRM.

Installation involves the following steps:

Note: The TAL library and automations are installed by default with OMNIbus7.3.0 and above.1. Installing the TAL library.2. Installing the TAL automations.

Installing the TAL library on Tivoli Netcool/OMNIbus V7.2.1

To install the TAL library on UNIX and Linux operating systems, use the followingsteps:1. Make a backup of any existing configuration files you may already have.2. Extract the contents of the installation package to a temporary directory.

3. Locate the extracted patches directory.This directory contains the installation files for the library.

4. Run the following command:$OMNIHOME/install/nco_patch -install patch_pathwhere patch_path is the path to the extracted patches directory.

To install the TAL library on Windows operating systems, use the following steps:1. Make a backup of any existing configuration files you may already have.2. Extract the contents of the installation package to a temporary directory.3. Locate the extracted patches directory.

This directory contains the installation files for the library.4. Extract the files in the patches directory to the %OMNIHOME% directory.

Installing TAL automationsAfter installing the TAL library, you must install the TAL automations. Theinstallation steps are the same regardless of which version of IBM TivoliNetcool/OMNIbus you are using.

To install the TAL automations on UNIX and Linux operating systems, run thefollowing commands using the Netcool/OMNIbus SQL interactive interface utility(nco_sql):

nco_sql -U username -P password -S obj_serv < $OMNIHOME/gates/tal/tal_automations.sql

nco_sql -U username -P password -S obj_serv < $OMNIHOME/gates/tsrm/tsrm.sql

where:v username is the name of the user authorized to run Netcool/OMNIbus.v password is the password associated with this user.v obj_serv is the name of ObjectServer instance to which the gateway will connect.



20/66

To install the TAL automations on Windows operating systems, copy the contentsof the following files into the Netcool/OMNIbus Administrator SQL interactiveinterface window and click the Execute SQL button:

%OMNIHOME%\gates\tal\tal_automations.sql

%OMNIHOME%\gates\tsrm\tsrm.sql

Note: For information about using the Netcool/OMNIbus Administrator and SQLinteractive interface utility, see the IBM Tivoli Netcool/OMNIbus AdministrationGuide.

Configuring the gateway serverYou must create the gateway server in the Netcool/OMNIbus interfaces file.

Use the Server Editor ( nco_xigen) to specify the hostname and port number of thegateway host in the Netcool/OMNIbus interfaces file. If you want to run multiplegateways, you must use a different name for each instance.

Use the following hostname for the primary gateway server:

GAT_TSRM

Note: For information about using the Server Editor, see the IBM TivoliNetcool/OMNIbus Administration Guide .

Setting environment variablesEnvironment variables are specific preset values that establish the workingenvironment of the gateway. From the environment variable specified, the gatewayreceives path information for the directories in which library files are present.

Note: This information only applies to gateway installations on Windowsoperating systems. If you are installing the gateway on a UNIX or Linux operatingsystem, you may skip this procedure.

On Windows 2003 and Windows XP add the following directories to the %PATH%environment variable:v %NCHOME%\platform\win32\jre_1.5.6\jre\binv %NCHOME%\platform\win32\jre_1.5.6\jre\bin\classic

On Windows 2008 add the following directories to the %LIBPATH% environmentvariable:v %NCHOME%\platform\win32\jre_1.5.6\jre\binv

%NCHOME%\platform\win32\jre_1.5.6\jre\bin\classicNote: To use the gateway with IBM Tivoli Netcool/OMNIbus V7.3.1, you musthave Java 1.6 installed. You must also adjust the %PATH% or %LIBPATH% environmentvariable accordingly.

Configuring the gatewayThe gateway uses centralized property management, which separates propertiesfrom data processing configuration.



21/66

Use the properties file to configure properties and the map definition and tablereplication definitions to configure data processing.

Note: You must have write access permissions to the directory where you want torun the gateway or you will get an error message referring to derby.log or'FileNotFoundException' , for more information see “Known issues” on page 49.

The following topics describe the configuration files and how to use them:v “Properties file”v “Map definition file” on page 26v “Table replication definition file” on page 30v “Advanced properties” on page 31

Properties fileThe properties file is a text file that contains a set of properties and theircorresponding values. These properties define the operational environment of thegateway, such as connection details and the location of the other configurationfiles.

Configuring the properties fileBefore running the gateway for the first time, you must rename the installedproperties file and specify some basic properties.

To configure the properties file, use the following steps:1. Rename the properties file that came with the installation package:

a. Copy the NCO_GATE.props file to the $OMNIHOME/etc directory.b. Change the name of the copied file from NCO_GATE.props to GAT_TSRM.props.

2. After renaming the properties file, specify the following property values in thenew GAT_TSRM.props file:

Property ValueMessageLog $OMNIHOME/log/GAT_TSRM.logName GAT_TSRMPropsFile $OMNIHOME/etc/GAT_TSRM.props

3. If you have Java security enabled, use the Gate.TSRM.UserName andGate.TSRM.Password properties to specify the user name and password requiredto access TSRM.

Note: If you do not have Java security enabled, you do not need to specifyvalues for these properties.

4. Edit the remaining values in the properties file to suit your operatingenvironment.

Properties and command line optionsYou use properties to define the operational environment of the gateway. You canoverride the default values by editing the properties file or by using the commandline options.



22/66

The following tables describe the properties available with the SNMP WriterGateway. For more information about generic and Inter-Process Communication(IPC) properties and command line options, see the IBM Tivoli Netcool/OMNIbusProbe and Gateway Guide (SC23-6387).

The following sections describe the properties used to configure the gateway:v “Common Netcool/OMNIbus properties”v “Generic gateway properties” on page 14v “Java properties” on page 15v “Mapping properties” on page 15v “Gateway Reader-Writer properties” on page 16v “Ticket Abstraction Layer (TAL) properties” on page 18v “Gateway-specific properties” on page 20

Common Netcool/OMNIbus properties

Table 4 lists the available common properties.

Table 4. Common Netcool/OMNIbus properties Property name Command line option Description

ConfigCryptoAlg string -configcryptoalg string Use this property to specifythe encryption algorithm thatthe gateway uses.

The default is AES.ConfigKeyFile string -configkeyfile string Use this property to specify

the encryption key used withthe encrypted data.

The default is "" .Connections integer -connections integer Use this property to specify

the maximum number of client connections that can bemade to the gateway server.

The default is 30.Help boolean -help boolean Use this property to instruct

the gateway to displayapplication help informationon startup and exit.

The default is FALSE.MaxLogFileSize integer -maxlogfilesize integer Use this property to specify

the size (in bytes) that the

gateway allocates for the logfile. When the log filereaches this size, the gatewayrenames the log file byappending the suffix .oldand creates a new log file.

The default is 1024.



23/66

Table 4. Common Netcool/OMNIbus properties (continued)

Property name Command line option Description

MessageLevel string -messagelevel string Use this property to specifythe reporting level of the logfile messages.

The default is warn.MessageLog string -messagelog string Use this property to specify

the location of the messagelog file.

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

Name string -name string Use this property to specifythe name of the currentgateway instance. If youwant to run multiplegateways on one machine,you must use a differentname for each instance.

The default is GAT_TSRM.Props.CheckNames boolean No command line

equivalent.Use this property to instructthe gateway to shut down if any property in theproperties file is set to aninvalid value.

The default is TRUE.PropsFile string -propsfile string Use this property to specify

the location of the gatewayproperties file.

The default is$OMNIHOME/etc/NCO_GATE.props.

UniqueLog boolean -uniquelog boolean Use this property to specifythat log file names are madeunique by adding theProcess ID (PID) of thegateway to the file name.

The default is FALSE.Version boolean -version boolean Use this property to instruct

the gateway to displayinformation about theapplication version onstartup and shutdown.

The default is FALSE.



24/66


25/66

Table 5. Generic gateway properties (continued)


Gate.UsePamAuth boolean -usepamauth boolean Use this property to specifywhether PAM authenticationis used.


Note: To run the gateway inFIPS 140-2 mode, you mustset this property to TRUE.

Java properties

Table 6 lists the available Java properties.

Table 6. Java properties


Gate.Java.Arguments string -javaarguments string Use this property to specifythe arguments to use whenstarting Java.

The default is "" .Gate.Java.ClassPath string -javaclasspath string Use this property to specify

the environment variableused to store the location of the Java libraries.

The default is $CLASSPATH.Gate.Java.Debug boolean -javadebug boolean Use this property to enable

the logging of Java debugmessages.

The default is TRUE.Gate.Java.LibraryPath string -javalibrarypath string Use this property to specify

the location of the Javalibraries that will be set inthe environment variablespecified by theGate.Java.ClassPathproperty.

The default is "" .

Mapping properties

Table 7 lists the available mapping properties.

Table 7. Mapping properties


Gate.Mapper.Debug boolean -mapperdebug boolean Use this property to enablethe logging of mapper debugmessages.

The default is TRUE.



26/66

Gateway Reader-Writer properties

Table 8 lists the available gateway reader-writer properties.

Table 8. Gateway Reader-Writer properties


Gate.RdrWtr.Debug boolean -debug boolean Use this property to enablethe logging of gatewayreader debug messages.

The default is TRUE.Gate.RdrWtr.Descriptionstring

-description string Use this property to specifythe application descriptionfor the reader connection.This description is used intriggers and allows you todetermine which componentof the gateway attempted toperform an action.

The default is ticket_gate .Gate.RdrWtr.FailbackEnabled boolean

-readerfailbackenabledboolean

Use this property to specifywhether the gatewayattempts to fail back to theprimary ObjectServerfollowing a ObjectServerfailover.


Note: The gateway attemptsto fail back with thefrequency specified by theGate.RdrWtr.FailbackTimeout

property.Gate.RdrWtr.FailbackTimeout integer

-readerfailbacktimeoutinteger

Use this property to specifythe frequency (in seconds)with which the gatewayattempts to fail back to theprimary system following asystem failover.

The default is 30.

Note: The gateway attemptsto fail back to the primaryObjectServer only if theGate.RdrWtr.

FailbackEnabled property isset to TRUE.



27/66

Table 8. Gateway Reader-Writer properties (continued)


Gate.RdrWtr.IducFlushRateinteger

-iducflushrate integer Use this property to specifythe rate (in seconds) of thegranularity of the reader.

If you set this property to 0,the reader gets its updates atthe same granular rate asthat of the ObjectServer towhich it is connected.

The default is 0.

Note: If you set thisproperty to a value greaterthan 0, the reader issuesautomatic IDUC flushrequests to the ObjectServerwith this frequency. Thisenables the reader to run at a

faster granularity than thatof the ObjectServer, thusenabling the gateway tocapture more detailed eventchanges in systems wherethe ObjectServer itself hashigh granularity settings.

Gate.RdrWtr.LogOSSql boolean -logossql boolean Use this property to specifywhether the gateway logs allSQL commands sent to theObjectServer in debug mode.


Gate.RdrWtr.Password string -password string Use this property to specifythe password associated withthe user specified by theGate.RdrWtr.Usernameproperty.

The default is "" .

Note: You must encrypt thispassword using thenco_g_crypt utility. For moreinformation, see the IBMTivoli Netcool/OMNIbus Administration Guide.

Gate.RdrWtr.ReconnectTimeout integer -reconntimeout integer Use this property to specifythe time (in seconds)

between each reconnectionpoll attempt that the gatewaymakes if the connection tothe ObjectServer is lost.

The default is 30.



28/66

Table 8. Gateway Reader-Writer properties (continued)


Gate.RdrWtr.Server string -server string Use this property to specifythe name of the ObjectServerfrom which the gatewayreads alerts

The default is NCOMS.Gate.RdrWtr.TblReplicateDefFile string

-tblrepdeffile string Use this property to specifythe path to the tablereplication definition file.

The default is$OMNIHOME/gates/tsrm/tsrm.rdrwtr.tblrep.def .

Gate.RdrWtr.Username string -username string Use this property to specifythe user name used toauthenticate the ObjectServerconnection.

The default is root .

Ticket Abstraction Layer (TAL) properties

Table 9 lists the available TAL properties.

Table 9. TAL properties


Gate.TAL.ForwardClearUpdatesOnly boolean

-forwardclearupdatesboolean

Use this property to specifywhether the gateway onlysends update events toTSRM if they are clear

events.

The default is FALSE.Gate.TAL.NBScriptFileNamestring

-nbscriptfilename string Use this property to specifythe name of the scripting fileused for sending notificationdata to the ObjectServer.

The default is$OMNIHOME/gates/tsrm/tsrm.script .

Note: If you want to stopthe gateway polling requests,

you must leave this property blank.



29/66

Table 9. TAL properties (continued)


Gate.TAL.TTFilterClausestring

-ttfilterclause string Use this property to specifythe filter clause used in thetable replication definitionfile for the status table.

The default is LogTicket=1.

Note: You must specify thisvalue in the form of the SQLcondition of the WITHFILTER clause. For example,if the definition file uses thefilter WITH FILTERLogTicket=1, set thisproperty to LogTicket =1.

Gate.TAL.TTJournalChronoFieldName string

-ttjournalchronofieldnamestring

Use this property to specifythe target field name to usein the map for the journal

Chrono field.The default is Chrono.

Gate.TAL.TTNumberFieldName string

-ttnumberfieldname string Use this property to specifythe name of the field in theObjectServer alerts.statustable that stores the troubleticket number.

The default is TTNumber.

Note: You will need to createthe field that you specifywith this property within

Netcool/OMNIbus. Fordetails about how to do this,see “Adding a field to theObjectServer” on page 38.

Gate.TAL.TTStateFieldNamestring

-ttstatefieldname string Use this property to specifythe name of the integer fieldin the ObjectServeralerts.status table thatstores the trouble ticket state.

The default is TTState.



30/66

Gateway-specific properties

Table 10 lists the available gateway-specific properties.

Table 10. Gateway-specific properties


Gate.TSRM.AttributeTokenSeparator string

-attributetokenseparatorstring

Use this property to specify adefault separator for namingXML attribute-based tokenswhen processing thenorthbound Maximoresponse.

The default is _ATTR_.Gate.TSRM.CloseOnDeleteList string

-closeondeletelist string Use this property to specifywhether a ticket in TSRM isclosed if theNetcool/OMNIbus event forwhich it was originallycreated is deleted.

Specify the values for thisproperty as comma-delimitedname-value pairs in thefollowing format:"Name1='Value1', ...,NameN='ValueN'".

For example:"CLASS=’INCIDENT’,STATUS=’RESOLVED’"

The default is "" . Thefunction is not enabled bydefault.

Gate.TSRM.CreateTicketTemplate string

-tsrmcreatetickettemplatestring

Use this property to specifythe name of the XMLtemplate used to create theticket within TSRM.

The default is$OMNIHOME/gates/tsrm/create.xml.template .

Gate.TSRM.DateTimeFormatstring

-tsrmdatetimeformat string Use this property to specifythe date time format thegateway uses to process ticketupdates sent by Maximo tothe gateway.

The default isyyyy-MM-dd\'T\'HH:mm:ssZ.



31/66

Table 10. Gateway-specific properties (continued)


Gate.TSRM.ErrorCodeFieldName string

-errorcodefieldname string Use this property to specifythe ObjectServer field towhich the gateway sends theerror code that identifies thenature of the TSRM error. TheGate.TSRM.ErrorCodeFieldName property is used inconjunction with theGate.TSRM.NonApplicationErrorTitles property to workout what category the errors belong to. Any TSRM errorresponses that match theregular expression in theGate.TSRM.NonApplicationErrorTitles property willmap to error code 1.

This property takes thefollowing values:

0: the operation is successful.

1: the error is due to anintermittent issue, such as theserver being down, so theoperation can be retried.

2: the error is such that theoperation cannot be retried,such as an invalid field value.

The default is TSRMErrorCode.

Gate.TSRM.FilterRepeatedValuesboolean

-tsrmfilterrepeatedvaluesboolean

Use this property to specifywhether the gateway sendsonly event data that haschanged since the last polling.The filtering will be based onthe mapped values in thetsrm.map file and will omitthe mapped values specified by the Gate.TSRM.FilterExclusionListproperty.

The default is TRUE.Gate.TSRM.FilterExclusionList string

-tsrmfilterexclusionliststring

Use this property to specify alist of properties that are notfiltered by the gateway if theGate.TSRM.FilterRepeatedValues is setto true.

The default is 'TTNumber'.



32/66



Gate.TSRM.JournalTemplatestring

-tsrmjournaltemplate string Use this property to specifythe name of the XMLtemplate used to create worklogs in TSRM.

The default is$OMNIHOME/gates/tsrm/journal.xml.template .

Gate.TSRM.Language string -tsrmlanguage string Use this property to specifythe language code for thelanguage used by TSRM toprocess incoming data.

The default is EN.Gate.TSRM.MapObjectStructureSeparator string

-mapobjectstructureseparator string

Use this property to specifythe separator that thegateway uses betweensub-objects when generatingthe XML code that it sends toTSRM to create or updatetickets. See “Addingsub-object structures” on page28 for more information.

The default is "" .Gate.TSRM.MaxRetries integer -tsrmmaxretries integer Use this property to specify

the number of times that thegateway retries polling TSRMafter the occurrence of anerror, an HTTP timeout, or asocket-related exception, before shutting down.

The default is 5.Gate.TSRM.NonApplicationErrorTitles string

-nonapplicationerrortitlesstring

Use this property to specify acomma-delimited list of application error titles (sent by TSRM) that the gatewayshould interpret as connectionerrors.

The default is .*500 InternalServer Error.*

Gate.TSRM.OptionalUpdateURLList string

-optionalupdurllist string If your TSRM implementationrequires two URLs (one for

creating tickets and one forupdating tickets), use thisproperty to specify the URLneeded to communicate withTSRM for updating tickets.Otherwise, leave this property blank.

The default is "" .



33/66



Gate.TSRM.Password string -tsrmpassword string Use this property to specifythe TSRM passwordassociated with the user namespecified by theGate.TSRM.Username property.

The default is maxadmin.Gate.TSRM.PollTime integer -tsrmpolltime integer Use this property to specify

the frequency (in seconds)with which the gateway pollsTSRM.

The default is 30.Gate.TSRM.PollTimeIntervalWindow integer

-tsrmpolltimeintervalwindow integer

Use this property to specify adifferent CHANGEDATEformat for the gateway to useto determine new events inMaximo.

The default is -1 : Thisfunction is disabled.

Gate.TSRM.QueryRetrieveList string

-tsrmqueryretrieveliststring

Use this property to specify acomma-separated list of TSRM ticket attributes thatthe gateway sends back to theObjectServer for furtherprocessing.

The default is STATUS.

Note: If you add any TSRMfields to this list, you mustadd the XML structure forthat field to that of the TSRMincident or service request.For details of how to do this,see “Retrieving additionalfields from TSRM” on page38.

Gate.TSRM.QueryTicketTemplate string

-tsrmquerytickettemplatestring

Use this property to specifythe name of the XMLtemplate used to query theticket within TSRM.

The default is$OMNIHOME/gates/tsrm/query.xml.template .

Gate.TSRM.RetryIntervalinteger

-tsrmretryinterval integer Use this property to specifythe interval (in seconds) between successive polls of the TSRM.

The default is 15.



34/66



Gate.TSRM.SocketTimeoutinteger

-tsrmsockettimeout integer Use this property to specifythe length of time (inseconds) that the gatewaywaits for a response to arequested operation fromTSRM.

The default is 15.Gate.TSRM.SourceName string -tsrmsourcename string Use this property to specify

the name used to tagincidents and work logobjects. This allows you toindicate that the incident wascreated by the gateway.

The default is NETCOOL.Gate.TSRM.StatusFieldNamestring

-tsrmstatusfieldname string Use this property to specifythe name of the mapper fieldused to populate the STATUSworkflow attribute in TSRMtickets.

The default is STATUS.

Note: If the value of themapper field is empty, thealert is not forwarded to theTSRM server. This is useful ina scenario where you mightwant to set the alert toRESOLVED if the severity of the alert is clear (or for any

other reason you may notwant to forward it). That iswhy the following lookupdefinition is included in thetsrm.map file:CREATE LOOKUP StatusTable ({0, ’RESOLVED’})

DEFAULT= ’’;Gate.TSRM.ThreadPoolSzinteger

-tsrmthreadpoolsz integer Use this property to specifythe number of concurrentthreads that the gateway usesto communicate with TSRM.

The default is 5.

Note: In most cases, you willnot need to change this value.



35/66



Gate.TSRM.TicketObjectName string

-tsrmticketobjectnamestring

Use this property to specifythe object name for the TSRMincident or service requestobject.

The default is MXINCIDENT.

Note: If you are using thegateway to generate servicerequests instead of incidents,set this property to MXSR.

Gate.TSRM.TicketObjectType string

-tsrmticketobjecttypestring

Use this property to specifythe object type created by thegateway within TSRM.

The default is INCIDENT.

Note: If you are using thegateway to generate servicerequests instead of incidents,set this property to SR.

Gate.TSRM.TimeZone string -tsrmtzdiff string Use this property to specifythe timezone used by theTSRM server relative to GMT.For example, to specify fourhours behind GMT, set thisproperty to GMT-4.

The default is "" .

Note: If the gateway is beingrun in the same timezone asthe TSRM server, leave thisproperty blank.

Gate.TSRM.UpdateTicketTemplate string

-tsrmupdatetickettemplatestring

Use this property to specifythe name of the XMLtemplate used to update theticket within TSRM.

The default is$OMNIHOME/gates/tsrm/update.xml.template .

Gate.TSRM.URLList string -tsrmurllist string Use this property to specify acomma-delimited stringconsisting of the URLsrequired to communicate withTSRM.

The default ishttp:///meaweb/os/MXINCIDENT.

Note: If you are using theTSRM server failoverfunction, you must specifyeach URL separated bycommas.



36/66



Gate.TSRM.UserName string -tsrmusername string Use this property to specifythe name of the userauthorized to log on toTSRM.

The default is maxadmin.Gate.TSRM.Version string -tsrmversion string Use this property to specify

the version of TSRM withwhich the gateway cancommunicate.

The default is 7.5 .Gate.TSRM.WorkLogObjectName string

-tsrmworklogobjectnamestring

Use this property to specifythe object name of the TSRMwork log object name.

The default is WORKLOG.

Map definition fileMapping defines how the gateway replicates tables by assigning data toappropriate fields in the ObjectServer. The map definition file defines how thegateway maps data received from the TSRM to the Status, and Journal tableswithin the ObjectServer.

To specify the map definition file, use the Gate.MapFile property. The default mapdefinition file, tsrm.map, is located in the following directory:

$OMNIHOME/gates/tsrm/

Note: If you are upgrading from version 1.1.0 of the gateway to version 1.2.0 (orlater), you must populate the CLASS field of incidents with the value INCIDENT byadding the following entries to the CREATE MAPPING StatusMap and CREATE MAPPINGJournalMap sections of the map definition file:CREATE MAPPING StatusMap(’CLASS’ = ’INCIDENT’,...

...);

CREATE MAPPING JournalMap(’CLASS’ = ’INCIDENT’,

...

...);

Mapping syntaxYou can configure the mapping functions of the gateway by using the mapperattributes.

Mappings for use with the ObjectServer writer must use the following syntax:



37/66

CREATE MAPPING mappingname ( ’ dest_fieldname’ = ( ’@src_fieldname’ |simple_expression | attribute ) [ ON INSERT ONLY ] [ CONVERT TO type ][ NOT NULL (’@src_fieldname’)] [ , ’dest_fieldname’ =( ’@src_fieldname’ | simple_expression | attribute ) [ ON INSERT ONLY ][ CONVERT TO type ] [ NOT NULL (’@src_fieldname’)] ] ... ) ;

where:v

mappingname is the name of the mapping to be created.v dest_fieldname is the name of the field to be written in TSRM.v src_fieldname is the name of a field in the ObjectServer alerts.status table.v simple_expression is an integer or a set of integers and operators.v attribute is an attribute name.

The ON INSERT ONLY command is optional and only applies when setting the valueof variables. It controls the updating of the field during the life of the alert. WhenON INSERT ONLY is included, the field is created once for the alert but is neverupdated. When ON INSERT ONLY is omitted, the field is updated for any change inthe state of the alert.

The CONVERT TO type command enables forced conversion for situations where thedata type of a source field may not match the data type of a destination field. Thedata type can be INTEGER, STRING, or DATE.

The NOT NULL command indicates that the mapping is only performed if the sourcefield is not null (it must have a value).

Mapping attributesYou use attribute names to include additional data in mapping definitions.

Mapping attributes and advanced mapping topics are explained in the followingsections:v “Mapping example”v “Modifying the default mapping” on page 28v “Adding sub-object structures” on page 28v “Sending data from TSRM to the ObjectServer” on page 29

Mapping example

The following example shows the mappings for the ObjectServer tables into whichthe gateway writes:CREATE LOOKUP SeverityTable (

{3 , 3},{4 , 2},{5 , 1} )

DEFAULT = 4 ;CREATE LOOKUP StatusTable (

{0 , ’RESOLVED’})DEFAULT = ’’ ;

CREATE MAPPING StatusMap(’CLASS’ = ’INCIDENT’,’DESCRIPTION’ = ’@Node’ + ":" + ’@Summary’ ON INSERT ONLY,’REPORTEDBY’ = ’NETCOOL’,’REPORTDATE’ = TO_TIME(’@FirstOccurrence’) ON INSERT ONLY,’REPORTEDPRIORITY’ = Lookup(’@Severity’,’SeverityTable’),



38/66

’STATUS’ = Lookup(’@Severity’, ’StatusTable’),’TTNumber’ = ’@TTNumber’

);

CREATE MAPPING JournalMap(’CLASS’ = ’INCIDENT’,’Chrono’ = ’@Chrono’,

’CREATEDATE’ = TO_TIME(’@Chrono’),’DESCRIPTION’ = ’NETCOOL JOURNAL ENTRY’,’DESCRIPTION_LONGDESCRIPTION’ = TO_STRING(’@Text1’) + TO_STRING(’@Text2’)

+ TO_STRING(’@Text3’));

Within this map, @TTNumber and @Chrono are used to provide ticket feedback and toenable failover respectively. They also correspond to, and must be the same as, thevalues set for the Gate.TAL.TTNumberFieldName andGate.TAL.TTJournalChronoFieldName properties. In most cases you will not need tochange these field names but if you do change them you must also change theircorresponding values in the properties file.

Modifying the default mapping

You can modify the default mapping to send additional fields fromNetcool/OMNIbus. The gateway supports both flexible mappings and lookuptables.

For most fields that you want to add to those mapped to TSRM, you simply add anew item to the default map definition file.

For example, if you want to populate the REPORTEDEMAIL field of the incident withthe ContactName ObjectServer field, add the following line to the StatusMap sectionof the map definition file:

'REPORTEDEMAIL’ = '@ContactName’,

The gateway will take the new item and convert it to an XML token that is sentacross to the TSRM server. These are regarded as flexible mappings.

Certain values (those that use lookup tables) can only be mapped successfully if they are first configured to exist in TSRM. This applies to the following fields(among others):v OWNERv OWNERGROUPv CLASSIFICATION ID

For details of the TSRM fields that use lookup tables and how to configure them,refer to the IBM Tivoli SRM Administration Guide.

Adding sub-object structures

If your implementation of TSRM uses substructures (for example, to associate oneor more assets with a ticket), you can define the sub-object structure that thegateway must add to incidents created within Netcool/OMNIbus by customizingthe map definition file.



39/66

For example, if your implementation includes a sub-object structure for assetinformation, and for each asset you can specify its type and asset number, you canadd the following map definition to the map definition file:’MULTIASSETLOCCI.RECORDCLASS’ = ’INCIDENT’ ON INSERT ONLY,’MULTIASSETLOCCI.ASSETNUM’ = ’7200’ ON INSERT ONLY

You must then use the Gate.TSRM.MapObjectStructureSeparator property tospecify the separator that the gateway inserts between each asset associated withan incident. For example '\\\.'

In the following example, the gateway produces XML for new incidents createdfrom Netcool/OMNMIbus events (the sub-object structure is shown in bold):

2010-03-05T10:11:10+00:00

NETCOOLNCOMS/953

Sending data from TSRM to the ObjectServer

When sending data from TSRM to the ObjectServer, the gateway uses TALscripting support. This provides functionality similar to that provided by rulesfiles. To configure additional fields to be sent from TSRM to the ObjectServer addthe fields to the $OMNIHOME/gates/tsrm/tsrm.script file using the followingexample. In this example the TicketStatus field is set based on the STATUS tokenvalue.CASE_OP_TYPE STATUS_UPDATE:

update alerts.status via ’$Identifier’ set TicketStatus=’$STATUS’ whereServerName=’$ServerName’ and ServerSerial=$ServerSerial and (TicketStatus ’RESOLVED’ or ’$STATUS’’RESOLVED’);BREAK;END;

Note: The TicketStatus field is the only field enabled for bidirectional operation by default. For further information on extending the availability of TSRM fields,see “Adding a TSRM field to the list of fields retrieved by the gateway” on page39.

Startup command fileThe startup command file contains a set of commands that the gateway executeseach time it starts.



40/66

You can specify the location of the startup command file using the genericNetcool/OMNIbus Gate.StartupCmdFile property. The default startup commandfile gw_name.startup.cmd is located in the following directory:

$OMNIHOME/gates/ gw_name

Where the value for gw_name is found in the configuration files row of the gatewayguide summary table.

The default startup command file contains example commands. You should make acopy of the default file for future reference.

You can use the following commands within the startup command file:v GET PROPS | SHOW CONFIG - Use these commands to display the current

configuration of the gateway by listing all properties and their values.v GET PROPERTY ’ property ’ - Use this command to display the gateway property

value, where property is the property value you wish to query.v SET PROPERTY ’ prop ’ TO ( ’string ’ | integer | TRUE | YES | FALSE | NO ); -

Use this command to specify the value of a gateway property in the propertiesfile.

v SET LOG LEVEL TO - Use this command to set the level of message logging. Thiscommand can take the following values; FATAL, ERROR, WARNING, INFORMATIONor DEBUG. The default is DEBUG.

These commands can also be entered using the SQL interactive interface ( nco_sql).For more information about using the SQL interactive interface, see the IBM TivoliNetcool/OMNIbus Administration Guide .

For more information about the startup command file, see the IBM TivoliNetcool/OMNIbus ObjectServer Gateway guide

Table replication definition fileThe gateway replicates data between ObjectServer tables and the gateway target.The table replication definition file is used to define which tables and event typesare monitored in OMNIbus and forwarded to the target that the gateway isconfigured to send data to.

You can specify the location of the table replication definition file using one of thefollowing generic Netcool/OMNIbus properties. The property relevant to yourgateway depend on if it is a reader/writer gateway or a reader gateway.v Gate.RdrWtr.TblReplicateDefFile : Use this property with reader/writer

gateways.v Gate.Reader.TblReplicateDefFile : Use this property with reader gateways.

The default table replication definition file, either gw_name.rdrwtr.tblrep.def or gw_name.reader.tblrep.def , is located in the following directory:

$OMNIHOME/gates/ gw_name

Where the value for gw_name is found in the configuration files row of the gatewayguide summary table.

The default table replication definition file contains example commands. Youshould make a backup copy of the default file for future reference.



41/66

Note: You should use the REPLICATE command to replicate data from the primarytables ( alert.status , alert.journal , alert.details ) and dynamic secondary tables(if required).

You can add one or more optional clauses to the REPLICATE command to furtherprocess the data during replication. The available commands are listed in thefollowing syntax example. Use the optional clauses in the order in which they arelisted in the syntax. For example, when using both the

FILTER WITH and AFTER IDUC DO clauses, the FILTER WITH clause must precede theAFTER IDUC DO clause.REPLICATE ALL | (INSERTS, UPDATES, DELETES)FROM TABLE sourcetableUSING MAP mapname[FILTER WITH filter][INTO targettable][ORDER BY order, ... ][AFTER IDUC DO afteriduc] ;

Table 11. Optional replication commands

Command Description

FILTER WITH ’ filter ’ Filters the database rows selected for replication,where filter defines the filter that the gateway uses inthe WHERE clause of the SQL SELECT.

Filtering is positive by default, which means that onlythose events that match the filter definition arereplicated. You can use a negative filter by putting anexclamation mark (!) before the equals sign (=) in thefilter clause. For example, the following filter clausereplicates all events whose severity is not 5:

FILTER WITH ’Severity !=5’ORDER BY ’order ’ Order results by the SQL SELECT ORDER BY clause used

to get data. A potential use case might be to order byfirst occurrence, so that alerts are processed inchronological order, in which case the value specifiedfor order would be ’FirstOccurrence’ .

AFTER IDUC DO ’afteriduc ’ Updates replicated rows, where afteriduc specifieswhich field to update with what value. This uses theSQL UPDATE action to execute on rows retrieved by theSQL SELECT action used to get data, e.g. ' SentToCRM=1'.

Advanced propertiesAfter configuring the basic property settings required to run the gateway, youmight have to specify some advanced properties to suit your operatingenvironment.

This section describes the property settings for the following functions:v “Failback” on page 32v “Process Agent control” on page 32v “Authentication” on page 32v “Error handling” on page 32v “Creating service requests and incidents” on page 33v “Polling TSRM for unread tickets” on page 34



42/66

v “Passing data back to Netcool/OMINbus” on page 35v “Encryption” on page 35v “XML templates” on page 35

Failback The failback function comes into operation when the gateway has lost itsconnection to the primary ObjectServer and has failed over to the backupObjectServer. The backup ObjectServer is configured using the nco_xigen utility.

To enable failback, set the Gate.RdrWtr.FailbackEnabled property to TRUE. Whenthe reader has detected that it is now connected to a backup ObjectServer, it pollsfor the return of the primary ObjectServer with the frequency specified by theGate.RdrWtr.FailbackTimeout property. When the primary ObjectServer is detectedagain, the reader automatically fails back to the primary ObjectServer.

Process Agent controlThe gateway can be run under Process Agent (PA) control.

The Gate.PAAware property specifies whether or not the gateway is PA-aware. The

Gate.PAAwareName property specifies which PA is running the gateway.Note: These properties are maintained automatically by the PA server and provideinformation only. Do not manually change the values of these properties.

AuthenticationUse the Gate.UsePamAuth property to specify how the gateway authenticates users.

Either standard UNIX authentication or Pluggable Authentication Modules (PAM)authentication can be used with the Gateway for TSRM. By default, the gatewayuses standard UNIX authentication. To use PAM authentication, set theGate.UsePamAuth property to TRUE.

Note: To run the gateway in FIPS 140-2 mode, you must set the Gate.UsePamAuthproperty to TRUE.

Error handlingError reporting is provided by the Netcool/OMNIbus Gateway Toolkit (NGTK)library. To specify that the NGTK library logs debug messages, set theGate.NGtkDebug property to TRUE.

The debug files provide information about errors in the following areas:v mapper syntaxv ObjectServer communication failurev invalid column references in the mapperv attempts to update a field in the ObjectServer that does not existv TSRM communication failure

If there is a communication failure with TSRM, the gateway generates aGatewayWatch message. The gateway then retries the connection to TSRM with thefrequency specified by the Gate.TSRM.RetryInterval property. If the gateway failsto connect to TSRM after the number of times specified by theGate.TSRM.RetryInterval property, the gateway shuts down.

For communication problems with TSRM, the gateway sends a code back to theObjectServer to identify the error. The code is sent to the ObjectServer field



43/66

specified by the Gate.TSRM.ErrorCodeFieldname property. For example, if thegateway cannot send requests to TSRM due to a communication error, the gatewaysends error code 1 to the ObjectServer error code field. If there is an applicationerror, the gateway sends error code 2 to the ObjectServer error code field.

Creating service requests and incidentsWithin the TSRM object structure, entities such as tickets and work logs are treatedas separate objects and identified by name. Use the Gate.TSRM.TicketObjectNameproperty to specify the object structure name that TSRM uses for tickets and theGate.TSRM.WorkLogObjectName property to specify the object structure name forwork logs.

The gateway can support either TSRM incidents or TSRM service requests, but not both simultaneously. If you want to create both incidents and service requests, youmust run two instances of the gateway, one for each type of ticket.

To configure the gateway to support either TSRM incidents or TSRM servicerequests you must specify the required class in the $OMNIHOME/gates/tsrm/tsrm.mapfile. To support TSRM incidents set class to ' INCIDENT' or to support servicerequests set class to ' SR'. For example;CREATE MAPPING StatusMap(

’CLASS’ = ’SR’,’DESCRIPTION’ = ’@Node’ + ":" + ’@Summary’ ON INSERT ONLY,’REPORTEDBY’ = ’NETCOOL’ ON INSERT ONLY,’REPORTDATE’ = TO_TIME(’@FirstOccurrence’) ON INSERT ONLY,’REPORTEDPRIORITY’ = Lookup(’@Severity’,’SeverityTable’),’STATUS’ = Lookup(’@Severity’, ’StatusTable’),’TTNumber’ = ’@TTNumber’

);CREATE MAPPING JournalMap(

’CLASS’ = ’SR’,’Chrono’ = ’@Chrono’,’CREATEDATE’ = TO_TIME(’@Chrono’),’DESCRIPTION’ = ’NETCOOL JOURNAL ENTRY’,’DESCRIPTION_LONGDESCRIPTION’ = TO_STRING(’@Text1’) +

TO_STRING(’@Text2’) + TO_STRING(’@Text3’));

Note: Class is set to 'INCIDENT' by default.

If you want the gateway to create and maintain TSRM incidents, specify thefollowing property values:

Property Value

Gate.TSRM.URLList http:///meaweb/os/MXINCIDENTGate.TSRM.TicketObjectName MXINCIDENTGate.TSRM.TicketObjectType INCIDENT

If you want the gateway to create and maintain TSRM service requests, specify thefollowing property values:

Property Value

Gate.TSRM.URLList http:///meaweb/os/MXSRGate.TSRM.TicketObjectName MXSR



44/66

Property Value

Gate.TSRM.TicketObjectType SR

Polling TSRM for unread ticketsThe TSRM reader thread polls TSRM for all unread tickets and work log changes.This polling is based on a timestamp that the gateway maintains internally. Unreadincident changes are processed as ObjectServer status table changes.

Note: To prevent miscommunication of ticket details, the time zones for theObjectServer, the gateway, and the TSRM server must be synchronized at all times.

The unread ticket changes are processed by the tsrm.script file supplied with thegateway. By default, any changes made to the STATUS field in TSRM are transferred back to the corresponding field in the ObjectServer. You can transfer additionalfields back to the ObjectServer by using the Gate.TSRM.QueryRetrieveListproperty. For example, if you want to indicate whether a Service Level Agreement(SLA) has been applied to any of the tickets whose details are passed back to theObjectServer, set the Gate.TSRM.QueryRetrieveList property to SLAAPPLIED.

Note: You must also add any additional fields that you want to send back to theObjectServer to the XML structure for the service request or incident, theObjectServer, and the tsrm.sql file supplied with the gateway. For details of howto do this, see “Retrieving additional fields from TSRM” on page 38.

To improve the performance of the TSRM reader, each time an incident or a worklog object is created, the source attribute of the corresponding TSRM item ispopulated with the text NETCOOL. You can use this as a filter during polling. Youcan specify an alternative text to identify tickets created from Netcool/OMNIbususing the Gate.TSRM.SourceName property.

If the poller cannot communicate with the TSRM server, it generates the following

GatewayWatch message:

TSRM Gateway is unable to connect to the TSRM Server

Filtering repeated values

The ObjectServer may send updates to the gateway which have unchanged eventdata since the last polling. This can put excessive load on the TSRM server. Toinstruct the gateway to send only event data that has changed since the lastpolling, set the Gate.TSRM.FilterRepeatedValues property to true. This enables thegateway to filter messages based on the post mapped values.

To stop filtering on fields in which you are not interested in preventing repeatvalues, specify them using the Gate.TSRM.FilterExclusionList property. Thisproperty enables the gateway to stop filtering data which you do not need interms of ObjectServer updates. For example, Date and Time fields usually fall intothis category and you may need to know when the severity of an event haschanged and what date it occurred but you may not need all event reoccurrenceswith the same severity.

Removing reliance on the Maximo host clock The gateway for TSRM uses the CHANGEDATE value to determine new TSRMupdates sent by Maximo.



45/66

If the Gate.TSRM.PollTimeIntervalWindow property is set to a positive value, thegateway uses the following algorithm to query for updates on Maximo:

CHANGEDATE > (current time using the gateway host clock) -(Gate.TSRM.PollTimeIntervalWindow)

This removes the reliance on the Maximo host clock.

Note: The clocks on the gateway server and the Maximo server need to be insynch.

For best performance the Gate.TSRM.PollTimeIntervalWindow value should betwice the value of set for the Gate.TSRM.PollTime property.

Note: The polling for events on TSRM will still occur with the frequency specified by the Gate.TSRM.PollTime property.

Passing data back to Netcool/OMINbusTo enable the gateway to query and maintain TSRM tickets that originated inNetcool/OMNIbus, and to pass data back to Netcool/OMNIbus, you must specifywhich fields in the ObjectServer alerts.status table hold the correspondingdetails from TSRM.

You do this using the following properties:v Gate.TAL.TTNumberFieldName : this field is required to hold the trouble ticket

number.v Gate.TAL.TTStateFieldName : this field is required to hold the integer that

indicates the state of the trouble ticket.v Gate.TAL.TTJournalChronoFieldName : this field is required to prevent duplicates

during failback.

EncryptionYou can use encryption algorithms (for example, AES or DES) to secure the entriesmade in the properties file.

Use the ConfigCryptoAlg property to specify the encryption method and theConfigKeyFile property to specify the encryption key data file.

XML templatesThe gateway writes Netcool/OMINbus data to TSRM tickets by using predefinedXML templates.

The templates are supplied with the gateway as individual text files and arespecified using the following properties:v Gate.TSRM.CreateTicketTemplate

: the gateway uses this template to createtickets in TSRM.v Gate.TSRM.UpdateTicketTemplate : the gateway uses this template to update

TSRM ticket details.v Gate.TSRM.JournalTemplate : the gateway uses this template to create work logs

in TSRM.v Gate.TSRM.QueryTicketTemplate : the gateway uses this template to query ticket

details in TSRM.



46/66

Configuring SSL connectionsIf you are using an HTTPS/SSL connection between the gateway and TSRM, youmust create a truststore to store the TSRM digital certificate and point the gatewayto the location of the truststore.

You can generate the truststore file using the Java keytool utility. The keytoolutility is located in the following directory:

$OMNIHOME/platform/arch / jre_directory /jre/bin/

Where arch is the operating system you are running and jre_directory is theinstallation directory of your Java Runtime Environment (JRE).

Use the following steps to enable SSL connections between the gateway and TSRM:1. Obtain the TSRM certificate files.

Note: You must obtain the CA root certificate and any intermediate CAcertificates that your TSRM configuration uses.

2. Use the Java keytool utility to create a truststore and password.3. Add the TSRM SSL certificate to the truststore.

For example, run the following keytool command from the$NCHOME/platform/arch /jre_ version /bin directory to import the certificate andcreate the keystore:keytool -import -trustcacerts -alias CAROOTCERT -file PATH CA.cer-keystore $NCHOME/etc/security/tsrmcerts

Note: You will be prompted to create a truststore password.4. Update the Gate.TSRM.URLList property to include the HTTPS MEA location.

For example: https:// targethost /meaweb/os/MXINCIDENT

Note: The targethost variable must match the hostname specified in the TSRMserver certificate.

5. Update the Gate.Java.Arguments property to include the following arguments:v -Djavax.net.ssl.trustStore= truststore_path

Where truststore_path is the full path and name of the truststore file.v -Djavax.net.ssl.trustStorePassword= truststore_password

For example:Gate.Java.Arguments : '-Djavax.net.ssl.trustStore=/opt/IBM/tivoli/netcool/platform/ arch /jre_1.6.7/jre/lib/security/tsrmcerts-Djavax.net.ssl.trustStorePassword=changeit'

Configuring TSRMAfter installing the gateway, you must configure TSRM to run with the gateway.

The following sections explain how to configure TSRM to run with the gateway:v “Configuring TSRM to receive journal entries from Netcool/OMNIbus events”

on page 37v “Retrieving additional fields from TSRM” on page 38v “Configuring the TSRM event summary field” on page 39



47/66

Configuring TSRM to receive journal entries fromNetcool/OMNIbus events

Within TSRM, entities such as incidents and work logs are represented usingobjects. These objects also have XML representations. Before using the gateway,you must configure TSRM to support the passing of journal entry details fromNetcool/OMNIbus to TSRM. These entries then get created as work logs within

TSRM.

To configure TSRM to receive journal entries from Netcool/OMNIbus events, youmust add the structure for work logs to that of incidents and service requestswithin the TSRM object structure. You will be able to create journal entries onNetcool/OMNIbus events and use the Gateway for TSRM to pass those details totheir corresponding TSRM tickets as work logs.

To add the appropriate XML structure required to add work logs to the TSRMobject structure, use the following steps:

1. Start the TSRM Web application interface (Maximo).2. Select Go To > Integration > Object Structures .

3. In the filter field of the Object Structure column, enter MXINCIDENT andpress Enter .

4. Open the MXINCIDENT object structure.

Note: To add the work order object to the structure for service requestsinstead of incidents, search for, select, and open MXSR instead of MXINCIDENT. Integration Application is responsible for all Maximointerfaces with external applications. In this context, the external application isthe Gateway for TSRM.

5. Select the New Row button at the bottom of the Source Object panel.6. Select INCIDENT from the Object drop-down field.

Note: To add the work order object to the structure for service requests, selectSR .7. Add a second new row to the Source Object panel.8. Make the following selections for the second row:

a. From the Source Object drop-down field, select WORKLOG .b. From the Parent Object drop-down field, select INCIDENT .

Note: To add the work order object to the structure for service requests,select SR .

c. Select MODIFYWORKLOG from the Relationship drop-down field.9. Select Select Action > Exclude/Include Fields .

The interface displays the Exclude Include Fields dialog box.10. In the Source Objects list, select the WORKLOG object.11. Select the Non-Persistent Fields tab.12. Select the DESCRIPTION_LONGDESCRIPTION check box.13. Select OK to close the dialog box.14. Select Select Action > Generate Schema/View XML .15. Select OK to generate the XML schema required within the TSRM object

structure.Maximo displays the View XML dialog box.



48/66

16. Select OK to close the window.

Retrieving additional fields from TSRMBy default, the gateway only retrieves the STATUS field from TSRM tickets.

If you want to retrieve an additional field from TSRM to send back to

Netcool/OMNIbus, you must use the following steps:1. Add the field to the XML structure for the TSRM incident or service request.2. Add the field to the ObjectServer.3. Add the TSRM field to the list of fields retrieved by the gateway.

Adding fields to the XML structure for incidents and servicerequests

You can add any of the TSRM ticket fields to the details that are retrieved and sent back to Netcool/OMNIbus. For details of which fields are available for selection,see the Tivoli SRM Administration Guide.

The following example shows how to add the appropriate XML code for retrievingthe SLAAPPLIED field to the XML structure for a TSRM incident:1. Start Maximo.2. Select Go To > Integration > Object Structures .3. In the filter field of the Object Structure column, enter MXINCIDENT and

press Enter .4. Open the MXINCIDENT object structure.

Note: To add a TSRM field to service request details retrieved and sent backto Netcool/OMNIbus, search for, select, and open MXSR instead of MXINCIDENT.

5. Select the Object Structure tab.6. Select the Exclude/Include Fields action.

Maximo displays the Exclude/Include Fields dialog box.7. Select the Non-Persistent Fields tab.8. Select the Include check box beside the SLAAPPLIED entry.9. Click OK .

10. To confirm that the XML code for the SLAAPPLIED field has been addedcorrectly, select the Generate Schema/View XML action from the ObjectStructure panel.Maximo displays the View XML dialog box.

11. In the left-hand side of the panel, scroll through the XML and locate thefollowing XML (highlighted in Figure 12):false

12. Select OK to close the dialog box.

Adding a field to the ObjectServer

To add a field to the ObjectServer, run the following command using theObjectServer SQL tool:alter table alerts.status add column FieldName typ;go



49/66

where FieldName is the name of the field that you are ad

Tsrmgw PDF

Documents

Transcript of Tsrmgw PDF