Netcool/Impact: DSA Reference Guide

Netcool/Impact
Version 7.1.0.3
DSA Reference Guide
IBM
SC27-4919-02
Netcool/Impact
Version 7.1.0.3
DSA Reference Guide
IBM
SC27-4919-02
Note
Before using this information and the product it supports, read the information in “Notices”.
Edition notice
This edition applies to version 7.1.0.3 of IBM Tivoli Netcool/Impact and to all subsequent releases and
modifications until otherwise indicated in new editions.
References in content to IBM products, software, programs, services or associated technologies do not imply that
they will be available in all countries in which IBM operates. Content, including any plans contained in content,
may change at any time at IBM's sole discretion, based on market opportunities or other factors, and is not
intended to be a commitment to future content, including product or feature availability, in any way. Statements
regarding IBM's future direction or intent are subject to change or withdrawal without notice and represent goals
and objectives only. Please refer to the developerWorks terms of use for more information.
© Copyright IBM Corporation 2006, 2015.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this publication
|
. . . . . . ..
v
Intended audience . . . . . . . . . . ..
Publications . . . . . . . . . . . . ..
Netcool/Impact library . . . . . . . . ..
Accessing terminology online. . . . . . ..
Accessing publications online. . . . . . ..
Ordering publications . . . . . . . . ..
Accessibility . . . . . . . . . . . . ..
Tivoli technical training . . . . . . . . ..
Support for problem solving . . . . . . . ..
Obtaining fixes . . . . . . . . . . ..
Receiving weekly support updates . . . ..
Contacting IBM Software Support . . . . ..
Conventions used in this publication . . . . ..
Typeface conventions . . . . . . . . ..
PDF code examples with single quotation marks
Operating system-dependent variables and paths
v
v
v
v
v
vi
vi
vi
vi
vi
vii
vii
ix
ix
. x
x
Chapter 1. Managing DSAs . . . . ..
1
Chapter 2. Data source adapters (DSA)
3
Categories of DSAs . . . . . . . . . . ..
3
Mediator DSAs . . . . . . . . . . ..
3
Managing data models . . . . . . . . . ..
4
Event readers . . . . . . . . . . . . ..
4
Event listeners . . . . . . . . . . . . ..
4
Policies . . . . . . . . . . . . . . ..
5
Working with SQL database DSAs . . . . . ..
5
List of provided SQL database DSAs . . . ..
5
Adding JDBC drivers and third-party JAR files to
the shared library. . . . . . . . . . ..
7
Changing the character set encoding for the
database connection . . . . . . . . . ..
8
SQL database data model . . . . . . . ..
8
SQL database policies . . . . . . . . ..
9
SQL database DSA failover . . . . . . ..
13
Chapter 3. Working with the UI data
provider DSA . . . . . . . . . . ..
UI data provider data model . . . . . . ..
UI data provider data sources . . . . . ..
UI data provider data types . . . . . . ..
Viewing data items for a UI data provider data
type . . . . . . . . . . . . . . ..
Using the GetByFilter function to handle large
data sets . . . . . . . . . . . . ..
Retrieving data from a UI provider data source ..
Creating custom schema values for output
parameters . . . . . . . . . . . ..
Clearing the UI Data Provider server cache with the
UI data provider DSA . . . . . . . . . ..
UI data provider operators . . . . . . . ..
An example using the UI data provider to integrate
with IBM Tivoli Monitoring . . . . . . . ..
© Copyright IBM Corp. 2006, 2015
17
17
17
18
19
19
22
24
25
26
26
Configuring Netcool/Impact to send messages to
Tivoli Monitoring Universal Message Console ..
27
Chapter 4. Working with the LDAP DSA 29
LDAP DSA overview . . . . .
Supported LDAP servers . . . .
LDAP data model . . . . . .
LDAP data sources . . . . .
LDAP data types . . . . .
LDAP data items . . . . .
LDAP policies . . . . . . .
Retrieving data from an LDAP data
International character support . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
source .
. . .
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
Chapter 5. Working with the web
services DSA . . . . . . . . . . ..
Web services DSA overview . . . . . . . ..
Compiling WSDL files . . . . . . . . . ..
Obtaining WSDL files . . . . . . . . ..
Running the WSDL compiler script . . . ..
Recompiling new and changed WSDL files . ..
Enabling and disabling proxy settings using
WSInvokeDL . . . . . . . . . . . ..
Web services DSA functions . . . . . . . ..
WSSetDefaultPKGName . . . . . . . ..
WSNewObject . . . . . . . . . . ..
WSNewSubObject . . . . . . . . . ..
WSNewArray . . . . . . . . . . ..
WSInvokeDL . . . . . . . . . . . ..
WSNewEnum . . . . . . . . . . ..
Writing Web services DSA policies. . . . . ..
Sending messages . . . . . . . . . ..
Examples using web services DSA functions ..
Web services listener . . . . . . . . . ..
Web services listener process . . . . . ..
Writing applications that call into Web services ..
SOAP endpoint . . . . . . . . . . ..
Authentication for the web services listener ..
WSDL file . . . . . . . . . . . . ..
Creating policies by using the web services wizard
Creating policies by using policy editor . . . ..
Integrating with third-party web services . . ..
Chapter 6. Web services security . ..
Enabling web services security . . . . . . ..
Creating a web service policy using web service
security. . . . . . . . . . . . . ..
Example of Sample04_wss.xml . . . . . ..
User name token authentication . . . . . ..
User name token authentication with a plain text
password . . . . . . . . . . . . . ..
Message integrity and non-repudiation with
signature . . . . . . . . . . . . . ..
Encryption . . . . . . . . . . . . ..
Sign and encrypt messages . . . . . . . ..
29
29
29
29
30
30
31
31
32
33
33
33
34
34
35
35
36
36
37
37
38
39
42
43
43
44
46
46
51
51
52
52
55
56
57
59
59
60
63
64
65
65
66
66
iii
Chapter 7. Working with the JMS DSA
69
Supported JMS providers . . . . . . . . ..
Configuring JMS DSAs to send and receive JMS
messages . . . . . . . . . . . . . ..
Setting up OpenJMS as the JMS provider . . ..
JMS data source . . . . . . . . . . . ..
JMS data source configuration properties . ..
Specifying more JNDI properties for the JMS data
source . . . . . . . . . . . . . ..
JMS message listener . . . . . . . . . ..
JMS message listener service configuration
properties . . . . . . . . . . . . ..
Writing JMS DSA policies. . . . . . . . ..
Sending messages to a JMS topic or queue . ..
Retrieving JMS messages from a topic or queue
Connecting to WebSphere MQ and JMS DSA . ..
Configuration option 1 . . . . . . . ..
Configuration option 2 . . . . . . . ..
Connecting Netcool/Impact to WebSphere Business
Events . . . . . . . . . . . . . . ..
Configure Netcool/Impact for WebSphere
Business Events integration . . . . . . ..
Using the WebSphere Business Events integration
69
69
70
70
70
72
72
73
74
74
78
81
81
82
82
83
83
Chapter 8. Working with the XML DSA
85
XML DSA overview . . . . . . . . . ..
XML documents . . . . . . . . . . . ..
XML DTD and XSD files . . . . . . . . ..
XML data types . . . . . . . . . . . ..
Super data types . . . . . . . . . ..
Element data types . . . . . . . . . ..
XML configuration files . . . . . . . . ..
XML document and data type mapping . . . ..
Creating XML data types . . . . . . . . ..
Create data types scripts . . . . . . . . ..
Data type mappings . . . . . . . . . ..
Setting up mappings for XML files and strings
Setting up mappings for XML over HTTP . ..
Reading XML documents . . . . . . . . ..
Retrieving the document data item . . . ..
Retrieving the root level element data item . ..
Retrieving child element data items . . . ..
Accessing attribute values . . . . . . ..
Sample policies . . . . . . . . . . . ..
XmlStringTestPolicy . . . . . . . . ..
XmlFileTestPolicy . . . . . . . . . ..
XmlHttpTestPolicy . . . . . . . . . ..
XmlXsdFileTestPolicy . . . . . . . . ..
85
85
85
85
85
86
86
86
87
88
88
89
90
91
91
92
93
94
94
94
95
95
96
Chapter 9. Working with the SNMP DSA 97
SNMP DSA overview .
SNMP data model . .
iv
.
.
.
.
.
.
.
.
.
.
Netcool/Impact: DSA Reference Guide
.
.
.
.
.
.
..
..
97
97
SNMP data sources . . . . . . . . . ..
SNMP data types . . . . . . . . . ..
SNMP DSA process. . . . . . . . . . ..
Sending data to agents . . . . . . . ..
Retrieving data from agents . . . . . . ..
Sending traps and notifications to managers ..
Handling error conditions . . . . . . ..
Handling timeouts . . . . . . . . . ..
Installing MIB files . . . . . . . . . ..
Working with SNMP data sources . . . . ..
Creating SNMP data sources . . . . . ..
Editing SNMP data sources. . . . . . ..
Deleting an SNMP data source . . . . ..
Working with SNMP data types . . . . . ..
Creating SNMP data types . . . . . . ..
Editing SNMP data types . . . . . . ..
Deleting SNMP data types . . . . . . ..
SNMP policies . . . . . . . . . . . ..
Setting packed OID data with standard
data-handling functions . . . . . . . ..
Setting packed OID data with SNMP functions
Retrieving packed OID data from SNMP agents
Retrieving table data from SNMP agents . ..
Sending SNMP traps and notifications . . ..
SNMP functions . . . . . . . . . . ..
SNMPGetAction . . . . . . . . . ..
SNMPGetNextAction . . . . . . . . ..
SNMPSetAction . . . . . . . . . ..
SnmpTrapAction . . . . . . . . . ..
Chapter 10. Working with the ITNM
DSA . . . . . . . . . . . . . ..
Appendix. Notices . . . . . . . ..
.
.
.
.
.
.
.
.
.
.
.
Index . . . . . . . . . . . . . ..
105
108
108
111
112
113
113
117
121
124
127
ITNM DSA overview . . . . . . . . . ..
Setting up the DSA . . . . . . . . . ..
Editing the DSA properties file . . . . ..
Running the ITNM event listener service for the
DSA . . . . . . . . . . . . . ..
ITNM DSA data type . . . . . . . . . ..
ExtraInfo field . . . . . . . . . . ..
Writing policies using the ITNM DSA . . . ..
GetByFilter . . . . . . . . . . . ..
Writing policies to receive events from ITNM
Sample policies . . . . . . . . . . . ..
ITNMSampleListenerPolicy. . . . . . ..
ITNMSamplePolicy . . . . . . . . ..
Trademarks .
97
98
98
99
99
99
99
99
100
100
100
101
102
102
102
104
104
104
127
127
128
128
129
130
130
130
132
133
133
133
135
..
137
139
About this publication
The Netcool/Impact DSA Reference Guide contains information about Impact data
source adaptors (DSAs).
Intended audience
This publication is for users who are responsible for creating Netcool/Impact data
models and writing Netcool/Impact policies.
Publications
This section lists publications in the Netcool/Impact library and related
documents. The section also describes how to access Tivoli® publications online
and how to order Tivoli publications.
|
Netcool/Impact library
|
|
|
|
|
|
v Quick Start Guide, CN1LAML
Provides concise information about installing and running Netcool/Impact for
the first time.
v Administration Guide, SC27491802
Provides information about installing, running and monitoring the product.
v Policy Reference Guide, SC27492102
|
|
|
Contains complete description and reference information for the Impact Policy
Language (IPL).
v DSA Reference Guide, SC27491902
|
|
|
Provides information about data source adaptors (DSAs).
v Operator View Guide, SC27492002
Provides information about creating operator views.
|
|
v Solutions Guide, SC27492302
Provides end-to-end information about using features of Netcool/Impact.
Accessing terminology online
The IBM® Terminology Web site consolidates the terminology from IBM product
libraries in one convenient location. You can access the Terminology Web site at the
following Web address:
http://www.ibm.com/software/globalization/terminology
Accessing publications online
Publications are available from the following locations:
v The Quick Start DVD contains the Quick Start Guide. Refer to the readme file on
the DVD for instructions on how to access the documentation.
v IBM Knowledge Center web site at http://publib.boulder.ibm.com/infocenter/
tivihelp/v8r1/topic/com.ibm.netcoolimpact.doc6.1.1/welcome.html. IBM posts
publications for all Tivoli products, as they become available and whenever they
are updated to the Tivoli Information Center Web site.
© Copyright IBM Corp. 2006, 2015
v
Note: If you print PDF documents on paper other than letter-sized paper, set
the option in the File → Print window that allows Adobe Reader to print
letter-sized pages on your local paper.
v Tivoli Documentation Central at http://www.ibm.com/tivoli/documentation.
You can access publications of the previous and current versions of
Netcool/Impact from Tivoli Documentation Central.
v The Netcool/Impact wiki contains additional short documents and additional
information and is available at https://www.ibm.com/developerworks/
mydeveloperworks/wikis/home?lang=en#/wiki/Tivoli%20Netcool%20Impact.
Ordering publications
You can order many Tivoli publications online at http://
www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss.
You can also order by telephone by calling one of these numbers:
v In the United States: 800-879-2755
v In Canada: 800-426-4968
In other countries, contact your software account representative to order Tivoli
publications. To locate the telephone number of your local representative, perform
the following steps:
1. Go to http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss.
2. Select your country from the list and click Go.
3. Click About this site in the main panel to see an information page that
includes the telephone number of your local representative.
Accessibility
Accessibility features help users with a physical disability, such as restricted
mobility or limited vision, to use software products successfully. In this release, the
Netcool/Impact console does not meet all the accessibility requirements.
Tivoli technical training
For Tivoli technical training information, refer to the following IBM Tivoli
Education Web site at http://www.ibm.com/software/tivoli/education.
Support for problem solving
If you have a problem with your IBM software, you want to resolve it quickly. This
section describes the following options for obtaining support for IBM software
products:
v “Obtaining fixes”
v “Receiving weekly support updates” on page vii
v “Contacting IBM Software Support” on page vii
Obtaining fixes
A product fix might be available to resolve your problem. To determine which
fixes are available for your Tivoli software product, follow these steps:
1. Go to the IBM Software Support Web site at http://www.ibm.com/software/
support.
2. Navigate to the Downloads page.
vi
Netcool/Impact: DSA Reference Guide
3. Follow the instructions to locate the fix you want to download.
4. If there is no Download heading for your product, supply a search term, error
code, or APAR number in the search field.
For more information about the types of fixes that are available, see the IBM
Software Support Handbook at http://www14.software.ibm.com/webapp/set2/sas/
f/handbook/home.html.
Receiving weekly support updates
To receive weekly e-mail notifications about fixes and other software support news,
follow these steps:
1. Go to the IBM Software Support Web site at http://www.ibm.com/software/
support.
2. Click the My IBM in the toobar. Click My technical support.
3. If you have already registered for My technical support, sign in and skip to
the next step. If you have not registered, click register now. Complete the
registration form using your e-mail address as your IBM ID and click Submit.
4. The Edit profile tab is displayed.
5. In the first list under Products, select Software. In the second list, select a
product category (for example, Systems and Asset Management). In the third
list, select a product sub-category (for example, Application Performance &
Availability or Systems Performance). A list of applicable products is
displayed.
6. Select the products for which you want to receive updates.
7. Click Add products.
8. After selecting all products that are of interest to you, click Subscribe to email
on the Edit profile tab.
9. In the Documents list, select Software.
10.
11.
12.
13.
Select Please send these documents by weekly email.
Update your e-mail address as needed.
Select the types of documents you want to receive.
Click Update.
If you experience problems with the My technical support feature, you can obtain
help in one of the following ways:
Online
Send an e-mail message to erchelp@u.ibm.com, describing your problem.
By phone
Call 1-800-IBM-4You (1-800-426-4409).
World Wide Registration Help desk
For word wide support information check the details in the following link:
https://www.ibm.com/account/profile/us?page=reghelpdesk
Contacting IBM Software Support
Before contacting IBM Software Support, your company must have an active IBM
software maintenance contract, and you must be authorized to submit problems to
IBM. The type of software maintenance contract that you need depends on the
type of product you have:
About this publication
vii
v For IBM distributed software products (including, but not limited to, Tivoli,
Lotus®, and Rational® products, and DB2® and WebSphere® products that run on
Windows or UNIX operating systems), enroll in Passport Advantage® in one of
the following ways:
Online
Go to the Passport Advantage Web site at http://www-306.ibm.com/
software/howtobuy/passportadvantage/pao_customers.htm .
By phone
For the phone number to call in your country, go to the IBM Worldwide
IBM Registration Helpdesk Web site at https://www.ibm.com/account/
profile/us?page=reghelpdesk.
v For customers with Subscription and Support (S & S) contracts, go to the
Software Service Request Web site at https://techsupport.services.ibm.com/ssr/
login.
v For customers with IBMLink, CATIA, Linux, OS/390®, iSeries, pSeries, zSeries,
and other support agreements, go to the IBM Support Line Web site at
http://www.ibm.com/services/us/index.wss/so/its/a1000030/dt006.
v For IBM eServer™ software products (including, but not limited to, DB2 and
WebSphere products that run in zSeries, pSeries, and iSeries environments), you
can purchase a software maintenance agreement by working directly with an
IBM sales representative or an IBM Business Partner. For more information
about support for eServer software products, go to the IBM Technical Support
Advantage Web site at http://www.ibm.com/servers/eserver/techsupport.html.
If you are not sure what type of software maintenance contract you need, call
1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go to
the contacts page of the IBM Software Support Handbook on the Web at
http://www14.software.ibm.com/webapp/set2/sas/f/handbook/home.html and
click the name of your geographic region for phone numbers of people who
provide support for your location.
To contact IBM Software support, follow these steps:
1. “Determining the business impact”
2. “Describing problems and gathering information” on page ix
3. “Submitting problems” on page ix
Determining the business impact
When you report a problem to IBM, you are asked to supply a severity level. Use
the following criteria to understand and assess the business impact of the problem
that you are reporting:
Severity 1
The problem has a critical business impact. You are unable to use the
program, resulting in a critical impact on operations. This condition
requires an immediate solution.
Severity 2
The problem has a significant business impact. The program is usable, but
it is severely limited.
Severity 3
The problem has some business impact. The program is usable, but less
significant features (not critical to operations) are unavailable.
viii
Netcool/Impact: DSA Reference Guide
Severity 4
The problem has minimal business impact. The problem causes little impact
on operations, or a reasonable circumvention to the problem was
implemented.
Describing problems and gathering information
When describing a problem to IBM, be as specific as possible. Include all relevant
background information so that IBM Software Support specialists can help you
solve the problem efficiently. To save time, know the answers to these questions:
v Which software versions were you running when the problem occurred?
v Do you have logs, traces, and messages that are related to the problem
symptoms? IBM Software Support is likely to ask for this information.
v Can you re-create the problem? If so, what steps were performed to re-create the
problem?
v Did you make any changes to the system? For example, did you make changes
to the hardware, operating system, networking software, and so on.
v Are you currently using a workaround for the problem? If so, be prepared to
explain the workaround when you report the problem.
Submitting problems
You can submit your problem to IBM Software Support in one of two ways:
Online
Click Submit and track problems on the IBM Software Support site at
http://www.ibm.com/software/support/probsub.html. Type your
information into the appropriate problem submission form.
By phone
For the phone number to call in your country, go to the contacts page of
the IBM Software Support Handbook at http://www14.software.ibm.com/
webapp/set2/sas/f/handbook/home.html and click the name of your
geographic region.
If the problem you submit is for a software defect or for missing or inaccurate
documentation, IBM Software Support creates an Authorized Program Analysis
Report (APAR). The APAR describes the problem in detail. Whenever possible,
IBM Software Support provides a workaround that you can implement until the
APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the
Software Support Web site daily, so that other users who experience the same
problem can benefit from the same resolution.
Conventions used in this publication
This publication uses several conventions for special terms and actions, operating
system-dependent commands and paths, and margin graphics.
Typeface conventions
This publication uses the following typeface conventions:
Bold
v Lowercase commands and mixed case commands that are otherwise
difficult to distinguish from surrounding text
v Interface controls (check boxes, push buttons, radio buttons, spin
buttons, fields, folders, icons, list boxes, items inside list boxes,
About this publication
ix
multicolumn lists, containers, menu choices, menu names, tabs, property
sheets), labels (such as Tip:, and Operating system considerations:)
v Keywords and parameters in text
Italic
v Citations examples: titles of publications, diskettes, and CDs
v Words defined in text (example: a nonswitched line is called a
point-to-point line)
v Emphasis of words and letters (words as words example: "Use the word
that to introduce a restrictive clause."; letters as letters example: "The
LUN address must start with the letter L.")
v New terms in text (except in a definition list): a view is a frame in a
workspace that contains data.
v Variables and values you must provide: ... where myname represents....
Monospace
v Examples and code examples
v File names, programming keywords, and other elements that are difficult
to distinguish from surrounding text
v Message text and prompts addressed to the user
v Text that the user must type
v Values for arguments or command options
PDF code examples with single quotation marks
How to resolve issues with PDF code examples with single quotation marks.
Throughout the documentation, there are code examples that you can copy and
paste into the product. In instances where code or policy examples that contain
single quotation marks are copied from the PDF documentation the code examples
do not preserve the single quotation marks. You need to correct them manually. To
avoid this issue, copy and paste the code example content from the html version of
the documentation.
Operating system-dependent variables and paths
This publication uses the UNIX convention for specifying environment variables
and for directory notation.
When you use the Windows command line, replace the $variable with the
%variable% for environment variables and replace each forward slash (/) with a
backslash (\) in directory paths. The names of environment variables are not
always the same in the Windows and UNIX environments. For example, %TEMP%
in Windows environments is equivalent to $TMPDIR in UNIX environments.
Note: If you are using the bash shell on a Windows system, you can use the UNIX
conventions.
v On UNIX systems, the default installation directory is /opt/IBM/tivoli/impact.
v On Windows systems, the default installation directory is C:\Program
Files\IBM\Tivoli\impact.
Windows information, steps, and process are documented when they differ from
UNIX systems.
x
Netcool/Impact: DSA Reference Guide
Chapter 1. Managing DSAs
DSAs are software components that are used to communicate with external data
sources. DSAs broker information to and from SQL databases, LDAP servers, JMS
topics and queues, and software systems that allow communication through web
services APIs. You also use DSAs to parse XML strings and documents,
communicate with web servers through HTTP, and communicate with custom
applications through Java APIs.
© Copyright IBM Corp. 2006, 2015
1
2
Netcool/Impact: DSA Reference Guide
Chapter 2. Data source adapters (DSA)
Data source adapters (DSA) are software components that are used to
communicate with external data sources.
Categories of DSAs
There are the following categories of DSAs:
SQL database DSAs
SQL database DSAs are used to access information stored in SQL database
data sources. For more information about SQL database DSAs, see
“Working with SQL database DSAs” on page 5.
LDAP DSA
The LDAP DSA are used to access information stored in an LDAP server.
For more information about LDAP DSA, see Chapter 4, “Working with the
LDAP DSA,” on page 29.
Mediator DSAs
Mediator DSAs are used to communicate with various third-party
applications or generic data interfaces such as a Web services API, SNMP,
or custom interfaces. For more information about Mediator DSAs, see
“Mediator DSAs.”
Mediator DSAs
Mediator DSAs are used to communicate with various third-party applications or
generic data interfaces such as a Web services API or custom interfaces.
Some Mediator DSAs are built in DSAs and do not require any additional
installation or configuration. Other Mediator DSAs require you to manually install
and configure them.
Table 1 lists the provided built-in Mediator DSAs:
Table 1. Mediator DSAs
Mediator DSA
For more information, see
Web services DSA
Chapter 5, “Working with the web services DSA,” on page
33
JMS DSA
Chapter 7, “Working with the JMS DSA,” on page 69
XML DSA
Chapter 8, “Working with the XML DSA,” on page 85
SNMP DSA
Chapter 9, “Working with the SNMP DSA,” on page 97
ITNM DSA
Chapter 10, “Working with the ITNM DSA,” on page 127
The following Mediator DSAs are provided but you must install and configure
them independently of the application:
v Alcatel 5620 DSA
v GE Smallworld DSA
© Copyright IBM Corp. 2006, 2015
3
Managing data models
A data model is a model of the business data and metadata that is used in an
Netcool/Impact solution.
DSA (Data Source Adapter) data models are sets of data sources, data types, and
data items that represent information that is managed by the internal data
repository or an external source of data. For each category of DSA, the data model
represents different structures and units of data that are stored or managed by the
underlying source. For example, for SQL database DSAs, data sources represent
databases; data types represent database tables; and data items represent rows in a
database table.
The following DSAs; Web Services, SNMP, ITNM (Precision), and XML, store some
of the configuration in the $IMPACT_HOME/dsa directory. In a clustered environment,
the $IMPACT_HOME/dsa directory will be replicated in the secondary servers in a
cluster from the primary server during startup.
If you are changing these directories and configurations, it is best to make these
changes on the primary server while the servers are down. When the changes are
complete, start primary server followed by the secondary servers in the cluster.
Some of the changes replicate in real time, for example if you use the Web Services
and XML wizards. There is also a directory, $IMPACT_HOME/dsa/misc, where you can
store scripts and flat files for example, which will be replicated across the cluster
during startup of secondary servers that are retrieving this data from the primary
server.
Event readers
Event readers are services that query a data source at intervals for events and then
run a policy that is based on the incoming event data.
Two types of event readers are provided: standard event readers and database
event readers. Standard event readers query a Netcool/OMNIbus ObjectServer
database by using the ObjectServer DSA. Database event readers query other
relational databases by using other types of SQL database DSAs.
The default event reader configuration is sufficient when you process an event
flow of around 500 events per second. To enrich the event flow at any time, adjust
the following parameters in the event processor properties file.
impact.perftesteventreader.objectserver.maxtoreadperquery=2000
impact.perftesteventreader.objectserver.polltime=1500 (polling inteval 1500ms)
impact.perftesteventreader.maxqueuesize=4000
For more information about the event processor, see the Event processor commands
in the Administration Guide and Configuring the event processor service in the online
help.
Event listeners
Event listeners are services that listen for incoming communication from an
external data source through a DSA.
Event listeners are implemented by certain DSAs that provide the means for
asynchronous exchange of data with the underlying sources of data. These DSAs
include the database listener service for some SQL database DSAs (such as the
4
Netcool/Impact: DSA Reference Guide
Oracle DSA), OMNIbusEventListener for OMNIbus version 7.2 and later. They also
include other listeners for Web services, JMS, and ITNM.
Policies
DSA policies are policies that contain instructions for interacting with a data source
using a DSA. These policies contain calls to data-handling functions (such as
GetByFilter) or DSA-specific functions that are instructions to send or retrieve
information to and from the external data sources.
Working with SQL database DSAs
SQL database DSAs (data source adapters) are used to retrieve information from
relational databases.
SQL database DSAs are also used to retrieve information from other types of data
sources (like Netcool/OMNIbus ObjectServers, character-delimited files), and data
sources that provide a public interface through JDBC (Java™ Database
Connectivity). They are also used to add, modify, and delete information stored in
these data sources.
The SQL database DSAs are direct-mode DSAs that run in-process with the Impact
Server. SQL database DSAs are built in DSAs and do not require installation or
configuration, but they require a JDBC driver to access data in the database. Only
these SQL database DSAs have JDBC drivers provided automatically with
Netcool/Impact:
v DB2
v Derby
v Informix
v
v
v
v
HSQLDB
ObjectServer
Oracle
PostgreSQL
Before you can use any other SQL database DSA, you must add its JDBC drivers to
the class path. For a detailed procedure, see “Adding JDBC drivers and third-party
JAR files to the shared library” on page 7.
You use SQL database DSAs by creating a data model, and writing policies. For
more information, see “SQL database data model” on page 8, and “SQL database
policies” on page 9.
List of provided SQL database DSAs
This topic provides a list, and a brief overview of SQL database DSAs.
For a list of the databases that are supported and a list of the JDBC drivers that are
required or that come with Netcool/Impact see the System requirements page on
the Netcool/Impact wiki.
https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/
wiki/Tivoli%20Netcool%20Impact/page/Netcool%20%20Impact%207.1.%20system
%20requirements.
Chapter 2. Data source adapters (DSA)
5
For information about how to add or update JDBC drivers see “Adding JDBC
drivers and third-party JAR files to the shared library” on page 7.
DB2 DSA
This DSA is used to retrieve, add, modify and delete information stored in
DB2. It is also used to run DB2 database stored procedures.
Derby DSA
The Apache Derby database is used to store the underlying data that is
used by the GUI reporting tools and Netcool/Impact solutions such as
Maintenance Window Management.
The Apache Derby database is used to store other information that is used
by Netcool/Impact. For more information about Apache Derby, see this
URL, http://db.apache.org/derby/.
Flat File DSA
You use the Flat File DSA to read information in a character-delimited text
file.
You cannot use the Flat File DSA to write information to a text file. The
Flat File DSA supports only the "AND" operator in flat file data type
queries. You cannot use the "OR" operator to work with flat file data types.
The flat file data source can be accessed like an SQL data source that uses
standard SQL commands in Netcool/Impact for example, DirectSQL.
Use an SQL database to run more complex queries. If you have to use the
Flat File DSA, run multiple queries that do not require the use of the "OR"
operator.
Restriction: The Flat File DSA is intended for use in demonstrating and
testing Netcool/Impact and for infrequently accessing small amounts of
data that is stored in a text file. Use of text files and the Flat File DSA is
not an effective substitute for the use of a conventional relational database
and an SQL database DSA. The Flat File DSA offers slower performance
when compared to other DSAs.
Generic SQL DSA
This DSA is used to retrieve, add, modify and delete information stored in
the database. To use the Generic SQL DSA, you must specify its JDBC
driver in the Generic SQL data source configuration window.
HSQLDB DSA
You use the HSQL DSA to retrieve, add, modify and delete information
stored in a HSQL database.
Informix® DSA
This DSA is used to retrieve, add, modify and delete information stored in
an Informix database.
MySQL DSA
This DSA is used to retrieve, add, modify, and delete information stored in
a MySQL database.
MS-SQL Server DSA
This DSA is used to retrieve, add, modify, and delete information stored in
a MS_SQL database. It is used to run MS-SQL Server stored procedures.
6
Netcool/Impact: DSA Reference Guide
ObjectServer DSA
You use the ObjectServer DSA to access information in the
Netcool/OMNIbus ObjectServer.
ODBC DSA
Use the ODBC DSA to access information in an ODBC database.
Oracle DSA
The Oracle DSA is used to retrieve, add, modify, and delete information
that is stored an Oracle database. It is also used to run Oracle database
stored procedures.
PostgreSQL DSA
Netcool/Impact uses this DSA to retrieve, add, modify, and delete
information stored in a PostgreSQL database.
Sybase DSA
This DSA is used to retrieve, add, modify, and delete information stored in
a Sybase database. It is also used to run Sybase stored procedures.
Adding JDBC drivers and third-party JAR files to the shared
library
Use this procedure to add a JDBC driver or third-party Java archive (JAR) files to
the Netcool/Impact shared library.
About this task
v For a list of the JDBC drivers that are installed with Netcool/Impact see the
SPCR Prerequisites report for this release, see:https://www.ibm.com/
developerworks/community/wikis/home?lang=en#!/wiki/Tivoli%20Netcool
%20Impact/page/Overview%20and%20Planning.
v You must copy the required JDBC drivers to the $NCHOME/dsalib directory.
v If you have an existing licensed version of a JDBC driver you can add it to the
$NCHOME/dsalib directory and restart the Impact Server. Netcool/Impact uses
that driver to establish connection to the target database.
If you need any additional third-party .jar files for example, some JDBC drivers,
you must download them from your vendor. You can also copy any third-party
JAR files that you require to the same directory. For example, if you have
specific Java classes that you want use with Java policy functions in
Netcool/Impact, you add the JAR files to this directory.
Procedure
1. Obtain the appropriate JDBC driver according to the DSA specification or the
third-party JAR files.
2. Copy the JDBC driver or third-party JAR files to the $NCHOME/dsalib directory.
This directory is created during the installation, and might contain files.
3. Restart the Impact Server.
What to do next
In a clustered configuration, you must repeat this procedure for each server in the
cluster because files in the $NCHOME/dsalib directory are not replicated between
cluster members. Stop all the servers in the cluster while you perform this
procedure.
Chapter 2. Data source adapters (DSA)
7
Changing the character set encoding for the database
connection
Use this procedure to change the default character set encoding (UTF-8) that is
used in establishing a connection to the SQL database.
Procedure
1. In the $NCHOME/etc directory, create a properties file for the DSA for which you
want to change the default character set encoding.
The properties filename must have the following format:
servername_drivermainclass.props
where servername is the name of your Impact Server, and drivermainclass is the
class name of the JDBC driver to connect to the SQL database.
For example, you will create the NCI_org.gjt.mm.mysql.Driver.props file, if the
name of your Impact Server is NCI, and if it is connecting to the MySQL
database.
Remember: You can get the drivermainclass values for other SQL databases,
from their JDBC documenation.
2. Add a CHARSET=encoding property to the properties file.
For example, CHARSET=EUC_JP.
3. Restart the Impact Server.
SQL database data model
An SQL database data model is an abstract representation of data stored in an
underlying relational database or other data source that can be accessed through
JDBC.
SQL database data models consist of SQL database data sources, SQL database
data types, and SQL database data items.
SQL database data sources
An SQL database data source represents a relational database or another source of
data that can be accessed using an SQL database DSA.
A wide variety of commercial relational databases are supported, such as Oracle,
Sybase, and Microsoft SQL Server. In addition, freely available databases like
MySQL, and PostgreSQL are also supported. The Netcool/OMNIbus ObjectServer
is also supported as a SQL data source.
The configuration properties for the data source specify connection information for
the underlying source of data. Some examples of SQL database data sources are:
v A DB2 database
v A MySQL database
v An application that provides a generic ODBC interface
v A character-delimited text file
You create SQL database data sources using the GUI. You must create one such
data source for each database that you want to access. When you create an SQL
database data source, you need to specify such properties as the host name and
port where the database server is running, and the name of the database. For the
flat file DSA and other SQL database DSAs that do not connect to a database
server, you must specify additional configuration properties.
8
Netcool/Impact: DSA Reference Guide
Note that SQL database data sources are associated with databases rather than
database servers. For example, an Oracle database server can host one or a dozen
individual databases. Each SQL database data source can be associated with one
and only one database.
SQL database data types
An SQL database data type represents a table in a relational database or a similar
structure that contains sets of data (like an Oracle view or a list of rows in a
comma-delimited text file).
The configuration properties for the data type specify the structure and contents of
data stored in the table. Some examples of SQL database data types are:
v A DB2 database table
v A MySQL database table
v The contents of a character-delimited text file
Each SQL database data type contains a set of fields that correspond to columns in
the database table (or structured categories of data in other types of data sources).
The data type can contain fields that represent all of the columns or a subset of the
columns in the table.
You create SQL database data types using the GUI. You must create one such data
type for each database table that you want to access.
When you create an SQL database data type, you need to specify such properties
as the table name and the names of the table columns that you want to include in
the data type. For the flat file DSA, you must specify additional configuration
properties.
SQL database data items
An SQL database data item represents a table row in a relational database or
another set of data (like a row in a comma-delimited text file).
You use the GUI to view, add, modify, and delete SQL database data items.
Typically, however, you use the tools that are provided by the relational database
server (or other third-party tools) to manage the data in an underlying data source.
SQL database policies
SQL database DSA policies work with data stored in underlying relational
databases or other data sources that can be accessed using an SQL database DSA.
You can perform the following tasks by using a SQL database policy:
v Retrieve data from an SQL database data source
v Add data to an SQL database data source
v Modify data stored in an SQL database data source
v Delete data stored in an SQL database data source
v Call database functions
v Call database stored procedures
Retrieving data from an SQL database data source
The Impact Policy Language (IPL) provides a set of functions that retrieve data
from an SQL database data source based on different criteria.
Chapter 2. Data source adapters (DSA)
9
These functions allow you to retrieve data by key, by filter, and by link, and by
directly running SQL SELECT queries against the underlying database or other
source of data. The following table shows the IPL functions that retrieve SQL
database data.
Table 2. IPL Functions that Retrieve SQL Database Data
Function
Description
GetByKey
Retrieves data items (rows in a table or other data element) whose key
fields match the specified key expression.
GetByFilter
Retrieves data items whose field values match the specified SQL filter
string.
GetByLinks
Retrieves data items that are dynamically or statically linked to
another data item using the GUI.
DirectSQL
Retrieves data items by directly running an SQL SELECT query against
the underlying database or other source of data.
For detailed syntax descriptions of these functions, see the Policy Reference Guide.
The following example shows how to use GetByKey to retrieve data items (rows in
a table or other data element) whose key field matches the specified key
expression. In this example, the SQL database data type associated with the table is
Customer and the key expression is 12345.
DataType = "Customer";
Key = 12345;
MaxNum = 1;
MyCustomer = GetByKey(DataType, Key, MaxNum);
The following example shows how to use GetByFilter to retrieve data items whose
field values match the specified SQL filter string. In this example, the SQL database
data type is Node and the filter string is Location = ’New York City’ AND Facility
= ’Manhattan’.
DataType = "Node";
Filter = "Location = ’New York City’ AND Facility = ’Manhattan’";
CountOnly = False;
MyNodes = GetByKey(DataType, Key, MaxNum);
The following example shows how to use GetByLinks to retrieve data items that
have been statically or dynamically linked to another data item using the
Netcool/Impact GUI. In this example, you use GetByLinks to retrieve data items
that are linked to the items of type Node returned in the previous example.
DataType = {"Customer"};
Filter = "";
MaxNum = 1000;
DataItems = MyNodes;
MyCustomers = GetByLinks(DataType, Filter, MaxNum, MyNodes);
Adding data to an SQL database data source
You can use the AddDataItem function to add data to an SQL database data
source.
The following example shows how to use AddDataItem to add a row to an SQL
database table that is represented by the User data type. In this example, Name,
Location, Facility, andEmail are columns in the database table.
10
Netcool/Impact: DSA Reference Guide
DataType = "User";
MyUser = NewObject();
MyUser.Name = "John Smith";
MyUser.Location = "New York City";
MyUser.Facility = "Manhattan";
MyUser.Email = "jsmith@example.com";
AddDataItem(DataType, MyUser);
For a detailed syntax description of this function, see the Policy Reference Guide.
Modifying data stored in an SQL database data source
You can use the BatchUpdate function to modify the data that is stored on the SQL
database. You can also assign values to variables for data items that were
previously retrieved by using the GetByKey, GetByFilter, or GetByLinks to modify
data stored in an SQL database.
The following example shows how to modify a row in an SQL database table by
assigning values to member variables of a data item that was previously retrieved
by using the GetByFilter function. In this example, the Customer data type
represents a table in the underlying database and the Name, Location, and Facility
fields represent columns in the table.
DataType = "Customer";
Filter = "Name = ’John Smith’";
CountOnly = "False";
MyCustomer = GetByFilter(DataType, Filter, CountOnly);
MyCustomer[0].Location = "Raleigh";
MyCustomer[0].Facility = "FAC_01";
The following example shows how to modify multiple rows in an SQL database
table by using the BatchUpdate function. In this example, you update the Location
and Facility columns in the table for each row where the value of Location is
New York City.
DataType = "Customer";
Filter = "Location = ’New York City’";
UpdateExpression = "Location = ’Raleigh’ AND Facility = ’FAC_01’";
BatchUpdate(DataType, Filter, UpdateExpression);
For more information about using these methods to modify SQL database data, see
the Policy Reference Guide.
Deleting data stored in an SQL database data source
You can use policies to delete data that is stored in an SQL database data source by
using the DeleteDataItem, or BatchDelete functions.
With these functions, you can delete either a single row or data element, or
multiple rows. The following table shows the IPL functions that delete SQL
database data.
Table 3. IPL Functions that Delete SQL Database Data
Function
Description
DeleteDataItem
Deletes a single data item which is a row in a table or other data
element.
Chapter 2. Data source adapters (DSA)
11
Table 3. IPL Functions that Delete SQL Database Data
(continued)
Function
Description
BatchDelete
Deletes one or more data items whose field values match the
specified SQL filter string.
The following example shows how to delete a row in a database table by using the
DeleteDataItem function. In this example, you first retrieve the data item that
represents the row by using the GetByKey function and then call DeleteDataItem.
DataType = "Node";
Key = "DB2_01";
MaxNum = 1;
MyNode = GetByKey(DataType, Key, MaxNum);
DeleteDataItem(MyNode[0]);
The following example shows how to delete multiple rows from a database table
by using the BatchDelete function. In this example, you delete all rows from the
table that is represented by the User data type, where the value of the Location
column is New York City.
DataType = "User";
Filter = "Location = ’New York City’";
BatchDelete(DataType, Filter, NULL);
For more information about using these functions to delete SQL database data, see
the Policy Reference Guide.
Calling database functions
You can use the CallDBFunction to call any SQL function that is defined by the
database server.
SQL functions vary per database. For a list of functions that are supported by a
specific database server, see the documentation provided by the software vendor.
The following example shows how to call a database function named NOW() and
return the results of the function for use in a policy.
// Call CallDBFunction and pass the name of a data type, a filter
// string and the function expression
DataType = "Server";
Filter = "0 = 0";
Metric = "NOW()";
DBTime = CallDBFunction(DataType, Filter, Metric);
For a detailed syntax description of the CallDBFunction function, see the Policy
Reference Guide.
Calling database stored procedures
You can use the CallStoredProcedure function to call Oracle, Sybase, DB2, and SQL
Server database stored procedures.
The following example shows how to call a Sybase stored procedure named
GetCustomerByLocation. In this example, the Sybase database is represented by the
data source SYB_03.
12
Netcool/Impact: DSA Reference Guide
Sp_Parameter = NewObject();
Sp_Parameter.CustType = "Platinum";
Sp_Parameter.Location = "Mumbai";
DataSource = "SYB_03";
ProcName = "GetCustomerByLocation";
MyResults = CallStoredProcedure(DataSource, ProcName, Sp_Parameter);
For a detailed syntax description of the CallStoredProcedure function, see the
Policy Reference Guide.
SQL database DSA failover
Failover is the process by which an SQL database DSA automatically connects to a
secondary database server (or other data source) when the primary server becomes
unavailable.
This feature ensures that Netcool/Impact can continue operations despite problems
accessing one or the other server instance. You can configure failover separately for
each data source that connects to a database using an SQL Database DSA.
SQL database DSA failover modes
Standard failover, failback, and disabled failover are supported failover modes for
SQL database DSAs.
Standard failover
Standard failover is a configuration in which an SQL database DSA
switches to a secondary database server when the primary server becomes
unavailable and then continues using the secondary until Netcool/Impact
is restarted.
Failback
Failback is a configuration in which an SQL database DSA switches to a
secondary database server when the primary server becomes unavailable
and then tries to reconnect to the primary at intervals to determine
whether it has returned to availability.
Disabled failover
If failover is disabled for an SQL database DSA the DSA reports an error to
Netcool/Impact when the database server is unavailable and does not
attempt to connect to a secondary server.
Standard failover:
Standard failover is a configuration in which an SQL database DSA switches to a
secondary database server when the primary server becomes unavailable and then
continues using the secondary until Netcool/Impact is restarted.
If the secondary server becomes unavailable, the SQL database DSA will attempt to
resume connections to the original primary server.
Failback:
Failback is a configuration in which an SQL database DSA switches to a secondary
database server when the primary server becomes unavailable and then tries to
reconnect to the primary at intervals to determine whether it has returned to
availability.
Chapter 2. Data source adapters (DSA)
13
If the primary server has become available, the DSA will resume connections using
that server. If the primary has not become available, the DSA will continue to use
the secondary server. In a failback configuration, the SQL database DSA will
always attempt to reconnect to the primary server before making a connection to
the secondary.
Setting up DSA failover
You set up failover when you create and configure an SQL database data source in
the GUI.
Procedure
You use the data source editor to select a failover configuration for the data source
and to specify connection information for the primary and secondary database
servers. For more information about creating and configuring SQL database data
sources, see the online help.
DSA failover defaults
An SQL database DSA determines that a database server is unavailable when it
cannot connect to the database server, or when the database server returns an error
message that is not related to SQL or stored procedure syntax.
Netcool/Impact provides a built-in list of errors messages that indicate that a
database server has received an incorrectly formed SQL or stored procedure query.
SQL database DSAs exclude these errors when determining whether a database
server is unavailable. This means that, by default, a DSA does not failover or fail
back when a syntax error occurs at the database level.
The following shows the built-in list of errors that Netcool/Impact excludes.
Table 4. SQL Database Error Messages for Failover
Database
Error Codes
DB2
No default error codes
Derby
No default error codes
GenericSQL
No default error codes
HSQLDB
No default error codes
Informix
Error codes from -899 to -200 inclusive
MySQL
Error codes 1047, 1048, 1051, 1052, 1054 to 1064 inclusive,
1071, 1106 to 1111 inclusive, 1122, 1138, 1146, 1217, 1222
ObjectServer
Error codes 667, 5555, 20000, 20001, 20002
ODBC
No default error codes
Oracle
Error codes 100, 900 to 999 inclusive, 17006
PostgreSQL
SQL states 03000, 42000, 42601, 42602, 42622, 42701, 42702,
42703, 42704, 42803, 42804, 42809, 42883, 42939, 42P01,
42P02, 42P10, 42P18
SQL Server
Error codes 105, 207, 208, 213, 229, 230, 260
Sybase
Error codes 100 to 300 inclusive, 403, 404, 407, 413
For instructions in providing an alternate customized list, see “Customizing DSA
failover” on page 15.
14
Netcool/Impact: DSA Reference Guide
Customizing DSA failover
You can provide an alternate list of error codes that the SQL database DSAs
exclude when determining whether a database server is unavailable.
You store this list in a file named $NCHOME/etc/NCI_non_failover_errors.props,
where NCI is the name of the Impact Server instance. This file is not automatically
created so you must manually create and edit this file using a text editor.
Properties in this file have the following format:
impact.database=error_codes
where database is the name of the database and error_codes is a comma-separated
list of error identification numbers. To specify a range of codes, place a less-than
character between the lower limit and upper limit numbers as follows: 200<300.
The error code range is inclusive of the numbers specified.
The following table shows the internal database names that you must use in the
properties file.
Table 5. Database Internal Names
Database
Internal Name
DB2
db2
Derby
derby
GenericSQL
genericsql
HSQL
hsqldb
Informix
informix
MS SQL Server
mssql
MySQL
mysql
Netcool/OMNIbus
ObjectServer
objectserver
ODBC
odbc
Oracle
oracle
PostgreSQL
postgresql
Sybase
sybase
Error codes are defined by at the database level. For a list of possible error codes,
see the documentation provided with the database application.
The following example shows a properties file that lists the default built-in error
codes excluded by Netcool/Impact when determining if a database server is
unavailable.
impact.db2=
impact.informix=-899<-200
impact.mssql=105,207,208,213,229,230,260
impact.mysql=1047,1048,1051,1052,1054<1064,1071,1106<1111,1122,1138,1146,
1217,1222
impact.objectserver=667,5555,20000,20001,20002
impact.odbc=
impact.oracle=100,900<999,17006
impact.postgresql=03000,42000,42601,42602,42622,42701,42702,42703,42704,
42803,42804,
42809,42883,42939,42P01,42P02,42P10,42P18
impact.sybase=100<300,403,404,407,413
Chapter 2. Data source adapters (DSA)
15
Customizing ObjectServer DSA failback
When you create a new data source during the ObjectServer data source
configuration, the failback mode is selected by default. Extra optional
customization is available for ObjectServer DSA to enhance its failback mechanism
and to support failback for JDBC connections to ObjectServer DSAs.
Before you begin
The following information applies when you want to enable customized failback
by setting the property to be true.
v Netcool/OMNIbus ObjectServer v7.3 or later must be installed. The ObjectServer
must support the new gateway mechanism to handle failback. Refer to the
ObjectServer documentation http://publib.boulder.ibm.com/infocenter/tivihelp/
v8r1/index.jsp?topic=%2Fcom.ibm.tivoli.namomnibus.doc%2Fwelcome_ob.htm
v The Netcool/OMNIbus ObjectServer v7.3 and later use the value in the backup
ObjectServer to determine the primary ObjectServer and to update the
catalog.properties table with a property of PropName=’ActingPrimary’.
Procedure
v To enable customized failback, in the $IMPACT_HOME/etc/
<ServerName>_server.props file, change the value for
impact.objectserver.failback.enabled from false to true.
impact.objectserver.failback.enabled=true
Important: If you are running a cluster setup repeat this step for each server in
the cluster. You must also restart the server to implement these changes. By
default this property is disabled and the failback setup uses a ping mechanism
like other SQL DSAs.
v If the connection to the primary server and port hangs, you can change the
value for the timeout, which by default is 20 seconds.
– In the $IMPACT_HOME/etc/<ServerName>_server.props file, add the following
property impact.datasource.failback.tester.timeout=<# of milli seconds>.
For example, if you want to change the timeout to 1 minute, set the value of
the property to 60000 impact.datasource.failback.tester.timeout=60000
v Change the polling time, which checks whether the primary server is up. By
default, the polling time is 1 minute.
– In the $IMPACT_HOME/etc/<ServerName>_server.props file, add the following
propertyimpact.objectserver.failback.pollinterval=<# of milli seconds>.
For example, if you want to change the polling time to 10 seconds, set the
value of the property to 10000
impact.objectserver.failback.pollinterval=10000
v Determine which server is acting as the primary.
– Go to the backup ObjectServer server.
– Run the following query: SELECT Value from catalog.properties WHERE
PropName = 'ActingPrimary';
– If the value for PropName=’ActingPrimary’ is FALSE, then the primary server is
in active.
– If the value for PropName=’ActingPrimary’ is TRUE, then the backup is acting
as the primary server. This situation can occur when the ObjectServer
gateway is doing a resync with the primary server and the primary server is
not available to accept any connections.
16
Netcool/Impact: DSA Reference Guide
Chapter 3. Working with the UI data provider DSA
The UI data provider DSA is used to return results from any UI data provider
To set up a UI data provider DSA complete the following steps:
v Create a UI data provider data source
v Create a UI data provider data type
v Create a policy that uses the GetByFilter function
v Run the policy to return the results from the selected UI data provider
UI data provider data model
A UI data provider data model is an abstract representation of data stored in an
underlying relational database or other data source that can be accessed through a
UI data provider.
The UI data provider data model has the following elements:
v UI data provider data sources
v UI data provider data types
UI data provider data sources
A UI data provider data source represents a relational database or another source
of data that can be accessed by using a UI data provider DSA.
You create UI data provider data sources in the GUI. You must create one such
data source for each UI data provider that you want to access.
Creating a UI data provider data source
Use this information to create a UI data provider data source.
Procedure
1. Click Data Model to open the Data Model tab.
2. From the Cluster and Project lists, select the cluster and project you want to
use.
3. In the Data Model tab, click the New Data Source icon in the toolbar. Select
UI Data Provider. The tab for the data source opens.
4. In the Data Source Name field:
Enter a unique name to identify the data source. You can use only letters,
numbers, and the underscore character in the data source name. If you use
UTF-8 characters, make sure that the locale on the Impact Server where the
data source is saved is set to the UTF-8 character encoding.
5. In the Host Name field, add the location where the UI data provider is
deployed. The location is a fully qualified domain name or IP address.
6. In the Port field, add the port number of the UI data provider.
7. Use SSL: To enable Netcool/Impact to connect over SSL to a data provider,
you must export a certificate from the data provider and import it into the
Impact Servers and each GUI Server. If the data provider is an IBM
Dashboard Application Services Hub server, complete these steps to export
© Copyright IBM Corp. 2006, 2015
17
and import the certificate. For other data provider sources, after you obtain
the certificate, use steps (f and g) to import the certificate.
a. In the IBM Dashboard Application Services Hub server, go to Settings,
WebSphere Adminstrative Console, Launch WebSphere administrative
console.
b. Within the administrative console, select Security, SSL certificate and key
management, Key stores and certificates, NodeDefaultKeyStore, Personal
certificates.
c. Check the default certificate check box and click Extract.
d. Enter dash, for the certificate alias to extract.
e. For certificate file name, enter a file name on the system to which the
certificate is written to, such as C:\TEMP\mycertificate.cert.
f. Copy the certificate file to the Impact Server host and import it into both
the Impact Servers and GUI Servers. For more information about the
import commands, refer to the Netcool/Impact Administration Guide,
within the security chapter go to the 'Enabling SSL connections with
external servers' topic.
g. Restart the Impact Servers and eachGUI Server.
For more information, see the Netcool/Impact Administration Guide under the
section Secure Communication.
If you want to connect to the local UI data provider by using the UI data
provider data source with an SSL enabled connection, the signed certificate
must be exchanged between the GUI Server and Impact Server. For more
information see Configuring SSL with scripts in the Security section of the
documentation.
8. Base Url: Type the directory location of the rest application, such as,
/ibm/tivoli/rest.
9. User Name: Type a user name with which you can access the UI data
provider.
10. Password: Type a password with which you can access the UI data provider.
11. Click Test Connection to test the connection to the UI data provider to ensure
that you entered the correct information. Success or failure is reported in a
message box. If the UI data provider is not available when you create the data
source, you can test it later.
To test the connection to the UI data provider at any time, from the data
source list, right-click the data source and select Test Connection from the list
of options.
12. Click Discover Providers to populate the Select a Provider list.
13. From the Select a Provider list, select the provider that you want to return the
information from.
14. From the Select a Source list, select the data content set that you want to
return information from. The Select Source list is populated with the available
UI data provider data content sets on the specified computer.
15. Click Save to create the data source.
UI data provider data types
A UI data provider data type represents a structure similar to a table that contains
sets of data in a relational database. Each UI data provider database data type
contains a set of fields that correspond to data sources in the UI data provider. You
create UI data provider data types in the GUI. You must create one such data type
for each data set that you want to access.
18
Netcool/Impact: DSA Reference Guide
The configuration properties for the data type specify which subset of data is
retrieved from the UI data provider data source.
Creating a UI data provider data type
Use this information to create a UI data provider data type.
Procedure
1. Right click the UI data provider data source you created, and select New Data
Type.
2. In the Data Type Name field, type the name of the data type.
3. The Enabled check box is selected to activate the data type so that it is
available for use in policies.
4. The Data Source Name field is prepopulated with the data source.
5. From the Select a Dataset list, select the data set you want to return the
information from. The data sets are based on the provider and the data sets
that you selected when you created the data source. If this list is empty, then
check the data source configuration.
6. Click Save. The data type shows in the list menu.
Viewing data items for a UI data provider data type
You can view and filter data items that are part of a UI provider data type.
Procedure
1. In the Data Model tab, right click the data type and select View Data Items. If
items are available for the data type, they show on the right side in tabular
format.
2. If the list of returned items is longer than the UI window, the list is split over
several pages. To go from page to page, click the page number at the bottom.
3. To view the latest available items for the data type, click the Refresh icon on
the data type.
4. You can limit the number of data items that display by entering a search string
in the Filter field. For example, add the following syntax to the Filter field,
totalMemory=256. Click Refresh on the data items menu to show the filtered
results.
Tip: If your UI Data Provider data type is based on a Netcool/Impact policy,
you can add &executePolicy=true to the Filter field to run the policy and
return the most up to date filtered results for the data set.
For more information about using the Filter field and GetByFilter function
runtime parameters to limit the number of data items that are returned, see
“Using the GetByFilter function to handle large data sets.”
Using the GetByFilter function to handle large data sets
You can extend the GetByFilter function to support large data sets. To fetch items
from a UI data provider with the GetByFilter, additional input parameters can be
added to the filter value of the GetByFilter function. Additional filter parameters
allow you to refine the result set returned to the policy.
The UI data provider REST API supports the following runtime parameters:
v count: limits the size of the returned data items.
v start: specifies the pointer to begin retrieving data items.
Chapter 3. Working with the UI data provider DSA
19
v param_*: sends custom parameters to data sets that the UI data provider uses
during construction and data presentation. The UI Data Provider server
recognizes any additional parameters and handles the request if the parameter
has the prefix param_. These values are also used to uniquely identify a data set
instance in the REST service cache.
v id: If used, it fetches a single item. The id parameter specifies the id of item you
want to retrieve. For example, &id=1. If the id parameter is used, all other
filtering parameters are ignored.
Tip: If your UI Data Provider data type is based on a policy, then you can add
executePolicy=true to the FILTER parameter in GetByFilter( Filter, DataType,
CountOnly) to run the policy and ensure the latest data set results are returned by
the provider.
This policy example uses the FILTER runtime parameters in a GetByFilter
(Filter, DataType, CountOnly) implementation in a UI data provider.
DataType="123UIdataprovider";
CountOnly = false;
Filter = "t_DisplayName =’Windows Services’";
Filter = "t_DisplayName starts ’Wind’";
Filter = "t_DisplayName ends ’ces’";
Filter = "t_DisplayName contains 'W'&count=6&param_One=paramOne";
Filter = "t_DisplayName contains ’W’&count=3&start=2";
Filter = "((t_DisplayName contains ’Wi’)
or (t_InstanceName !isnull))";
Filter = "((t_DisplayName contains ’Wi’)
or (t_InstanceName=’NewService’))&count=3";
Filter = "((t_DisplayName contains ’Wi’)
or (t_InstanceName=’NewService’))&count=5&start=1";
MyFilteredItems = GetByFilter( DataType, Filter, CountOnly );
Log( "RESULTS: GetByFilter(DataType="+DataType+", Filter="+Filter+",
CountOnly="+CountOnly+")" );
Log( "MATCHED item(s): " + Num );
index = 0;
if(Num > 0){
while(index <Num){
Log("Node["+index+"] id = " + MyFilteredItems[index].id +
"---Node["+index+"] DisplayName= " +
MyFilteredItems[index].t_DisplayName);
index = index + 1;
}
}
Log("========= END =========");
Here are some more syntax examples of the FILTER runtime parameters that you
can use in a GetByFilter (Filter, DataType, CountOnly) implementation in a UI
data provider.
Example 1:
Filter = "&count=6";
No condition is specified. All items are fetched by the server, but only the first 6
are returned.
Example 2:
20
Netcool/Impact: DSA Reference Guide
Filter = "&count=3&start=2";
No condition specified. All items are fetched by the server, but only the first 3 are
returned, starting at item #2
Example 3:
Filter = "t_DisplayName ends ’ces’
Only items that match the condition = "t_DisplayName ends ’ces’ are fetched.
Example 4:
Filter = "t_DisplayName contains ’W’&count=6&param_One=paramOne";
Only items that match the condition "t_DisplayName contains
’W’&count=6&param_One=paramOne"; are fetched. Only the first six items that
contain 'W' and paramOne are returned and paramOne is available for use by the
provider when it returns the data set.
Example 5:
Filter = "&param_One=paramOne";
All items are fetched by the server, and paramOne is available for use by the
provider when it returns the data set.
Adding Delimiters
The default delimiter is the ampersand (&) character. You can configure a different
delimiter by editing the property impact.uidataprovider.query.delimiter in the
NCI_server.props file. Where NCI is the name of your Impact Server. Any time
you add a delimiter you must restart the Impact Server to implement the changes.
The delimiter can be any suitable character or regular expression, that is not part
of the data set name or any of the characters used in the filter value.
The following characters must use double escape characters \\ when used as a
delimiter:
* ^ $ . |
Examples:
An example using an Asterisk (*) as a delimiter:
v Property Syntax: impact.uidataprovider.query.delimiter=\\*
v Filter query: t_DisplayName contains ’Imp’*count=5
An example with a combination of characters:
v Property Syntax:impact.uidataprovider.query.delimiter=ABCD
v Filter query: t_DisplayName contains ’Imp’ABCDcount=5
An example of a regular expression, subject to Java language reg expression rules:
v Property Syntax: impact.uidataprovider.query.delimiter=Z|Y
v Filter queryt_DisplayName contains ’S’Zcount=9Zstart=7YexecutePolicy=true
An example of a combination of special characters: * . $ ^ |
v Property Syntax: impact.uidataprovider.query.delimiter=\\*|\\.|\\$|\\^|\\|
Chapter 3. Working with the UI data provider DSA
21
v Filter query t_DisplayName contains ’S’.count=9|start=7$executePolicy=true
Retrieving data from a UI provider data source
Create a policy that includes the GetByFilter function to retrieve data by filter
from a UI data provider data source.
To retrieve data from a UI data provider data source, you must create a
Netcool/Impact policy that uses the GetByFilter function to return theUI data
provider data items. The GetByFilter function is modified for use with data
sources. This function retrieves data items whose properties match the specified UI
data provider filter string. The UI data provider filter string is made up of three
parts property 'id', operator, and the value.
You can use the operator AND and the operator OR to repeat the conditions. If you
use these operators together, then the full expression must be in parentheses. For
example:
((NAME contains 'abcd') or (TYPE isnull) or (DESCRIPTION starts 'abcd'))
and (SIZE >= 100) and (LAST_UPDATE > 1)
UI data provider data items contain many properties. Each of these properties has
two attributes that are relevant for filtering UI data provider data items, a display
value attribute and the actual value attribute. Operators are evaluated against the
display value by default. If you want to filter for the actual values instead, you
must add an asterisk (*) before the property. For example:
(*TYPE = 'SERVER')’s
For a full list of the available operators, see “UI data provider operators” on page
26
You can use the Keys function to return an array of strings that contain the field
names for a specific UI data provider data item. For more information about the
Keys function, see the Netcool/Impact Policy Reference Guide.
After you create the policy, you must create a user output parameter and
associated custom schema values for the GetByFilter function to ensure that
Netcool/Impact can process the values that the function returns from the external
UI data provider:
1. In the policy editor, click the Configure User Parameters icon.
Click the New Policy Output Parameter: New button
Select DirectSQL / UI Provider Datatype in the Format field.
Enter a name for the parameter in the Name field.
Enter the same name as defined in the policy in the Policy Variable Name
field.
6. To create the custom schema values, click the Open Schema Definition Editor
2.
3.
4.
5.
icon. You must create custom schema values for each schema that is
defined in the database and included in the returned results. To view the
schema values that are required for your policy, right click the associated data
type and click View Data Items. You must create a custom schema value for
each column that you want to view in the widget in the console.
22
Netcool/Impact: DSA Reference Guide
For more information about how to create user output parameters and custom
schema values, see “Creating custom schema values for output parameters” on
page 24.
Example
In the following policy example, the UI data provider data type called
uidataprovider-ImpactROI is sourcing the data from the REPORT_ImpactROI data
type that uses the GetByFilter function and the IPL policy language. The
REPORT_ImpactROI data type is a standard data type delivered with
Netcool/Impact.
DataType="uidataprovider-ImpactROI";
Filter = "PROCESS_NAME='Escalate'";
CountOnly = false;
The GetByFilter function returns an OrgNodes object that represents an array of
values:
OrgNodes = GetByFilter( DataType, Filter, CountOnly );
The filter matches only one item in the data, and the GetByFilter function returns
one item as a result:
Log("Number of org nodes returned:" + Num); // will be = 1
Log("Key = " + OrgNodes[0].Key); // will be = Escalate
In the following policy example, the data type is myuidataproviderDataType
DataType="myuidataproviderDataType";
Filter = "SAVED_TIME > 1000";
CountOnly = false;
This example returns the following OrgNodes object:
OrgNodes = GetByFilter( DataType, Filter, CountOnly );
If the filter matches two items, the GetByFilter function returns these two items as
follows:
Log("Number of org nodes returned:" + Num);
// will be = 2
Log("Key = " + OrgNodes[0].Key);
// will be = Escalate
Log("Key = " + OrgNodes[1].Key);
// will be = Resolve
The following example demonstrates how to create a user output parameter and
custom values to represent the output of the GetByFilter function. The following
policy uses the GetByFilter function to retrieve data from an external UI data
provider. The values that are returned are contained in the DemoUISchema
parameter.
Filter="&count=200";
DemoUISchema=GetByFilter(’UITestCuriMySQL’,Filter,CountOnly);
Log(DemoUISchema);
You create the following output parameter for to represent the DemoUISchema
parameter. You do not have to enter a data source or data type name.
Table 6. Output parameter for the DemoUISchema parameter
Field
User entry
Name
DemoUISchema
Chapter 3. Working with the UI data provider DSA
23
Table 6. Output parameter for the DemoUISchema parameter (continued)
Field
User entry
Policy variable name
DemoUISchema
Format
DirectSQL / UI Provider Datatype
After you create the output parameter, you must create custom schema values for
id, firstName, and lastName. To view the schema values that are required for your
policy, right click the associated data type and click View Data Items.
Table 7. Custom schema value for id
Field
Entry
Name
id
Format
Integer
Table 8. Custom schema value for fname
Field
Entry
Name
firstName
Format
String
Table 9. Custom schema value for lastName
Field
Entry
Name
lastname
Format
String
Creating custom schema values for output parameters
When you define output parameters that use the DirectSQL, Array of Impact
Object, or Impact Object format in the user output parameters editor, you also
must specify a name and a format for each field that is contained in the
DirectSQL, Array of Impact Object, or Impact Object objects.
About this task
Custom schema definitions are used by Netcool/Impact to visualize data in the
console and to pass values to the UI data provider and OSLC. You create the
custom schemas and select the format that is based on the values for each field
that is contained in the object. For example, you create a policy that contains two
fields in an object:
O1.city="NY"
O1.ZIP=07002
You define the following custom schemas values for this policy:
Table 10. Custom schema values for City
24
Field
Entry
Name
City
Format
String
Netcool/Impact: DSA Reference Guide
Table 11. Custom schema values for ZIP
Field
Entry
Name
ZIP
Format
Integer
If you use the DirectSQL policy function with the UI data provider or OSLC, you
must define a custom schema value for each DirectSQL value that you use.
If you want to use the chart widget to visualize data from an Impact object or an
array of Impact objects with the UI data provider and the console, you define
custom schema values for the fields that are contained in the objects. The custom
schemas help to create descriptors for columns in the chart during initialization.
However, the custom schemas are not technically required. If you do not define
values for either of these formats, the system later rediscovers each Impact object
when it creates additional fields such as the key field. UIObjectId, or the field for
the tree widget, UITreeNodeId. You do not need to define these values for OSLC.
Procedure
1. In the Policy Settings Editor, select DirectSQL, Impact Object, or Array of
Impact Object in the Format field.
2. The system shows the Open the Schema Definition Editor icon
beside
the Schema Definition field. To open the editor, click the icon.
3. You can edit an existing entry or you can create a new one. To define a new
entry, click New. Enter a name and select an appropriate format.
To edit an existing entry, click the Edit icon beside the entry that you want to
edit
4. To mark an entry as a key field, select the check box in the Key Field column.
You do not have to define the key field for Impact objects or an array of Impact
objects. The system uses the UIObjectId as the key field instead.
5. To delete an entry, select the entry and click Delete.
Clearing the UI Data Provider server cache with the UI data provider
DSA
The DSA and the policy function can be used to send a DELETE HTTP request to
the UI Data Provider server. Sending the DELETE method issues a request to the
server to release obsolete cached data sets from memory. Both GetByFilter() and
GetHTTP() functions can be used to send the DELETE HTTP request.
Procedure
1. Use the GetHTTP function to send DELETE requests to the UI Data Provider
server.
The GetHTTP function with the ’DELETE’ method can be run before or after
retrieving a data set. Here is an example of IPL policy with GetHTTP.
host=<host_name> // e.g. "uidp.host.ibm.com";
port =<port_num> // e.g. 15210;
props = NewObject();
props.UserId=<userid> // e.g. "sysadmin";
props.Password =<password> // e.g. "password";
path = "/ibm/tivoli/rest/providers/<provider_name>/datasources/
<datasource_name>/datasets/<dataset_name>?<_paramXXXX>";
// Execute GetHTTP DELETE method to clear cacheof dataset identified with <_paramXXXX>:
Chapter 3. Working with the UI data provider DSA
25
GetHTTP(host, port, "http", path, "key", "DELETE", "BASIC", null, null, null, props);
// Execute GetHTTP GET method to get dataset identified with <_paramXXXX> :
GetHTTP(host, port, "http", path, "key", "GET", "BASIC", null, null, null, props);
The only difference in above GetHTTP method execution is the usage of ’GET’
instead of ’DELETE’ HTTP method
// Log context and display return codes of the HTTP requests
Log(CurrentContext());
2. Using the GetByFilter function to send a DELETE request to UI Data Provider
server.
GetByFilter() can be used to run GET and DELETE HTTP methods. Here is an
example:
DataType="UIDPdatatype_name";
Filter = "param_SourceToken= ’sysitmsles:LZ’count=4 delete=true";
CountOnly = false; OrgNodes = GetByFilter( DataType, Filter, CountOnly );
Log("Number of org nodes returned:" + Num);
// They will be 4 or less Org Nodes returned
Log("Number of org nodes returned:" + Num);
// Log context and display return codes of the HTTP requests
Log(CurrentContext());
The important parameter in the Filter is ’delete=true’. When the GetByFilter
function runs with ’delete=true’ in the filter value, the data set is retrieved
and then the data set is removed from UI Data Provider server cache. If
GetByFilter runs with the Filter value ’delete=false’ or the delete parameter is
omitted, then only the GET request is submitted to the UI Data Provider server
and cache is not cleared.
UI data provider operators
You use these operators to create a filter string for UI data provider data sources.
Table 12. Operators for creating filter strings
String
Numeric and date
Boolean and enumerated
contains
=
=
!contains
!=
!=
starts
<
!starts
<=
ends
>
!ends
>=
isnull
!isnull
=
!=
An example using the UI data provider to integrate with IBM Tivoli
Monitoring
You use the integration with IBM Tivoli Monitoring to send messages from
Netcool/Impact into the Tivoli Monitoring Universal Message Console.
Messages are sent from Tivoli Netcool/Impact into the Tivoli Monitoring Universal
Message Console through the DSA.
26
Netcool/Impact: DSA Reference Guide
Configuring Netcool/Impact to send messages to Tivoli
Monitoring Universal Message Console
Use this procedure to configure Netcool/Impact to send messages to Tivoli
Monitoring 6.1 and higher, Universal Message Console.
Procedure
1. In the Netcool/Impact UI find the ITM project, and the policies for IPL and
JavaScript ITMLibraryFunctionsIPL, ITMLibraryFunctionsJS,
ITMFunctionsCallerIPL, and ITMLibraryFunctionsCallerJS.
2. Update the ITMFunctionsCallerJS or ITMFunctionsCallerIPL policy that you
want to use with Tivoli Monitoring specific information such as host name,
port, user name, password, attribute, and object that is based on the function to
be called.
Remember: The example function is using default values.
3. Run the policy. The functions return an XML formatted string.
Obtaining data from Tivoli Monitoring 6.3 using the UI data
provider
How to obtain data from Tivoli Monitoring 6.3, with the UI data provider DSA.
Procedure
v To obtain data from Tivoli Monitoring 6.3, use the UI data provider DSA to
access the Tivoli Monitoring data provider seeChapter 3, “Working with the UI
data provider DSA,” on page 17.
v For more information, see the following link and information center reference.
– Netcool/Impact devWorks wiki, see examples associated to dashboarding in
the Scenarios and Examples page at the following URL: https://www.ibm.com/
developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/Tivoli
%20Netcool%20Impact/page/Scenarios%20and%20examples
– Netcool/Impact Solutions Guide, Visualizing data from the UI data provider in the
console, Visualizing a data mashup from two IBM Tivoli Monitoring sources. This
example shows how to visualize the data from Tivoli Monitoring sources in
dashboard. You can use the same method to retrieve data for event
management purposes.
Chapter 3. Working with the UI data provider DSA
27
28
Netcool/Impact: DSA Reference Guide
Chapter 4. Working with the LDAP DSA
The LDAP DSA are used to access information stored in an LDAP server.
This type of DSA is read-only. You cannot use Netcool/Impact to insert new LDAP
data into the server data store. The LDAP DSA is s built in DSA and does not
require any additional installation or configuration.
LDAP DSA overview
Netcool/Impact uses the Lightweight Directory Access Protocol (LDAP) data
source adaptor to retrieve data managed by an LDAP server.
The LDAP DSA is a direct-mode data source adaptor that runs in-process with
Netcool/Impact. This DSA is automatically loaded during application run time.
You do not have to start or stop this DSA independently of the application.
Netcool/Impact is not able to use this DSA to add, modify, or delete information
managed by the LDAP server
To use the LDAP DSA, complete the following tasks:
v Create an LDAP DSA data model that provides an abstract representation of the
data managed by the LDAP server.
v Write one or more LDAP DSA policies that retrieve data from the underlying
LDAP server.
For more information about LDAP data model, see.“LDAP data model”
For more information about LDAP policies, see.“LDAP policies” on page 31
Supported LDAP servers
Netcool/Impact supports directory servers that fully implement the LDAP v2 and
v3 specifications, including Netscape, iPlanet, OpenLDAP, and Microsoft Active
Directory servers.
LDAP data model
A Lightweight Directory Access Protocol (LDAP) data model is an abstract
representation of data that is managed by an LDAP directory server.
LDAP data models have the following elements:
v LDAP data sources
v LDAP data types
v LDAP data items
LDAP data sources
The Lightweight Directory Access Protocol (LDAP) data source represent LDAP
directory servers.
Netcool/Impact supports the OpenLDAP and Microsoft Active Directory servers.
© Copyright IBM Corp. 2006, 2015
29
You create LDAP data sources in the GUI Server. You must create one data source
for each LDAP server that you want to access. The configuration properties for the
data source specify connection information for the LDAP server and any required
security or authentication information.
LDAP data types
A Lightweight Directory Access Protocol (LDAP) data type represents a set of
entities in an LDAP directory tree.
The LDAP DSA determines which entities are part of this set in real time by
dynamically searching the LDAP tree for entities that match a specified LDAP filter
within a certain scope. The DSA searches in relation to a location in the tree that is
known as the base context.
Use the GUI to create LDAP data. You must create one LDAP data type for each
set of entities that you want to access. You must create a new field in the data type
for each field of data you want to obtain from the LDAP entities.
The following table shows the configuration properties for an LDAP data type.
Table 13. LDAP Data Type Configuration Properties
Configuration
Property
Description
Data type name
Name of the new LDAP data type.
Search scope
Keyword that indicates the scope for the LDAP search. Possible
values are: OBJECT_SCOPE, ONELEVEL_SCOPE, and SUBTREE_SCOPE.
OBJECT_SCOPE causes the LDAP DSA to search only the specified base
context for matches.
ONELEVEL_SCOPE causes the DSA to search only the child entities of
the base context for matches.
SUBTREE_SCOPE causes the DSA to search all descendants of the base
context.
Base context
Location in the LDAP tree regarding which the LDAP DSA searches
for matching entities. An example is ou=people, o=IBM.com.
Key search field
Attribute in the LDAP entity that uniquely identifies it as a key.
Used when you retrieve data items from an LDAP data type with
the GetByKey function in a policy.
Display name field
Attribute in the LDAP entity that is logged when you log the entity
in a policy.
Restriction filter
LDAP search filter as described in Internet RFC 2254: String
Representation of LDAP Search Filters.
LDAP data items
A Lightweight Directory Access Protocol (LDAP) data item represents an entity in
the LDAP directory tree.
Each field in an LDAP data item corresponds to an attribute in the LDAP entity.
You use the GUI to view LDAP data items. You cannot use the GUI to add,
modify, or delete LDAP data items.
30
Netcool/Impact: DSA Reference Guide
LDAP policies
Information from LDAP data sources is retrieved by the LDAP policies, which are
Netcool/Impact policies. You cannot add, modify, or delete LDAP data from within
a policy.
Retrieving data from an LDAP data source
You can retrieve data, by key, filter, or link, from an LDAP data source by using
the GETbyKey, GetByFilter, and GetByLinks functions when you write a policy.
The following table describes the functions that retrieve LDAP data.
Table 14. Functions that Retrieve LDAP Database Data
Function
Description
GetByKey
Retrieves data items, or entities in the LDAP directory tree, whose key
fields match the specified key expression. The key field is configured
in the Key search field entry in the data type.
GetByFilter
Retrieves data items whose field values match the specified LDAP
filter string.
GetByLinks
Retrieves data items that are dynamically or statically linked to
another data item using the Netcool/Impact GUI.
Example
The following example shows how to use GetByKey to retrieve data items, or
entities in the LDAP directory tree, whose key field matches the specified key
expression. In this example, the LDAP data type associated with a search scope in
the tree is Customer and the key expression is 12345.
DataType = "Customer";
Key = 12345;
MaxNum = 1;
MyCustomer = GetByKey(DataType, Key, MaxNum);
The following example shows how to use GetByFilter to retrieve data items whose
field values match the specified LDAP filter string. The LDAP filter is part of the
specification that is described in Internet RFC 2254. In this example, the LDAP data
type is Facility and the filter string is (|(facility=Wall
St.)(facility=Midtown)(facility=Jersey City)).
DataType = "Facility";
Filter = "(|(facility=Wall St.)(facility=Midtown)(facility=Jersey City))";
CountOnly = False;
MyFacilities = GetByFilter(DataType, Filter, CountOnly);
If the filter does not return any LDAP entities when you think it should,
sometimes this can be fixed be adding a * to the end of the search text. For
example, instead of Filter = "(cn=myuser)", try Filter= "(cn=myuser*)";
The following example shows how to use GetByLinks to retrieve data items that
are statically or dynamically linked to another data item by using the
Netcool/Impact GUI. In this example, you use GetByLinks to retrieve data items of
type Customer that are linked to data items in the MyFacilities array that is
returned in the previous example.
Chapter 4. Working with the LDAP DSA
31
DataType = {"Customer"};
Filter = "";
MaxNum = 1000;
DataItems = MyFacilities;
MyCustomers = GetByLinks(DataType, Filter, MaxNum, DataItems);
For detailed syntax descriptions of these functions, see the Policy Reference Guide.
International character support
The Lightweight Directory Access Protocol (LDAP) Data Source Adaptor (DSA)
follows the LDAP v3 standard for international character support.
This standard specifies that non-ASCII characters must be stored in UTF-8 format
in the LDAP server to be handled correctly by client applications. If you use the
LDAP DSA to access non-ASCII character data, make sure that the data is encoded
using the UTF-8 standard.
32
Netcool/Impact: DSA Reference Guide
Chapter 5. Working with the web services DSA
The web services data source adaptor (DSA) is a direct-mode adaptor that
Netcool/Impact automatically loads during application run time.
You do not have to start or stop this DSA independently of the application. The
web services DSA is installed with Netcool/Impact so you do not have to complete
any additional installation or configuration steps.
To enable SSL connections between Netcool/Impact servers and external servers,
refer to the Netcool/Impact Administration Guide, within the security chapter go
to the 'Enabling SSL connections with external servers' topic.
The web services DSA provides support for WSDL version 1.1 and 2.0, and SOAP
version 1.1.
Web services DSA overview
The web services data source adapter (DSA) is used to exchange data with external
systems, devices, and applications through web services interfaces.
The web services DSA uses blocking messages to communicate with web services.
The use of blocking messages forces Netcool/Impact to wait for a reply from the
web service before it can continue processing a policy. If Netcool/Impact does not
receive a reply in the specified time frame, the DSA times out and returns an error
message to Netcool/Impact.
During policy run time, simple object access protocol (SOAP) messages are sent
through the DSA to the specified web service. The message structure is defined by
a web services definition language (WSDL) file. The message content is defined in
the policy.
After the DSA sends a message, it waits for a reply from the web service. When
the DSA receives the reply, the returned data is converted into data items and
returned to the Impact Server for further processing in the policy.
Complete the following tasks when working with the web services DSA:
v Compile WSDL files that are associated with the interfaces provided by a web
service.
v Create and configure a web services listener that listens on an HTTP port for
SOAP/XML messages from external applications.
v Write policies that send messages to a web service interface and handle the
message replies.
v Write policies that handle SOAP/XML messages that are received by the web
services listener.
Compiling WSDL files
Before you can use the web services DSA, you must compile a Web Services
Description Language (WSDL) file.
© Copyright IBM Corp. 2006, 2015
33
When you compile a WSDL file, you create a set of Java class files that contain a
programmatic representation of the WSDL data. This representation is then used
by the web services DSA when it sends messages to the web service and handles
message replies.
WSDL files are XML documents that describe the public interface that is provided
by a web service.
To
1.
2.
3.
compile the WSDL, you complete the following tasks:
Obtain the WSDL file for the web service.
Run the WSDL compiler script.
The JAR files are created in the $NCHOME/wslib directory on the primary server.
4. You can now use the web services wizard to create a policy with the newly
compiled JAR file.
|
|
Note: If the WSDL file contains XSD imports, files are provided separately. The
WSDL files and related XSD files must be placed in a directory with no spaces.
For more information about WSDL files, see the Web Services Description Working
Group home page on the W3C website at http://www.w3c.org/2002/ws/desc.
Obtaining WSDL files
Every web service must provide one or more Web Services Description Languages
(WSDL) files that define its public interfaces. WSDLs are available from known
URLs.
Procedure
Use a version of the WSDL file that defines the SOAP interface for the web service
with the web services DSA. WSDL files are most often made available by a web
service at a known URL. For example, the web service WSDL for a real-time stock
quote service is available at http://www.webservicex.net/stockquote.asmx?wsdl.
You can compile a WSDL by using its URL or by using a copy of the file that is
stored locally in your file system.
Running the WSDL compiler script
The WSDL compiler script, nci_compilewsdl, creates a JAR file that contains a
programmatic representation of the WSDL data.
Procedure
1. Navigate to the $NCHOME/bin directory.
2. In the command prompt, run the compiler script with the following options:
nci_compilewsdl package_name wsdl_file destination
Where:
package_name
The name of the JAR file (without the .jar suffix) to be created by the
script.
wsdl_file
The name of the JAR file (without the .jar suffix) to be created by the
script.
34
Netcool/Impact: DSA Reference Guide
destination
The directory to copy the generated JAR file to, the default directory is
$NCHOME/wslib.
You must enter the entire command in one line, without any line breaks. For
example, on UNIX:
./nci_compilewsdl amazon US.wsdl $NCHOME/wslib
The example command compiles a WSDL file, US.wsdl that is in the current
working directory, and creates the amazon.jar file, in the $NCHOME/wslib
directory. Another example shows how to compile a WSDL file using a URL:
./nci_compilewsdl weather
http://www.webservicex.net/WeatherForecast.asmx?WSDL ../wslib
The weather.jar file, is created under $NCHOME/wslib directory.
3. Optional: If the destination directory for the script is different from the default
one, you must copy the generated JAR file into the $NCHOME/wslib directory so
that Netcool/Impact policies can use it.
Recompiling new and changed WSDL files
If you change an existing WSDL file or add a new file that uses classes from an
existing WSDL file, you must compile the WSDL file again.
About this task
Netcool/Impact uses the Java archive files that the Java virtual machine stores in
the $IMPACT_HOME/wslib directory. You must remove the existing JAR file that is
related to the WSDL file. Then, recompile the WSDL file.
Procedure
1. Change an existing WSDL file or create a new file that references an existing
file.
2. Move all the Java archive files from the $IMPACT_HOME/wslib directory to a
temporary location.
3. Restart Netcool/Impact.
4. Compile the WSDL file.
5. If the compiled WSDL file is not saved to the $IMPACT_HOME/wslib directory,
move the new JAR file to the $IMPACT_HOME/wslib directory.
6. Move all the Java archive files, except for the files that you either changed or
referenced in your new WSDL file, from the temporary directory to the
$IMPACT_HOME/wslib directory. If you do copy the files that you changed, your
changes are overwritten with the original file.
Enabling and disabling proxy settings using WSInvokeDL
Use the following settings in a policy if you are using the Web Service server
behind a proxy server.
Example
CallProps=NewObject();
CallProps.ProxyEnabled=true;
CallProps.ProxyHost=HostName;
CallProps.ProxyPort=PortNumber;
//The following are optional if required by the Proxy server:
CallProps.ProxyDomain=DomainName;
Chapter 5. Working with the web services DSA
35
CallProps.ProxyUsername=Username;
CallProps.ProxyPassword=Password;
//Password can be plain text or encrypted value using nci_crypt script.
//If it’s an encrypted password, the following property must be used:
CallProps.DecryptPassword=true;
You pass CallProps as an additional argument to the WSInvokeDL command.
For example:
WSInvokeDLResult = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, CallProps);
Web services DSA functions
The web services DSA provides a set of special functions that you use to send
messages from Netcool/Impact to a web service.
v WSSetDefaultPKGName
v WSNewObject
v WSNewSubObject
v WSNewArray
v WSNewEnum
v WSInvokeDL
WSSetDefaultPKGName
The WSSetDefaultPKGName function sets the default package that is used by
WSNewObject and WSNewArray.
The package name is the name that you supplied to the nci_compilewsdl script
when you compiled the WSDL file for the web service. It is also the name of the
JAR file that is created by this script, without the .jar suffix.
Syntax
This function has the following syntax:
WSSetDefaultPKGName(PackageName)
Parameters
The WSSetDefaultPKGName function has the following parameter.
Table 15. WSSetDefaultPKGName function parameter
Parameter
Format
Description
PackageName
String
Name of the default WSDL package used by
WSNewObject and WSNewArray.
Example
The following example sets the default package that is used by subsequent calls to
WSNewObject and WSNewArray to google.
WSSetDefaultPKGName("google");
36
Netcool/Impact: DSA Reference Guide
WSNewObject
The WSNewObject function creates an object of a complex data type as defined in
the WSDL file for the web service.
You use this function when you are required to pass data of a complex type to a
web service as a message parameter.
Syntax
This function has the following syntax:
Object = WSNewObject(ElementType)
Parameters
This WSNewObject function has the following parameter.
Table 16. WSNewObject function parameter
Parameter
Format
Description
ElementType
String
Name of the complex data type that is defined in
the WSDL file. The name format is
[Package.]TypeName, where Package is the name of
the package you created when you compiled the
WSDL file, without the .jar suffix.
Return Value
A new web services object.
Examples
The following example shows how to use WSNewObject to create a web services
object, what you previously called WSSetDefaultPKGName in the policy. This example
creates an object of the data type ForwardeeInfo as defined in the mompkg.jar file
compiled from the corresponding WSDL.
// Call WSSetDefaultPKGName
WSSetDefaultPKGName("mompkg");
// Call WSNewObject
MyObject = WSNewObject("ForwardeeInfo");
The following example shows how to use WSNewObject to create a web services
object, where you did not previously call WSSetDefaultPKGName in the policy.
// Call WSNewObject
MyObject = WSNewObject("mompkg.ForwardeeInfo");
WSNewSubObject
The WSNewSubObject function creates a child object that is part of its parent
object and has a field or attribute name of ChildName.
Syntax
This function has the following syntax:
Object = WSNewSubObject(ParentObject, ChildName)
Chapter 5. Working with the web services DSA
37
Parameters
This WSNewSubObject function has the following parameters.
Table 17. WSNewSubObject function parameters
Parameter
Format
Description
ParentObject
String
Name of the parent object
ChildName
String
Name of the new child object
Return Value
A new web services child object.
Examples
The following example shows how to use WSNewSubObject to create a web services
child object:
// Call WSNewSubObject
ticketId=WSNewSubobject(incident, "TICKETID");
WSNewArray
The WSNewArray function creates an array of complex data type objects or
primitive values, as defined in the WSDL file for the web service.
You use this function when you are required to pass an array of complex objects or
primitives to a web service as message parameters.
Syntax
This function has the following syntax:
Array = WSNewArray(ElementType, ArrayLength)
Parameters
The WSNewArray function has the following parameters:
Table 18. WSNewArray function parameters
Parameter
Format
Description
ElementType
String
Name of the complex object or primitive data type that is
defined in the WSDL file. The name format is
[Package.]TypeName, where Package is the name of the
package you created when you compiled the WSDL file,
without the .jar suffix. The package name is required
only if you did not previously call the
WSSetDefaultPKGName function in the policy.
ArrayLength
Integer
Number of elements in the new array.
Return Value
The WSNewArray returns the new array that is created by the function.
38
Netcool/Impact: DSA Reference Guide
Examples
The following example shows how to use WSNewArray to creates a web services
array, where you previously called WSSetDefaultPKGName in the policy. This
example creates an array of the data type String as defined in the mompkg.jar file
that is compiled from a WSDL file.
// Call WSSetDefaultPKGName
WSSetDefaultPKGName("mompkg");
// Call WSNewArray
MyArray = WSNewArray("String", 4);
The following example shows how to use WSNewArray to create a web services
array, where you did not previously call WSSetDefaultPKGName in the policy.
// Call WSNewArray
MyArray = WSNewArray("mompkg.String", 4);
The following example invokes a web service method called runPolicy and passes
in a string array as a parameter to the method. The policy creates a WSNewArray
object and populates the object with 3 elements. Note that WSNewArray object is
used only for arrays of primitives. For arrays of complex types, you need to create
a WSNewSubObject for each array element. Also, in general it is easier to use the
web services wizard to generate the web services policy from a WSDL, rather than
manually creating the web services policy.
RunPolicyDocument=WSNewObject("com.myexample.RunPolicyDocument");
_RunPolicy=WSNewSubObject(RunPolicyDocument,"RunPolicy");
_Arg0=WSNewArray("java.lang.String",3);
_Arg0[0] = ’aaa’;
_Arg0[1] = ’bbb’;
_Arg0[2] = ’ccc’;
_RunPolicy.Arg0Array=_Arg0;
WSParams = {RunPolicyDocument};
WSService = ’MyWebService’;
WSEndPoint = ’http://localhost:8888/MyWebService;
WSMethod = ’runPolicy’;
WSInvokeDLResult = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams);
WSInvokeDL
The WSInvokeDL function makes web services calls when a Web Services
Description Language (WSDL) file is compiled with nci_compilewsdl, or when a
policy is configured using the Web Services wizard.
Syntax
This function has the following syntax:
[Return] = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, [callProps])
This function returns the value of your target web services call.
Chapter 5. Working with the web services DSA
39
Parameters
The WSInvokeDL function has the following parameters:
Table 19. WSInvokeDL function parameters
Parameter
Format
Description
WSService
String
This web service name is defined in the /definitions/service
element of the WSDL file.
WSEndPoint
String
The web service endpoint URL of the target web service.
WSMethod
String
The web service method defines which method you would like
to call in WSInvokeDL().
WSParams
Array
The web services operation parameters are defined by
/definitions/message/part elements in the WSDL file. It
comprises an array that contains all of the parameters that are
required by the specified web service operation.
callProps
String,
Boolean,
integer
The optional container in which you can set any of the
properties, which are listed in the callProps properties section.
callProps properties
Remember: Any options that are set in callProps must precede the actual call to
WSInvokeDL.
v Chunked divides the packets into small chunks if the server supports the feature.
The default property is true.
Tip: If you receive the following error message when running the WSInvokeDL
function then set this property to false.
Transport error: 11 Error: Length Required in policy
v MTOM enables or disables the Message Optimization for the SOAP message.
v CharSet sets the encoding other than UTF-8.
v HTTP the default HTTP version is 1.1. You can use this property to set the
protocol version to 1.0.
v ReuseHttpClient enables the underlying infrastructure to reuse the HTTP client
if one is available. The ReuseHttpClient is useful if the client is using HTTPS to
communicate with the server. The SSL handshake is not repeated for each
request. The parameter must be set to true or false.
v EnableWSS enables web Service Security. If you specify EnableWSS, you must also
specify the following properties:
– WSSRepository, which specifies the path location of WSS Repository.
– WSSConfigFile, which specifies configuration file for EnableWSS.
v Username specifies the user name for basic authentication.
v Password specifies the password for basic authentication. PreemptiveAuth enables
Preemptive Authentication.
v Timeout this property is used in a blocking scenario. The client system times out
after the specified amount of time.
You can optionally set a global web Service DSA call timeout property called
impact.server.dsainvoke.timeout. The property must be added to the
Netcool/Impact server property file, <servername>_server.props. It is best to use
the timeout property on a per policy basis as specified in callProps.Timeout.
40
Netcool/Impact: DSA Reference Guide
The value is set in milliseconds, for example,
impact.server.dsainvoke.timeout=30000 (30 seconds).
When you set the properties in any of the .props files, restart theNetcool/Impact
server to implement the changes.
If the impact.server.dsainvoke.timeout property is set, all WSInvokeDL calls
use the same timeout setting.
v MaintainSession sets the session management to enabled status. When session
management is enabled, the system maintains the session-related objects across
the different requests. The parameter must be set to true or false.
v CacheStub caches generated stubs. This value must be set to true if either or
both of the following properties are enabled, ReuseHttpClient, MaintainSession.
Examples of usage:
callProps.CacheStub=true;
callProps.ReuseHttpClient = true;
v CustomHeaders adds custom header values other than the headings that are
already supported in the documentation.
v DecryptPassword enables the decryption of an encrypted password in a policy.
v HandleFault is used to manage faults. Fault messages are returned from the web
services server to indicate that there is a problem.
v LogSoapMessages: You can enable logging of the full outgoing and incoming
soap messages, by adding the LogSoapMessages property to callProps and
setting it to true. This property should be used for debugging purposes and not
left on permanently in a production environment.
CallProps = newObject();
CallProps.LogSoapMessages = "true":
WSInvokeDLResult = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, CallProps);
The logs are written to $IMPACT_HOME/wlp/usr/servers/<server>/logs/
messages.log.
Examples
Remember: Any options that are set in callProps must precede the actual call to
WSInvokeDL.
Apart from its primary usage, the callProps container can be used to enable
security. For example, if the basic authentication is enabled through the wizard, the
sample policy contains the following lines:
callProps.Username="username";
callProps.Password="password";
The following example shows how to use the WSInvokeDL function to send a
message to the target web service.
Example using IPL:
ServiceName = "StockQuote";
EndPointURL = "http://www.webservicex.net/stockquote.asmx";
MethodName = "GetQuote";
ParameterArray = { "IBM" };
Results = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, {callProps});
Example using JavaScript:
ServiceName = "StockQuote";
EndPointURL = "http://www.webservicex.net/stockquote.asmx";
MethodName = "GetQuote";
Chapter 5. Working with the web services DSA
41
ParameterArray = [ "IBM" ];
Results = WSInvokeDL(WSService, WSEndPoint, WSMethod, WSParams, [callProps])
Use the DecryptPassword policy parameter to enable the decryption of an
encrypted password in a policy that is used with the CallProps function:
CallProps=NewObject();
CallProps.Password="<Web Serice encrypted using nci_crypt>";
CallProps.DecryptPassword=true;
//default is false and must be plain text password.
The password is decrypted at policy runtime and is used in plain text internally to
Netcool/Impact.
You can also use the CustomHeaders parameter to add custom http header values
other than the headings that are already supported in the documentation.
Headers = NewObject();
Headers.HeaderName1=’HeaderValue1’;
Headers.HeaderName2=’HeaderValue2’;
CallProps.CustomHeaders=Headers;
Use the HandleFault parameter to handle fault messages.
CallProps=NewObject();
CallProps.HandleFault=true;
When the default value is false, the policy throws an exception. When the value is
true, the policy returns only the fault string message. No fault code is returned.
If the value is true, the return is similar to the following example.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<Fault>
<faultstring> some message here
</faultstring>
</Fault>
To turn off the formatting and return the message in plain text add the following
parameter anywhere in <serverName>_server.props:
impact.wsinvoke.formatfaultmessage=false
The changes are implemented dynamically without restarting the server.
WSNewEnum
The WSNewEnum function returns an enumeration value to a target web service.
Syntax
This function has the following syntax:
[Return] = WSNewEnum(EnumType, EnumValue);
42
Netcool/Impact: DSA Reference Guide
Parameters
The WSNewEnum function has the following parameters.
Table 20. WSNewEnum function parameters
Parameter
Format
Description
EnumType
String
The enumeration class name that exists in the package
that is created by nci_compilewsdl
EnumValue
String
The enumeration value to return
Return Value
A new enumeration type and value.
Example
The following example shows how to use the WSNewEnum function to send a
message to the target web service.
euro = WSNewEnum("net.webservicex.www.Currency", "EUR");
usd = WSNewEnum("net.webservicex.www.Currency", "USD");
Writing Web services DSA policies
You can complete the following tasks with the web services DSA in a
Netcool/Impact policy:
v Send messages to a web service
v Handle data that is returned from a web service as a message reply
Sending messages
You can use the web services DSA to send messages.
Procedure
1. Call WSSetDefaultPKGName.
2. Add message parameters with any required data.
3. Call WSInvoke or WSInvokeDL.
Important: [The WSInvoke feature is deprecated.]
When a WSDL file is compiled with nci_compilewsdl or by the web services
DSA wizard, you must use the WSInvokeDL() function to make web services
calls.
Calling WSSetDefaultPKGName
The default package used for communication with the web service is set by the
WSSetDefaultPKGName function.
The package name can be the name you supplied to the nci_compilewsdl script
when you compiled the WSDL file for the web service. This name is also the name
of the JAR file created by this script, without the .jar suffix. The package name
can also be any other Java package that resides in the CLASSPATH and contains the
class definition of an object you want to use with the WSNewObject or WSNewArray
functions (for example, java.util).
Chapter 5. Working with the web services DSA
43
To set the default package, you call WSSetDefaultPKGName and pass the name of the
package, without the .jar suffix.
Example
The following example shows how to set the default package:
WSSetDefaultPKGName("google");
In this example, google.jar is the package you created when you compiled the
WSDL file for the web service.
Note: If you do not call this function before you call WSNewArray or WSNewObject,
you must explicitly specify the package name in those function calls.
Examples using web services DSA functions
The following examples illustrate how the web services DSA functions and
demonstrates its abilities.
Example using web services DSA functions to create a real-time
stock quote service
You can add a combination of web services DSA functions to create a policy. The
following IPL policy example uses a stock quote service.
WSSetDefaultPKGName("impactstockquote");
endpoint ="http://www.webservicex.net/stockquote.asmx";
quoteDoc=WSNewObject("net.webservicex.www.GetQuoteDocument");
quote = WSNewSubObject(quoteDoc, "GetQuote");
quote.Symbol="IBM";
params = { quoteDoc };
return = WSInvokeDL("StockQuote", endpoint, "GetQuote", params);
result = return.GetQuoteResponse.GetQuoteResult;
log("result = " + result);
The following example is the same but uses JavaScript, where the params =
[quoteDoc]; value is enclosed in braces ([]).
WSSetDefaultPKGName("impactstockquote");
endpoint ="http://www.webservicex.net/stockquote.asmx";
quoteDoc=WSNewObject("net.webservicex.www.GetQuoteDocument");
quote = WSNewSubObject(quoteDoc, "GetQuote");
quote.setSymbol("IBM");
params = [ quoteDoc ];
return = WSInvokeDL("StockQuote", endpoint, "GetQuote", params);
result = return.GetQuoteResponse.GetQuoteResult;
Log("result = " + result);
Example that uses web services DSA functions to create a
Global Weather service
The policy in IPL included the following web services DSA functions:
WSSetDefaultPKGName, WSNewObject, WSNewSubObject, and WSInvokeDL.
44
Netcool/Impact: DSA Reference Guide
WSSetDefaultPKGName("impactglbweather");
endpoint ="http://www.webservicex.net/globalweather.asmx";
weatherdoc=WSNewObject("net.webservicex.www.GetWeatherDocument");
weather = WSNewSubObject(weatherdoc, "GetWeather");
weather.CityName = "New York";
weather.CountryName = "United States";
params = { weatherdoc };
return = WSInvokeDL("GlobalWeather", endpoint, "GetWeather", params);
result = return.GetWeatherResponse.GetWeatherResult;
log("result = " + result);
The following example is the same but uses JavaScript, where the params value is
enclosed in braces ([]).
WSSetDefaultPKGName("impactglbweather");
endpoint ="http://www.webservicex.net/globalweather.asmx";
weatherdoc=WSNewObject("net.webservicex.www.GetWeatherDocument");
weather = WSNewSubObject(weatherdoc, "GetWeather");
weather.setCityName("New York");
weather.setCountryName("United States");
params = [ weatherdoc ];
return = WSInvokeDL("GlobalWeather", endpoint, "GetWeather", params);
result = return.GetWeatherResponse.GetWeatherResult;
Log("result = " + result);
Example that uses web services DSA functions to create a
currency converter service
The policy in IPL, includes the following web service DSA functions:
WSSetDefaultPKGName, WSNewObject, WSNewSubObject, WSInvokeDL, and WSNewEnum.
WSSetDefaultPKGName("impactcurrencyconverter");
endpoint ="http://www.webservicex.net/CurrencyConvertor.asmx";
convDoc=WSNewObject("net.webservicex.www.ConversionRateDocument");
rate = WSNewSubObject(convDoc, "ConversionRate");
fromCur = WSNewEnum("net.webservicex.www.Currency", "EUR");
rate.FromCurrency = fromCur;
toCur = WSNewEnum("net.webservicex.www.Currency", "USD");
rate.ToCurrency = toCur;
params = { convDoc };
return = WSInvokeDL("CurrencyConvertor", endpoint, "ConversionRate", params);
result = return.ConversionRateResponse.ConversionRateResult;
log("result = " + result);
log("--------------------------------");
The following example is the same but uses JavaScript, where the params value is
enclosed in square braces [].
WSSetDefaultPKGName("impactcurrencyconverter");
endpoint ="http://www.webservicex.net/CurrencyConvertor.asmx";
convDoc=WSNewObject("net.webservicex.www.ConversionRateDocument");
rate = WSNewSubObject(convDoc, "ConversionRate");
fromCur = WSNewEnum("net.webservicex.www.Currency", "EUR");
rate.setFromCurrency(fromCur);
toCur = WSNewEnum("net.webservicex.www.Currency", "USD");
rate.setToCurrency(toCur);
params = [ convDoc ];
Chapter 5. Working with the web services DSA
45
return = WSInvokeDL("CurrencyConvertor", endpoint, "ConversionRate", params);
result = return.ConversionRateResponse.ConversionRateResult;
Log("result = " + result);
Log("--------------------------------");
Web services listener
The web services listener is a service that provides a Netcool/Impact web services
interface to other applications to run Netcool/Impact policies.
Before you can use the web services listener, you must assign the
impactAdminUser or impactWebServiceUser role to the user who uses the web
services.
See the section Working with the command line, Netcool/Impact Roles in the main
documentation for more information.
Web services listener process
Policy requests from external applications are managed by the web services
listener.
The web services listener listens at an HTTP port for SOAP/XML messages from
external applications. These messages make requests to Netcool/Impact to run a
policy. When the listener receives a request, it sends it to the Netcool/Impact
policy engine and any runtime parameters and returns the policy results to the
calling application through the HTTP port.
The requests can also be made over HTTPS protocol.
Netcool/Impact 7.1.0.3 has web services listener implementation that is not
compatible with versions prior to 7.1 of Netcool/Impact.
If you had a previous implementation with any of the following items you need to
take the following steps:
v A Java client that connects to a web services listener: If the Java client is using
the Jar file from a previous version of Netcool/Impact, the Java client must be
modified to handle the new methods and new parameter names or a new Java
client class must be used. You can use the WSTestDL.java file as an example to
model the new Java client. The WSTestDL.java file is in the $IMPACT_HOME/
integrations/web-service-listener/ directory. The WSTestDL.java file differs
from any previous version.
v An XML soap envelope client such as SoapUI: The XML must be rewritten or
you must create new project for Netcool/Impact 7.1.0.3 by using the WSDL file
in the $IMPACT_HOME/integrations/web-service-listener directory.
v A Netcool/Impact policy that uses the web services DSA to call the external
Impact Web Services Listener, and uses the WSInvokeDL function that used
compiled classes for a previous version of the WSDL file: You must compile a
new package with the updated WSDL file and policy must be updated. See the
examples in “Compiling the WSDL file for the web services listener” on page 47
Setting up the web services listener
The web services listener is automatically installed when you install
Netcool/Impact. You do not need to complete any additional configuration steps.
46
Netcool/Impact: DSA Reference Guide
You can obtain the web services client information, including the WSDL file and a
set of utilities that help you work with web services, at the $NCHOME/integrations/
web-service-listener directory.
The following files are provided with the web services listener.
ImpactWebServiceListenerDLService.wsdl
The Web Service Listener WSDL file.
WSListenerTestPolicy.ipl
A sample policy.
WSTestDL.java
A sample client file.
README
A readme file.
bin/test_wslistener.bat
The script that runs the sample client.
/lib
This directory contains JAR files for sample application.
$NCHOME/bin/nci_findendpoint
The script that you can use to find the SOAP endpoint for an Impact
Server.
Compiling the WSDL file for the web services listener
Use the web services listener WSDL file that is provided in the
integrations/web-service-listener directory.
About this task
This WSDL file ImpactWebServiceListenerDLService.wsdl provides a set of classes
that are compatible with the Apache axis 2 compiler. The package name is
com.micromuse.response.common.types.
Procedure
Compile the web services listener WSDL file in the usual way. See “Running the
WSDL compiler script” on page 34. When the web services listener WSDL file has
compiled, you can execute a policy like the following example:
Example
To create a Java based client to run a policy, use the WSTestDL.java file as example
to model the code. Using the XML soap envelope client, the XML is similar to the
following examples.
Run a policy without input parameters, no results are retuned.
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:typ="http://response.micromuse.com/types">
<soapenv:Header/>
<soapenv:Body>
<typ:runPolicy>
Chapter 5. Working with the web services DSA
47
<arg0>PolicyNameTest</arg0>
<arg2>false</arg2>
</typ:runPolicy>
</soapenv:Body>
</soapenv:Envelope>
Run a policy with one input parameter, returns a result.
<soapenv:Envelope
xmlns:soapenv="http://
schemas.xmlsoap.org/soap/envelope/"
xmlns:typ="http://
response.micromuse.com/types">
<soapenv:Header/>
<soapenv:Body>
<typ:runPolicy>
<arg0>PolicyNameTest</arg0>
<!--Zero or more repetitions:-->
<arg1>
<desc>ProductName</desc>
<format>String</format>
<label>ProductName</label>
<name>ProductName</name>
<value>Impact V7.1</value>
</arg1>
<arg2>false</arg2>
</typ:runPolicy>
</soapenv:Body>
</soapenv:Envelope>
Multiple input parameters and returns result
<soapenv:Envelope
xmlns:soapenv="http://
schemas.xmlsoap.org/soap/envelope/"
xmlns:typ="http://
response.micromuse.com/types">
<soapenv:Header/>
<soapenv:Body>
<typ:runPolicy>
<arg0>PolicyNameTest</arg0>
<!--Zero or more repetitions:-->
<arg1>
<desc>ProductName</desc>
<format>String</format>
<label>ProductName</label>
<name>ProductName</name>
<value>Impact</value>
</arg1>
<arg1>
<desc>Company</desc>
<format>String</format>
<label>Company</label>
<name>Company</name>
<value>IBM</value>
</arg1>
<arg1>
<desc>Revision</desc>
<format>Integer</format>
<label>Revision</label>
<name>Revision</name>
<value>7</value>
</arg1>
<arg2>true</arg2>
</typ:runPolicy>
</soapenv:Body>
</soapenv:Envelope>
48
Netcool/Impact: DSA Reference Guide
Writing web services listener policies
Web service listener policies are run in response to web messages that are sent to
Tivoli Netcool/Impact from other applications.
The web messages that are sent to Tivoli Netcool/Impact specify the name of the
policy to be run and a set of runtime parameters. External applications use runtime
parameters to pass data to the policy. The web services listener does not pass an
event container to the policy engine. Web services listener policies return data to
calling applications in the form of a data item that is called WSListenerResult. The
policies return one data item at a time.
Runtime parameters:
Runtime parameters in web services listener policies are handled in the same way
as any other policy.
You can use the variable name to reference the parameters in the policy. No
initialization of the variables is required.
For example, if an incoming web services message contains runtime parameters
named Param1, Param2, and Param3, when it runs the policy the web services
listener creates new variables in the policy context with those parameter names.
The following code shows how to reference those variables in a policy:
// Log incoming runtime parameters
Log("Value of Param1: " + Param1);
Log("Value of Param2: " + Param2);
Log("Value of Param3: " + Param3);
Note that all runtime parameters in a web services listener policy are strings. No
other type of value can be passed to such a policy from calling applications.
WSListenerResult:
WSListenerResult is a special data item that contains the result of a web services
policy.
You can use NewObject function to create the WSListenerResult data and populate
its member variables with values. When the policy terminates, this data item is
passed to the web services listener to be returned to the calling application.
The following example shows how to create the WSListenerResult data item and
populate its member values.
WSListenerResult = NewObject();
WSListenerResult.Node = "192.168.1.1";
WSListenerResult.Location = "New York";
WSListenerResult.Summary = "Node not responding to ping.";
WSListenerResult can contain other data types. The caller parses the object to get
the right data from the result. The name contains the field name through which the
caller can identify the type of data that is used.
For example, the "SERVICEREQUESTIDENTIFIER" column from the database, is
an Integer.
Chapter 5. Working with the web services DSA
49
The assignment WSListenerResult.SERVICEREQUESTIDENTIFIER=_result[0]
.SERVICEREQUESTIDENTIFIER assigns the Integer value to the result. The result is the
return value from the GetByFilter function. If the value of the service request is "1",
then:
v The getValue method from the policyExecutionResult returns 1.
v The getName method from the policyExecutionResult returns
SERVICEREQUESTIDENTIFIER.
Results from policy execution into WSListenerResult variable:
WSListenerResult supports the return of Array of Impact Objects. You can return
one or more Array of Impact Objects. The client must set the return variable to
true: in XML: <arg3>true</arg3>, in Java Class: runPolicy.setArg3(true);.
To return a WSListenerResult as one Impact object:
WSListenerResult = NewObject();
WSListenerResult.FirstName=”MyName”;
WSListenerResult.LastName=”MyLastName”;
To return one or more Array Of Impact Objects:
WSListenerResult=NewObject();
index = 0;
objects=[];
objects1=[];
while (index < 5) {
Obj = NewObject();
Obj.FirstName="FistNameJS"+index;
Obj.LastName="LastNameJS"+index;
Obj.Location="LocationJS"+index;
Obj1=NewObject();
Obj1.DOB=LocalTime(GetDate());
Obj1.PlaceOfBirth="City"+index;
objects[index]=Obj;
objects1[index]=Obj1;
index = index +1;
}
WSListenerResult.FirstObject=objects;
WSListenerResult.SecondObject=objects1;
The name of the array can be anything, it is not used as an element, for example,
FirstObject, SecondObject.
To return combination of Array of Impact Objects and any other variable:
WSListenerResult=NewObject();
Log( "class of WSListenerResult: " + ClassOf(WSListenerResult));
index = 0;
objects={};
while (index < 5) {
Obj = NewObject();
Obj.FirstName="FistName"+index;
Obj.LastName="LastName"+index;
Obj.Location="Location"+index;
index = index +1;
objects=objects+{Obj};
}
WSListenerResult.ImpactObject=objects;
WSListenerResult.Product="Impact";
50
Netcool/Impact: DSA Reference Guide
The Return Document: The XML returned from calling runPolicy method has
parent name element “return”: example:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<a:runPolicyResponse xmlns:a="http://types.common.response.micromuse.com/">
<return>
<name>Product</name>
<value>Impact</value>
</return>
<return>
<name>Location</name>
<value>Location0</value>
</return>
<return>
<name>FirstName</name>
<value>FistName0</value>
</return>
<return>
<name>LastName</name>
<value>LastName0</value>
</return>
<return>
<name>Location</name>
<value>Location1</value>
</return>
<return>
<name>FirstName</name>
<value>FistName1</value>
</return>
<return>
<name>LastName</name>
<value>LastName1</value>
</return>
</a:runPolicyResponse>
</soap:Body>
</soap:Envelope>
Writing applications that call into Web services
When you write applications that call into the Web services, you must have the
following information:
v Location of the SOAP endpoint.
v WSDL file.
SOAP endpoint
The Simple Object Access Protocol (SOAP) endpoint is a URL. It identifies the
location on the built-in HTTP service where the web services listener listens for
incoming requests. Calling applications must specify this endpoint when they send
web services messages to Netcool/Impact.
The endpoint URL varies depending on the configuration of Netcool/Impact. The
following URL uses the default configuration.
http://<hostname>:<port>/jaxws/impact/ImpactWebServiceListenerDLIfc
Where <hostname> is the name of the system where Netcool/Impact is installed,
<port> is the port number that is used by the built-in HTTP service. The default
port number is 9080.
Chapter 5. Working with the web services DSA
51
The following example shows the endpoint URL for a web services listener that is
running on a system named impact_01 and uses the default port.
http://impact_01:9080/jaxws/impact/ImpactWebServiceListenerDLIfc
You can also determine the SOAP endpoint by using the nci_findendpoint script
in the $NCHOME/bin directory. When you run this script, it connects to the Name
Server, looks up the SOAP endpoint, and prints the URL to the standard output.
The syntax of nci_findendpoint is as follows:
nci_findendpoint server_name
Where server_name is the name of the Impact Server instance for example, NCI.
The web services call must provide a user name who has the ImpactAdminUser
role in the Impact Server and the password for this user. By default, the
impactadmin user has the ImpactAdminUser role.
Authentication for the web services listener
Before you can use the web services listener, you must assign the
ImpactAdminUser role to the user who uses the web services.
If you use an XML envelope such as SoapUI, you must configure the username and
password in the properties of the header. If you use an Netcool/Impact policy you
must configure the username and password in the Web Services Security section.
For more information about how to assign these roles, see Working with
command-line tools > Using WebServices through the command line > Mapping
groups, and users to roles on the Netcool/Impact information center at or in the
Administration Guide PDF file.
WSDL file
The Web Services Description Language (WSDL) file is an XML document that
describes the web services interface.
The WSDL file specifies three messages that define the terms of communication
between Tivoli Netcool/Impact and calling applications. Calling applications use
these messages to log in to Tivoli Netcool/Impact and to request the execution of a
policy. You can also use the messages to respond to login requests and return
policy results. The WSDL file also specifies types of data that can be passed in the
body of the messages.
The WSDL specifies the following messages:
v runPolicy
v runPolicyResponse
v WSListenerException
runPolicy
The runPolicy message requests that Tivoli Netcool/Impact run the specified
policy.
Table 1 shows the parameters in runPolicy.
52
Netcool/Impact: DSA Reference Guide
Table 21. runPolicy
Parameter
Description
policyName
Name of the policy to be run.
policyUserParams
Array of runtime parameters to pass to the policy, where each
parameter is represented in the WSDL file as a variable of the
complex type WslPolicyUserParameter. You must set the values of
the format, name, and value elements of each parameter to display
the values in the WSDL file. The required value of the format
element is String. The value of the name element is the name of the
parameter as it is handled in the policy. The value of the value
element is the parameter value.
wantResult
Specifies whether to return the results of the policy to the calling
application.
A calling application sends this message. The web services listener responds by
returning a message of type runPolicyResponse.
An example using runPolicy. The target namespace is http://
types.common.response.micromuse.com The variables names are: arg0, arg1, arg2,
and arg3.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:typ="http://types.common.response.micromuse.com/">
<soapenv:Header/>
<soapenv:Body>
<typ:runPolicy>
<arg0>PolicyName</arg0>
<arg1>
<desc>input_parameter</desc>
<format>String</format>
<label>input_parameter</label>
<name>input_parameter</name>
<value>value</value>
</arg1>
<arg2>true</arg2>
</typ:runPolicy>
</soapenv:Body>
</soapenv:Envelope>
runPolicyResponse
The runPolicyResponse message is sent by the web services listener in response to
a request from a calling application to run a policy.
The runPolicyResponse contains a single parameter result. This parameter
contains an array of name-value pairs that correspond to the member variables in
the WSListenerResult data item that is returned by the policy.
The web services listener sends this message to a calling application if the
wantResult parameter was specified as true in the originating runPolicy message.
WSListenerException
The WSListenerException message is sent by the web services listener in response
to invalid messages from a calling application.
The WSListenerException contains a single parameter named WSListenerException
that provides detail about the error.
Chapter 5. Working with the web services DSA
53
Sample policy and sample client
A sample policy and a sample client, which you can use to learn about web
services listener, are provided.
v The sample policy is WSListenerTestPolicy.ipl.
v The sample client is WSTestDL.java.
They are in the $NCHOME/integrations/web-service-listener directory. You can
run the sample client by using the test_wslistener script that is in the
$NCHOME/integrations/web-service-listener/bin directory.
1. To run the provided sample client. Import WSListenerTestPolicy.ipl into
Netcool/Impact.
2. Run the $IMPACT_HOME/bin/nci_findendpoint script to determine the endpoint
of the Doc/Literal listener.
3. Invoke the test_wslistener.bat script passing the endpoint as an argument as
well as an impactadmin username and password, and optionally a policy name.
For example:
test_wslistener.bat
http://ImpactHostName.ibm.com:16310/jaxws/impact/ImpactWebServiceListenerDLIfc
impactadmin netcool123
1. To create a Java Client to connect to the web services listener, use the
WSTestDL.java file that is in the $IMPACT_HOME/integrations/web-servicelistener directory.
2. To start the policy by using the XML Soap Envelop client such as SoapUI.
v Run a policy with one input parameter that does not return a result.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<typ:runPolicy xmlns:typ="http://response.micromuse.com/types">
<arg0>WSSSample03</arg0>
<arg1>
<desc>Product</desc>
<format>String</format>
<label>Product</label>
<name>Product</name>
<value>Impact</value>
</arg1>
<arg2>false</arg2>
</typ:runPolicy>
</soapenv:Body>
</soapenv:Envelope>
v Run a policy with multiple input parameters that returns a result.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<typ:runPolicy xmlns:typ="http://response.micromuse.com/types">
<arg0>WSSSample03</arg0>
<arg1>
<desc>Product</desc>
<format>String</format>
<label>Product</label>
<name>Product</name>
<value>Impact</value>
</arg1>
<arg1>
<desc>Company</desc>
<format>String</format>
<label>Company</label>
<name>Company</name>
<value>IBM</value>
</arg1>
<arg2>false</arg2>
</typ:runPolicy>
</soapenv:Body>
</soapenv:Envelope>
Configuring a secure web services listener connection
To start the web services listener over SSL, you must generate a certificate in the
Impact Server keystore and import it into the truststore of the client.
54
Netcool/Impact: DSA Reference Guide
About this task
The Liberty keystore used by Netcool/Impact contains a default certificate for the
host where Netcool/Impact is installed. The certificate matches the fqdn or short
host name depending on your environment.
Procedure
1. Use the following command to export the self-signed certificate to a file called
mycertificate.
$IMPACT_HOME/sdk/bin/keytool -export -alias default -file mycertificate
-keystore $IMPACT_HOME/wlp/usr/servers/<server>/resources/security/key.jks
2. When prompted enter the keystore password which will be the impactadmin
user password configured at installation time.
3. Copy the mycertificate file to the location where you want to start the
WebService call and import the certificate into the truststore that is used by the
Java process. By default the truststore that is used by the Java process is in the
$JAVA_HOME/jre/lib/security/cacerts file and its default password is
changeit.
This password is not managed or updated by the Netcool/Impact installer. If
you change the password you can for you convenience make it the same as the
Liberty or Impact keystore password.
$JAVA_HOME/bin/keytool -import -alias default -file mycertificate
-keystore $JAVA_HOME/jre/lib/security/cacerts
If you are running the test_wslistener script from the Netcool/Impact
installation, the $JAVA_HOME that is used is $IMPACT_HOME/sdk.
4. When prompted enter the Java keystore password.
5. Use the following command to run the test_wslistener script:
test_wslistener.bat https://<hostname>:<https port>
/jaxws/impact/ImpactWebServiceListenerDLIfc
impactadmin <password> <optional policy>
Where <hostname> is the host name you configured in the CN field of the dname
argument of the certificate.
6. Run the following command to execute the sample client on a remote host or
the Impact Server.
$JAVA_HOME\bin\java -Djavax.net.ssl.keyStore=
$JAVA_HOME\<jre>\lib\security\cacerts"
-cp ".;<$IMPACT_HOME>\integrations\web-service-listener\lib\*"
WSTestDL https:/<impacthost>:16311/jaxws/impact/ImpactWebServiceListenerDLIfc
impactadmin <password> password <policy>
Where <password> is the impactadmin user password and <policy> is the name
of the policy to execute.
Creating policies by using the web services wizard
You can use the web Services wizard to develop policies. To do so, you connect to
the GUI and follow the on-screen prompts.
Procedure
1. In the Policies tab, select the arrow next to the New Policy icon. To run the
Web services wizard, select Use Wizard > Web Services.
2. In the Web Services Invocation-Introduction window, type in your policy name
in the Policy Name field. Click Next to continue. Example
http://www.webservicex.net/stockquote.asmx?wsdl.
Chapter 5. Working with the web services DSA
55
3. In the Web Services Invocation-WSDL file and Jar File window, in the URL or
Path to WSDL field, enter the URL or a path for the target WSDL file.
In instances where the GUI server is installed separately from the back-end
server, the file path for the WSDL file refers to the back-end server file system,
not the GUI server file system. If you enter a URL for the WSDL file, that URL
must be accessible to the back-end Impact Server host and the GUI server host.
Note: If the WSDL file contains XSD imports, these files are provided
separately. The WSDL files and related XSD files must be placed in a directory
with no spaces.
4. In the Jar file area, select one of the following available options:
v Select a previously generated jar file for the WSDL file:
Applies if you generated a jar file from a WSDL file previously. Select one of
the existing jar files from the list menu.
– Currency.jar
– Stock.jar
– length.jar
The Package Name field is automatically completed. Select the Edit check
box to modify the package name.
v Provide a package name for the new jar file :
Select this option to create a jar file. Complete the Package Name field for
the new jar file. The package name cannot have a period ".".
Click Next.
5. In the Web Service Invocation-Web Service Name, Port and Method window,
select the general web service information for the following items: Web
Services, Web Service Port Type, and Web Service Method. Click Next.
6. In the Web Services Invocation - Web Service Method parameters window,
enter the parameters that are required by the target web service method. Click
Next.
7. Optional: In the Web Service Invocation-Web Service EndPoint window, you
can edit the URL or Path to WSDL by selecting the edit check box. To enable
web service security, select the Enable web service security service check box.
Select one of the following authentication types:
v HTTP user name authentication
v SOAP message user name authentication
Add the User name and Password. Click Next.
8. The Web Service Invocation-Summary and Finish window is displayed. It
shows the name of the policy. Click Finish to create the policy.
Creating policies by using policy editor
You can use the policy editor to develop policies.
Procedure
1. Get the latest WSDL file which must match your target web service.
2. Determine the endpoint of your target running web service.
3. Run the $NCHOME/impact/bin/nci_compilewsdl script to compile the target
WSDL file. Always place the output JAR file to $NCHOME/wslib directory.
Otherwise, Netcool/Impact is not able to find the JAR file at run time.
4. Use policy editor to write your policy to make web services calls.
56
Netcool/Impact: DSA Reference Guide
5. Run the policy that you created.
Integrating with third-party web services
Sometimes in the development phase you must change your wsdl file and reuse
Netcool/Impact web services wizard for testing purposes. Because JVM caches the
loaded classes, the wizard cannot recognize the latest changes. Use this procedure
to clear the cache.
Procedure
1. Stop the Impact Server.
2. Remove the old JAR file from the $NCHOME/wslib directory.
3. Start the Impact Server.
4. Run the nci_compilewsdl script from IMPACT_HOME/bin to generate the new JAR
file in the wslib directory or alternatively run the web services wizard to
generate a new JAR file and a new policy.
Chapter 5. Working with the web services DSA
57
58
Netcool/Impact: DSA Reference Guide
Chapter 6. Web services security
Web service DSA has limited support to Web services security standard defined by
Oasis-Open. The following security features are supported:
v User name token authentication
v User name token authentication with a plain text password
v Message integrity and non-repudiation with signature
v Encryption
v Sign and encrypt messages
Enabling web services security
Use the following method to enable web message level web services security. You
can enable HTTP basic authentication (transport level security) by adding optional
properties into the policy.
Procedure
1. Stop all the Impact Servers in the cluster.
2. Complete the following steps for the primary Impact Server. These changes are
replicated to the secondary servers in the cluster.
a. Update the $NCHOME/dsa/wsdsa/wss/conf/wss.xml file in your Tivoli
Netcool/Impact installation directory to set up security features that are
required by your web service calls. For most cases, you must update two
related XML elements, which are OutflowSecurity and possibly
InflowSecurity in your wss.xml file.
b. Update the $NCHOME/dsa/wsdsa/wss/conf/wscb.properties file to set up user
ID and password that is required by particular security features. For
example, UsernameToken or Signature. This file has the following format:
num=2
uid.1=client
pwd.1=apache
uid.2=service
pwd.2=apache
where num property defines how many user names and password pairs are
included in the file. uid.1 defines the user name for the first pair, while
pwd.1 is the password for the first pair. The same scheme applies to the
consecutive pairs.
3. Complete the following step for each Impact Server in the cluster:
a. If security features such as signature or encryption are required by web
service calls, a signature property file or encryption property file is needed
on impact Java class path. Place property files in the jar that is compiled for
the web service, for details see the next topic Creating a web service policy
using web service security. The following is an example property file that is
called client.properties. You must enter each line of code on a separate
line.
org.apache.ws.security.crypto.provider=
org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=apache
org.apache.ws.security.crypto.merlin.file=client.jks
© Copyright IBM Corp. 2006, 2015
59
This property file includes information about your keystore file that
contains public and private keys that are used for signature or encryption.
Except the first entry in the file, you must update the next three entries to
reflect information about your own keystore file.
4. Start the primary Impact Server. Ensure that it starts and initializes successfully.
5. To enable the web services security feature in web services DSA, add the
following optional properties to the policy.
callProps = NewObject();
callProps.EnableWSS = true;
callProps.WSSRepository= "/tmp/dsa/wsdsa/wss";
callProps.WSSConfigFile = "/tmp/dsa/wsdsa/wss/conf/wss.xml";
6. The supporting security feature, WSInvokeDL() function is started with an
additional callProps object:
result = WSInvokeDL("Sample07", endpoint, "echo", params, callProps)
7. Start the remaining, secondary Impact Servers.
Results
The preceding steps enable message level security. You can enable HTTP basic
authentication (transport level security) by adding the following optional
properties into the policy you develop:
callProps=NewObject();
callProps.Username="myName";
callProps.Password="myPassword";
WSInvokeDL(....,paramArray, callProps);
Creating a web service policy using web service security
This example shows how to set up a stand-alone Apache Axis2 rampart server
with an Netcool/Impact policy to enable Web Service Security.
Before you begin
For information about the Apache Axis2 Rampart security module, see the
following URL. http://axis.apache.org/axis2/java/rampart/
Tip: If you are using another Web Service Security Server, make sure to use the
client properties and .jks files of the server. Client.properties and client.jks
files are used in Step 2 of the example.
v Java SDK or JRE 1.6 and above is required. You can use Impact SDK if you are
installing the example in the same system where Netcool/Impact is installed:
IMPACT_HOME/sdk/bin
v Ant 1.8 or above is required. You can use the Netcool/Impact Ant package
IMPACT_HOME/ant
v Make sure that the Java and Ant executable files are in the system PATH
environment variable.
About this task
This example uses Apache Axis2 version 1.6.2 and rampart version 1.6.2.
1. Set up Rampart as a stand-alone server.
a. Download Axis2 from the following URL. http://axis.apache.org/axis2/
java/core/download.cgi
60
Netcool/Impact: DSA Reference Guide
b. Download the Rampart from the following URL: http://axis.apache.org/
axis2/java/rampart/download.html
c. Unpack the files that you downloaded in the previous two steps and set the
following environment variables:
v AXIS2_HOME=<where axis2 package downloaded and unpacked>
v RAMPART_HOME=<where rampart package downloaded and unpacked>
d. Copy all the JAR files from RAMPART_HOME\lib to AXIS2_HOME\lib cp –rf
RAMPART_HOME\lib\* AXIS2_HOME\lib\.
Remember: The Rampart package is running on the Windows server and
Netcool/Impact is running on the UNIX server. Use the appropriate file
system separator according to your operating system.
e. Copy the following two MAR files to AXIS2_HOME\repository\modules.
v RAMPART_HOME\modules\ rahas-1.6.2.mar
v RAMPART_HOME\modules\rampart-1.6.2.mar.
v Use the following commands.
Copy RAMPART_HOME\modules\ rahas-1.6.2.mar
AXIS2_HOME\repository\modules\.
Copy RAMPART_HOME\modules\ rampart -1.6.2.mar
AXIS2_HOME\repository\modules\.
f. Go to the RAMPART_HOME\samples\basic directory
cd RAMPART_HOME\samples\basic directory
The directory includes several sample examples marked sample01 to
sample11. This example uses sample04. The Sample04 application echoes only
the message that you typed in the variable.
g. Run the following command to build sample04 application and start the
stand-alone server.
ant clean service.04
The command creates all the necessary files and starts a stand-alone
application for sample04. The port number is displayed in the terminal.
Buildfile: E:\opt\rampart-1.6.2\samples\basic\build.xml
clean:
[delete] Deleting directory E:\opt\rampart-1.6.2\samples\basic\build
check.dependency:
service.04:
[mkdir] Created dir:
E:\opt\rampart-1.6.2\samples\basic\build\service_repositories\sample04
[mkdir] Created dir:
E:\opt\rampart-1.6.2\samples\basic\build\service_repositories\sample04\
services
[mkdir] Created dir:
E:\opt\rampart-1.6.2\samples\basic\build\service_repositories\sample04\
modules
[copy] Copying 2 files to
E:\opt\rampart-1.6.2\samples\basic\build\service_repositories\sample04\modules
[mkdir] Created dir: E:\opt\rampart-1.6.2\samples\basic\build\temp
[mkdir] Created dir: E:\opt\rampart-1.6.2\samples\basic\build\temp\META-INF
[javac] E:\opt\rampart-1.6.2\samples\basic\build.xml:191:
warning: ’includeantruntime’ was not set,
defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 2 source files to E:\opt\rampart-1.6.2\samples\basic\build\temp
[copy] Copying 1 file to E:\opt\rampart-1.6.2\samples\basic\build\temp\META-INF
[copy] Copying 1 file to E:\opt\rampart-1.6.2\samples\basic\build\temp
[copy] Copying 1 file to E:\opt\rampart-1.6.2\samples\basic\build\temp
[jar] Building jar:
E:\opt\rampart-1.6.2\samples\basic\build\service_repositories\
sample04\services\sample04.aar
[delete] Deleting directory E:\opt\rampart-1.6.2\samples\basic\build\temp
[java] [SimpleHTTPServer] Starting
[java] [SimpleHTTPServer] Using the Axis2 Repository
E:\opt\rampart-1.6.2\samples\basic\build\service_repositories\sample04
[java] [SimpleHTTPServer] Listening on port 8080
[java] [INFO] Deploying module: addressing-1.6.2 - file:
/E:/opt/rampart-1.6.2/samples/basic/build/service_repositories/sample04/modules
Chapter 6. Web services security
61
/addressing-1.6.2.mar
[java] [INFO] Deploying module: rampart-1.6.2 - file:
/E:/opt/rampart-1.6.2/samples/basic/build/service_repositories/sample04/modules/ra
mpart-1.6.2.mar
[java] [INFO] Deploying Web service: sample04.aar - file:
/E:/opt/rampart-1.6.2/samples/basic/build/service_repositories/sample04/servic
es/sample04.aar
[java] [INFO] Listening on port 8080
[java] [SimpleHTTPServer] Started
The example shows that the server is running on port 8080 and no warning
or errors occur.
h. Verify the application by going to http://server:8080/axis2/services and
view the following output.
Deployed services
sample04
Available operations
echo
Click the sample04 link to view the WSDL file. The full link to the WSDL
file is http://server:8080/axis2/services/sample04?wsdl.
Now that service is up and running, the next step is to create a policy and
setup Netcool/Impact.
2. Create a Netcool/Impact policy and configure Web Service Security.
a. Create a policy with the policy wizard in the usual way. The WSDL file is
http://server:8080/axis2/services/sample04?wsdl and name of the JAR
file is sample04.
Remember: When the wizard prompts for end point and security, make
sure to enable the security. Select the following option SOAP message user
name authentication so you do not have to enter a user name and
password.
b. The wizard creates the policy with the following parameters:
//Enable web service security
callProps = NewObject();
callProps.EnableWSS = true;
callProps.WSSRepository= "/opt//IBM/tivoli/Impact71/dsa/wsdsa/wss";
callProps.WSSConfigFile = "/opt/ /IBM/tivoli/Impact71/dsa/wsdsa/wss/conf/Sample04_wss.xml";
c.
d.
e.
f.
62
Tip: The path to the file can vary if you have a different Netcool/Impact
installation location.
The xml file /opt/ /IBM/tivoli/Impact71/dsa/wsdsa/wss/conf/
Sample04_wss.xml is created as template.
For example, if you need to add a statement to update the InFlowSecurity
and OutFlowSecurity parameters actions to match application
implementation. See the application services.xml file in the
$RAMPART_HOME/samples/basic/<sample directory> directory for details.
If you are using a different web service server, you need to update the files
accordingly. A full working xml file for this example is located at the end of
this section see Example of Sample04_wss.xml. Make sure to overwrite the
existing template with the updated file.
Update the file /opt/ /IBM/tivoli/Impact71/dsa/wsdsa/wss/conf/
wscb.properties to num=1 uid.1=client pwd.1=apache
Copy or FTP client.properties and client.jks from RAMPART_HOME\
samples\keys to the IMPACT_HOME\wslib directory.
The wizard creates a JAR file in IMPACT_HOME/wslib/sample04.jar. Update
the JAR file with client.properties and client.jks by using the following
command:
Netcool/Impact: DSA Reference Guide
IMPACT_HOME/sdk/bin/jar –uf sample04.jar IMPACT_HOME/wslib/ client.*
To verify that the JAR file was updated:
IMPACT_HOME\sdk\bin\jar –tf sample04.jar |grep
client to display the content of the JAR file.
g. Move the client.properties and client.jks from the wslib directory
h. Restart Netcool/Impact.
i. Run the policy that you created with the policy wizard.
Results
The following results are displayed.
Parser log: Web Service call echo return result:
<ns:echoResponse xmlns:ns="http://sample04.samples.rampart.apache.org"
xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<ns:return>Hello from Impact 7 Server</ns:return>
</ns:echoResponse
Example of Sample04_wss.xml
A working example of the Sample04_wss.xml template.
Example
<?xml version="1.0" encoding="UTF-8"?>
<!-- *************************************************** {COPYRIGHT-TOP-RM} ***
* Licensed Materials - Property of IBM
* "Restricted Materials of IBM"
* 5724-S43
*
* (C) Copyright IBM Corporation 2006, 2011. All Rights Reserved.
*
* US Government Users Restricted Rights - Use, duplication, or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
** this is a new on:
******************************************************** {COPYRIGHT-END-RM} -->
<!--This file is used by automation. Edit at your own risk--><axisconfig name="AxisJava2.0">
<module ref="rampart"/>
<parameter name="OutflowSecurity">
<action>
<items>Timestamp Signature</items>
<user>client</user>
<signaturePropFile>client.properties</signaturePropFile>
<passwordCallbackClass>com.micromuse.common.util.WSPWCBHandler</passwordCallbackClass>
<signatureKeyIdentifier>DirectReference</signatureKeyIdentifier>
</action>
</parameter>
<parameter name="InflowSecurity">
<action>
<items>Timestamp Signature</items>
<signaturePropFile>client.properties</signaturePropFile>
</action>
</parameter>
<transportSender class="org.apache.axis2.transport.http.CommonsHTTPTransportSender" name="http">
<parameter locked="false" name="PROTOCOL">HTTP/1.1</parameter>
<parameter locked="false" name="Transfer-Encoding">chunked</parameter>
</transportSender>
<phaseOrder type="InFlow">
<phase name="Transport">
<handler class="org.apache.axis2.engine.RequestURIBasedDispatcher"
name="RequestURIBasedDispatcher">
<order phase="Transport"/>
</handler>
<handler class="org.apache.axis2.engine.SOAPActionBasedDispatcher"
name="SOAPActionBasedDispatcher">
<order phase="Transport"/>
Chapter 6. Web services security
63
</handler>
</phase>
<phase name="Security"/>
<phase name="PreDispatch"/>
<phase class="org.apache.axis2.engine.DispatchPhase" name="Dispatch">
<handler class="org.apache.axis2.engine.AddressingBasedDispatcher"
name="AddressingBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"
name="SOAPMessageBodyBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler class="org.apache.axis2.engine.InstanceDispatcher" name="InstanceDispatcher">
<order phase="Dispatch"/>
</handler>
</phase>
<phase name="OperationInPhase"/>
</phaseOrder>
<phaseOrder type="OutFlow">
<phase name="OperationOutPhase"/>
<phase name="PolicyDetermination"/>
<phase name="MessageOut"/>
<phase name="Security"/>
</phaseOrder>
<phaseOrder type="InFaultFlow">
<phase name="PreDispatch"/>
<phase class="org.apache.axis2.engine.DispatchPhase" name="Dispatch">
<handler class="org.apache.axis2.engine.RequestURIBasedDispatcher"
name="RequestURIBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler class="org.apache.axis2.engine.SOAPActionBasedDispatcher"
name="SOAPActionBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler class="org.apache.axis2.engine.AddressingBasedDispatcher"
name="AddressingBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"
name="SOAPMessageBodyBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler class="org.apache.axis2.engine.InstanceDispatcher" name="InstanceDispatcher">
<order phase="Dispatch"/>
</handler>
</phase>
<!-user can add his own phases to this area -->
<phase name="OperationInFaultPhase"/>
</phaseOrder>
<phaseOrder type="OutFaultFlow">
<!-user can add his own phases to this area -->
<phase name="OperationOutFaultPhase"/>
<phase name="PolicyDetermination"/>
<phase name="MessageOut"/>
</phaseOrder>
</axisconfig>
User name token authentication
Authentication uses a security token to validate the user and determine whether a
client is valid in a particular context. User name tokens are used to validate user
names and passwords.
Procedure
Update the $NCHOME/dsa/wsdsa/wss/conf/wss.xml parameters in the following way:
<parameter name="OutflowSecurity"
<action>
<items>UsernameToken Timestamp</items>
64
Netcool/Impact: DSA Reference Guide
,user>bob</user>
<passwordCallbackClass>com.micromuse.common.util.WSPWCBHandler
</passwordCallbackClass>
</action>
<parameter>
In the corresponding wscb.properties file, the parameter values are like:
num=1
uid.1=bob
pwd.1=bobPassword
User name token authentication with a plain text password
Authentication uses a security token to validate the user and determine whether a
client is valid in a particular context. User name tokens are used to validate user
names and passwords.
Procedure
Update the $NCHOME/dsa/wsdsa/wss/conf/wss.xml parameters:
<parameter name="OutflowSecurity">
<action>
<items>UsernameToken</items>
<user>bob</user>
<passwordCallbackClass>com.micromuse.common.util.WSPWCBHandler
</passwordCallbackClass>
</action>
<parameter>
In the corresponding wscb.properties file, the parameter values are like:
num=1
uid.1=bob
pwd.1=bobPassword
Message integrity and non-repudiation with signature
Procedure
In the $NCHOME/dsa/wsdsa/wss/conf/wss.xml file, make sure the OutflowSecurity
and InflowSecurity are set in the following way:
<parameter name="OutflowSecurity">
<action>
<items>Timestamp Signature</items>
<user>client</user>
<signaturePropFile>client.properties</signaturePropFile>
<passwordCallbackClass>com.micromuse.common.util.WSPWCBHandler
</passwordCallbackClass>
<signatureKeyIdentifier>DirectReference</signatureKeyIdentifier>
</action>
<parameter>
<parameter name="InflowSecurity">
<action>
<items>Timestamp Signature</items>
<signaturePropFile>client.properties</signaturePropFile>
</action>
<parameter>
The <user>client</user> expression here denotes the outgoing Web services calls,
which will be signed by the private key of user client.
In the corresponding wscb.properties file, the parameter values are like:
Chapter 6. Web services security
65
num=1
uid.1=client
pwd.1=apache
Encryption
Procedure
In the $NCHOME/dsa/wsdsa/wss/conf/wss.xml file, make sure the OutflowSecurity
and InflowSecurity are set in the following way:
<parameter name="OutflowSecurity">
<action>
<items>Encrypt</items>
<encryptionUser>service</EncryptionUser>
<encryptionPropFile>client.properties</encryptionPropFile>
</action>
</parameter>
<parameter name="InflowSecurity">
<action>
<items>Encrypt</items>
<passwordCallbackClass>com.micromuse.common.util.WSPWCBHandler</passwordCallbackClass>
<decryptionPropFile>client.properties</decryptionPropFile>
</action>
</parameter>
The <user>client</user> expression here denotes the outgoing Web services calls,
which will be signed by the private key of user client.
In the corresponding wscb.properties file, the parameter values are like:
num=1
uid.1=service
pwd.1=apache
All outbound Web service calls will be encrypted by the public key entry with
alias service. The keystore file, as described in client.properties file, should
contain the public key entry for alias service. For example, you can get the public
key of service as X.509 certificate and import the certificate into your own
keystore.
Sign and encrypt messages
Procedure
The security configuration files needs to be added to the $NCHOME/dsa/wsdsa/wss/
conf/ directory. The wss.xml file is provided and uses a built-in Impact class to
handle the user name and password, $NCHOME/dsa/wsdsa/wss/conf/wss.xml.
Important: Your configuration file should have its own security configuration if
needed, see the following example:
<parameter name="OutflowSecurity">
<action>
<items>Timestamp Signature Encrypt</items>
<user>client</user>
<passwordCallbackClass>com.micromuse.common.util.WSPWCBHandler
</passwordCallbackClass>
<signaturePropFile>client.properties</signaturePropFile>
<signatureKeyIdentifier>DirectReference</signatureKeyIdentifier>
<encryptionKeyIdentifier>SKIKeyIdentifier</encryptionKeyIdentifier>
<encryptionUser>service</encryptionUser>
</action>
</parameter>
66
Netcool/Impact: DSA Reference Guide
<parameter name="InflowSecurity">
<action>
<items>Timestamp Signature Encrypt</items>
<passwordCallbackClass>
com.micromuse.common.util.WSPWCBHandler
</passwordCallbackClass>
<signaturePropFile>client.properties</signaturePropFile>
</action>
</parameter>
In the corresponding wscb.properties file, the parameter values are like:
num=2
uid.1=service
pwd.1=apache
uid.2=client
pwd.2=apache
Chapter 6. Web services security
67
68
Netcool/Impact: DSA Reference Guide
Chapter 7. Working with the JMS DSA
You can use the Java Message Service (JMS) data source adapter (DSA) to send and
receive JMS messages from within a policy.
The JMS DSA is installed automatically when you install Netcool/Impact.
For detailed information about connecting WebSphere MQ and JMS DSA, see
“Connecting to WebSphere MQ and JMS DSA” on page 81.
Supported JMS providers
Before you can use the Java Message Service (JMS) data source adapter (DSA) to
send and retrieve JMS messages, you must obtain the correct set of JMS client
libraries.
The JMS client libraries are third-party software components that provide the
function that is required to connect to the JMS and JNDI providers in your
environment. These libraries are Java JAR files that are distributed with each JMS
application. The JMS DSA is compatible with JMS providers that fully support the
JMS 1.1 specification.
For more information about JMS 1.1, see the Oracle Java website at
http://www.oracle.com/technetwork/java/docs-136352.html. Some supported JMS
providers include OpenJMS 0.7.7; BEA WebLogic 8.1; Oracle Java System
Application Server 8 and later; and WebSphere MQ. For information about
connecting WebSphere MQ to a JMS DSA, see “Connecting to WebSphere MQ and
JMS DSA” on page 81.
Configuring JMS DSAs to send and receive JMS messages
You must complete the configuration steps before you can use the Java Message
Service (JMS) data source adapter (DSA) to send and retrieve JMS messages.
Procedure
1. Obtain and install the required JMS client libraries.
2. Copy the client JAR files from the JMS client installation directory to the
$NCHOME/dsalib directory.
3. Restart the Impact Server.
4. Create a JMS data source, and configure it for the JMS source.
For more information about creating a JMS data source, see “JMS data source”
on page 70.
5. Handle the incoming JMS messages.
You can handle the incoming JMS messages by using any of these approaches:
v Write JMS policies that use the JMS data source, and the JMS functions.
For more information, see “Writing JMS DSA policies” on page 74.
v Configure the JMSListener service to send JMS events to a policy.
© Copyright IBM Corp. 2006, 2015
69
If you use the JMSListener to send JMS messages to your policy, you do not
have to use the ReceiveJMSMessage function to receive them. For more
information, see “Handling incoming messages from a JMS message listener”
on page 80.
Setting up OpenJMS as the JMS provider
You can set up OpenJMS as the Java Message Service (JMS) provider for
Netcool/Impact.
Procedure
1. Obtain the OpenJMS libraries from the OpenJMS website http://
openjms.sourceforge.net/.
2. To install OpenJMS, follow the procedure in the getting started information that
is available on the OpenJMS website.
3. Copy the OpenJMS client JAR files to the $NCHOME/dsalib directory.
You can find the OpenJMS client JAR files in the lib subdirectory in the
OpenJMS installation directory.
4. Restart the Impact Server.
5. To start the OpenJMS server, use the startup script that is in the bin
subdirectory in the OpenJMS installation directory.
6. Create a JMS data source, and configure it for OpenJMS.
For more information, see “JMS data source”
JMS data source
A Java Message Service (JMS) data source abstracts the information that is required
to connect to a JMS Implementation.
This data source is used by the JMSMessageListener service, the SendJMSMessage,
and ReceiveJMSMessage functions.
JMS data source configuration properties
You can configure the properties for the Java Message Service (JMS) data source.
Table 22. General settings for the JMS data source window
70
Window element
Description
Data Source Name
Enter a unique name to identify the data
source. You can use only letters, numbers,
and the underscore character in the data
source name. If you use UTF-8 characters,
make sure that the locale on the Impact
Server where the data source is saved is set
to the UTF-8 character encoding.
Netcool/Impact: DSA Reference Guide
Table 23. Source settings for the JMS data source window
Window element
Description
JNDI Factory Initial
Enter the name of the JNDI initial context
factory. The JNDI initial context factory is a
Java object that is managed by the JNDI
provider in your environment. The JNDI
provider is the component that manages the
connections and destinations for JMS.
OpenJMS, BEA WebLogic, and Sun Java
Application Server distribute a JNDI
provider as part of their JMS
implementations. The required value for this
field varies by JMS implementation. For
OpenJMS, the value of the property is
org.exolab.jms.jndi.
InitialContextFactory
For other JMS implementations, see the
related product documentation.
JNDI Provider URL
Enter the JNDI provider URL. The JNDI
provider URL is the network location of the
JNDI provider. The required value for this
field varies by JMS implementation. For
OpenJMS, the default value of this property
is tcp://hostname:3035, where host name is
the name of the system on which OpenJMS
is running. The network protocol TCP or
RMI, must be specified in the URL string.
For other JMS implementations, see the
related product documentation.
JNDI URL Packages
Enter the Java package prefix for the JNDI
context factory class. For OpenJMS, BEA
WebLogic, and Sun Java Application Server,
you are not required to enter a value in this
field.
JMS Connection Factory Name
Enter the name of the JMS connection
factory object. The JMS connection factory
object is a Java object that is responsible for
creating new connections to the messaging
system. The connection factory is a managed
object that is administered by the JMS
provider. For example, if the provider is
BEA WebLogic, the connection factory object
is defined, instantiated, and controlled by
that application. For the name of the
connection factory object for your JMS
implementation, see the related product
documentation.
JMS Destination Name
Enter the name of a JMS topic or queue,
which is the name of the remote topic or
queue where the JMS message listener
listens for new messages.
Chapter 7. Working with the JMS DSA
71
Table 23. Source settings for the JMS data source window (continued)
Window element
Description
JMS Connection User Name
Enter a JMS user name. If the JMS provider
requires a user name to listen to remote
destinations for messages, enter the user
name in this field. JMS user accounts are
controlled by the JMS provider.
JMS Connection Password
If the JMS provider requires a password to
listen to remote destinations for messages,
enter the password in this field.
Test Connection
Test the connection to the JMS
Implementation. If the test is successful, the
system shows the following message:
JMS: Connection OK
Specifying more JNDI properties for the JMS data source
You can specify more Java Naming and Directory Interface (JNDI) properties by
editing the Java Message Service (JMS) data source.
Procedure
1. Open the JMS data source for editing in a text editor of your choice. You can
find all data sources in the $IMPACT_HOME/etc/ directory. The data source file
name is <servername>_<datasourceName>.ds. <servername> is the name of the
Impact Server instance, and <datasourceName> is the name of your JMS data
source as displayed in the data source editor in GUI.
2. Add your JNDI properties in the following format:
<datasourceName>.JMS.DSPROPERTY.#.NAME=<property>
<datasourceName>.JMS.DSPROPERTY.#.VALUE=<property value>
# is the property number in a sequence of properties, the starting number is 1,
for example:
<datasourceName>.JMS.DSPROPERTY.1.NAME=java.naming.factory.initial
<datasourceName>.JMS.DSPROPERTY.1.VALUE=org.exolab.jms.jndi.
InitialContextFactory
<datasourceName>.JMS.DSPROPERTY.2.NAME=java.naming.provider.url
<datasourceName>.JMS.DSPROPERTY.2.VALUE=tcp://jndi_host:3035
<datasourceName>.JMS.DSPROPERTY.3.NAME=java.naming.security.principal
<datasourceName>.JMS.DSPROPERTY.3.VALUE=User1
<datasourceName>.JMS.DSPROPERTY.4.NAME=java.naming.security.credentials
<datasourceName>.JMS.DSPROPERTY.4.VALUE=password
<datasourceName>.JMS.NUMDSPROPERTIES=4
The <datasourceName>.JMS.NUMDSPROPERTIES=<number of properties> property
specifies the number of more properties, 4 in the previous example.
Note: Use the $IMPACT_HOME/bin/nci_crypt utility to encrypt the value of the
java.naming.security.credentials property.
3. Save the changes in the data source, and restart the Impact Server to apply the
changes.
JMS message listener
The Java Message Service (JMS) message listener service runs a policy in response
to incoming messages that are sent by external JMS message providers.
72
Netcool/Impact: DSA Reference Guide
The message provider can be any other system or application that can send JMS
messages. Each JMS message listener listens to a single JMS topic or queue. There
is one default JMS message listener named JMSMessageListener. You can create as
many listener services as you need, each of which listens to a different topic or
queue.
A JMS message listener is only required when you want Netcool/Impact to listen
passively for incoming messages that originate with JMS message producers in
your environment. You can actively send and retrieve messages from within a
policy without using a JMS message listener.
JMS message listener service configuration properties
You can configure the properties for the Java Message Service (JMS) listener
service.
Table 24. JMSMessageListener Service configuration window
Window element
Description
Service name
Enter a unique name to identify the service.
Policy To Execute
Select the policy that you created to run in response to
incoming messages from the JMS service.
JMS Data Source
JMS data source to use with the service.
You need an existing and valid JMS data source for the
JMS Message Listener service to establish a connection
with the JMS implementation and to receive messages.
For more information about creating JMS data sources,
see “JMS data source configuration properties” on page
70.
Message Selector
The message selector is a filter string that defines which
messages cause Netcool/Impact to run the policy
specified in the service configuration. You must use the
JMS message selector syntax to specify this string.
Message selector strings are similar in syntax to the
contents of an SQL WHERE clause, where message
properties replace the field names that you might use in
an SQL statement.
The content of the message selector depends on the types
and content of messages that you anticipate receiving
with the JMS message listener. For more information
about message selectors, see the JMS specification or the
documentation distributed with your JMS
implementation. The message selector is an optional
property.
Durable Subscription: Enable
You can configure the JMS message listener service to use
durable subscriptions for topics that allow the service to
receive messages when it does not have an active
connection to the JMS implementation. A durable
subscription can have only one active subscriber at a
time. Only a JMS topic can have durable subscriptions.
Client ID
Client ID for durable subscription. It defines the client
identifier value for the connection. It must be unique in
the JMS Implementation.
Chapter 7. Working with the JMS DSA
73
Table 24. JMSMessageListener Service configuration window (continued)
Window element
Description
Subscription Name
Subscription Name for durable subscription. Uniquely
identifies the subscription made from the JMS message
listener to the JMS Implementation. If this property is not
set, the name of JMS DSA listener service itself is used as
its durable subscription name, which is
JMSMessageListener by default.
Clear Queue
Clear the message waiting in the JMSMessageListener
queue that has not yet been picked by the EventProcessor
service. It is recommended not to do this while the
Service is running.
Starts automatically when
server starts
Select to automatically start the service when the server
starts. You can also start and stop the service from the
GUI.
Service log (Write to file)
Select to write log information to a file.
Writing JMS DSA policies
Java Message Service (JMS) policies send or retrieve JMS messages.
JMS policies use the SendJMSMessage and ReceiveJMSMessage functions, or work
with the JMS message listener service.
In a policy, you use the JMS DSA to perform the following tasks:
v Send messages to a JMS topic or queue
v Retrieve messages from a JMS topic
v Queue or handle incoming messages from a JMS message listener
Sending messages to a JMS topic or queue
You can send messages to a Java Message Service (JMS) topic or queue from
within a policy.
Procedure
1. Create and configure a JMS data source
For more information, see “JMS data source” on page 70.
2. Create a message properties context.
For more information, see “Message properties context” on page 75.
3. Create a message body string or context.
For more information, see “Creating a message body string or context” on page
76.
4. Call the SendJMSMessage function and pass the values the JMS data source, the
message properties context, and the specified message body as runtime
parameters.
For more information about the syntax of the SendJMSMessage function, see
“SendJMSMessage.”
SendJMSMessage
The SendJMSMessage function sends a message to the specified destination by
using the Java Message Service (JMS) DSA.
74
Netcool/Impact: DSA Reference Guide
To send the message, you call the SendJMSMessage function and pass the JMS data
source, a message properties context, and the message body as input parameters.
Syntax
The SendJMSMessage function has the following syntax:
SendJMSMessage(DataSource, MethodCallProperties, Message)
Parameters
The SendJMSMessage function has the following parameters.
Table 25. SendJMSMessage function parameters
Parameter
Format
Description
DataSource
String
Valid, and existing JMS data source.
MethodCallProperties
Context
Context that contains message header, and
other JMS properties for the message.
Custom message properties are supported.
Message
String | Context
String or context that contains the body of
the message.
Message properties context
The message properties context specifies runtime parameters for the underlying
Java Message Service (JMS) client method call that retrieves the message when you
call the ReceiveJMSMessage function.
You pass this context as a runtime parameter when you call the SendJMSMessage
function in a policy. This message properties context specifies the message header,
custom message properties, and the message selector. The table shows the valid
JMS message header values.
Table 26. JMS Message Header Values
Property
Description
DeliveryMode
Optional. Specifies the JMS delivery mode for the
method. Possible values are 1 for non-persistent and 2 for
persistent.
DisableMessageId
Optional. Specifies whether JMS message IDs are
disabled.
DisableMessageTimeStamp
Optional. Specifies whether JMS message time stamps are
disabled.
JMSCorrelationID
Optional. Specifies a JMS correlation ID for the message.
JMSCorrelationIDAsBytes
Optional. Specifies a JMS correlation ID for the message
as an array of bytes.
JMSDeliveryMode
Optional. Specifies a JMS delivery mode. Possible values
are 0 for persistent mode and 1 for non-persistent mode.
JMSDestination
Optional. Specifies a destination for the message in the
form of a JMS-administered object.
JMSExpiration
Optional. Specifies an expiration value in milliseconds for
the message. If not specified, value is set by the JMS
provider.
JMSMessageID
Optional. Specifies a JMS message ID for the message.
Chapter 7. Working with the JMS DSA
75
Table 26. JMS Message Header Values (continued)
Property
Description
JMSPriority
Optional. Specifies a JMS priority level for the message.
JMS supports priority levels from 0 to 9, with 9 as the
highest.
JMSRedelivered
Optional. Specifies whether the message is being
redelivered. Possible values are True or False.
JMSReplyTo
Optional. Specifies the name of a JMS destination where
replies to this message are sent.
JMSTimeStamp
Optional. Specifies a time stamp for the message in
seconds since the beginning of the UNIX epoch. If not
specified, the value is set by the JMS provider.
JMSType
Optional. Specifies a JMS message type for the message.
Some JMS implementations use a message repository to
store defined types of messages. You can use this header
value to associate a particular message with a message
type.
Priority
Same as JMSPriority.
TimeToLive
Optional. Specifies the length of time that a message is
retained by the JMS delivery system before it expires. The
default value is 0, which indicates an unlimited message
lifetime.
For more information about the JMS message header, see the documentation that
was provided with your JMS application.
Optionally, you can also specify custom message properties. These properties are
user-defined and can contain any value. Generally, these properties are used to
send meta information about messages that is not otherwise described in the
message header.
The following example shows how to create and populate a message properties
context:
// Call NewObject to create the new context
MsgProps = NewObject();
// Assign message header values as member variables
MsgProps.TimeToLive = 0;
MsgProps.Priority = 5;
MsgProps.DeliveryMode = "PERSISTENT";
MsgProps.ReplyTo = "jms/Topic";
// Assign custom message properties as member variables
MsgProps.Custom1 = "First custom property";
MsgProps.Custom2 = "Second custom property";
Creating a message body string or context
You specify the message body by using a string value or a context, depending on
whether you want to send a text message or a map message.
To specify the body of a text message, you use a string assignment statement in the
policy. When you call SendJMSMessage, you pass this string to the function as a
runtime parameter. This example shows how to assign the body of a text message
to a string:
MsgTextBody = "Body content of text message";
76
Netcool/Impact: DSA Reference Guide
To specify the body of a map message, you create a context by using the
NewObject function. You assign one member variable for each name-value pair in
the map, where the name of the variable corresponds to the name for the pair.
When you call SendJMSMessage, you pass this context to the function as a runtime
parameter.
This example shows how to create a message body context for a map message. In
this example, the names of values in the map are name, location, and email.
MsgMapBody = NewObject();
MsgMapBody.name = "John Smith";
MsgMapBody.location = "New York City";
MsgMapBody.email = "jsmith@example.com";
Example of sending a map message to a JMS destination
The following example shows how to send a map message to a Java Message
Service (JMS) destination by using the SendJMSMessage function.
// Set JMSDataSource to a valid and existing JMSDataSource in Impact.
// The destination where the message is sent is obtained from the JMSDataSource.
JMSDataSource = “JMSDS1”;
// Create a message properties object and populate its
// member variables with message header properties and custom properties
MsgProps = NewObject();
MsgProps.TimeToLive = 0;
MsgProps.color = "green";
MsgProps.Expiration = 2000;
MsgProps.DeliveryMode = "PERSISTENT";
MsgProps.ReplyTo="queue2";
// Specify custom message properties
MsgProps.Custom1 = "Value 1";
MsgProps.Custom2 = "Value 2";
// Create a map message content and populate its member
// variables where each variable and value represent a name/
// value pair for the resulting map
MsgMapBody = NewObject();
MsgMapBody.name = "sanjay";
MsgMapBody.location = "New York City";
MsgMapBody.facility = "Wall St.";
// Call SendJMSMessage and pass the JNDI properties
// context, the message properties context, the message
// map context and other parameters
SendJMSMessage(JMSDataSource, MsgProps, MsgMapBody);
Example of sending a text message to a JMS destination
This example shows how to send a text message to a Java Message Service (JMS)
destination by using the SendJMSMessage function.
// Set JMSDataSource to a valid and existing JMSDataSource in Impact.
// The destination where the message is sent is obtained from the JMSDataSource.
JMSDataSource = “JMSDS1”;
// Create a message properties object and populate its
// member variables with message header properties and custom properties
MsgProps = NewObject();
MsgProps.TimeToLive = 0;
MsgProps.color = "green";
MsgProps.Expiration = 2000;
MsgProps.DeliveryMode = "PERSISTENT";
MsgProps.ReplyTo="queue2";
Chapter 7. Working with the JMS DSA
77
// Specify custom message properties
MsgProps.Custom1 = "Value 1";
MsgProps.Custom2 = "Value 2";
// Create a text message content
MsgTextBody = "This is the message body";
// Call SendJMSMessage and pass the JNDI properties
// context, the message properties context, the message
// map context and other parameters
SendJMSMessage(JMSDataSource, MsgProps, MsgTextBody);
Retrieving JMS messages from a topic or queue
You can retrieve messages from a Java Message Service (JMS) topic or queue from
within a policy.
Procedure
1. Create and configure a JMS data source
For more information, see “JMS data source” on page 70.
2. Create a message properties context.
For more information, see “Creating a message properties context.”
3. Call the ReceiveJMSMessage function and pass the values of the JMS data
source, and the message properties context as parameters.
For examples of the ReceiveJMSMessage function usage, see
“ReceiveJMSMessage.”
4. Handle the retrieved message
For more information, see “Handling a retrieved message” on page 79.
ReceiveJMSMessage
The ReceiveJMSMessage function retrieves a message from the specified Java
Message Service (JMS) destination.
To retrieve the message, you call this function and pass a JMS data source, and a
message properties context as input parameters.
Syntax
The ReceiveJMSMessage function has the following syntax:
ReceiveJMSMessage(DataSource, MethodCallProperties)
Parameters
The ReceiveJMSMessage function has the following parameters:
Table 27. ReceiveJMSMessage function parameters
Parameter
Format
Description
DataSource
String
Existing, and valid JMS data source.
MethodCallProperties
Context
Context that contains optional MessageSelector
and Timeout.
Creating a message properties context
The message properties context specifies connection information for the underlying
Java Message Service (JMS) client method call that retrieves the message when you
call the ReceiveJMSMessage function.
78
Netcool/Impact: DSA Reference Guide
You pass this context as a parameter when you call the ReceiveJMSMessage
function in a policy. The following table shows the properties that you can set in
the message properties context:
Table 28. Message Properties Context
Property
Description
MessageSelector
String expression that specifies which message in the topic
or queue you want to retrieve. The message selector syntax
is similar to the contents of an SQL WHERE clause and is
defined in the JMS specification.
Timeout
Specifies the length of time that a message is retained by
the JMS delivery system before it expires. Default value is
0, which indicates an unlimited message lifetime.
You can create an empty message properties context by passing the NewObject
function to the ReceiveJMSMessage as a parameter.
The following example shows how to create a message properties context.
// Call NewObject to create the next context
MsgProps = NewObject();
// Assign a message selector that filters the message to
// retrieve
MsgProps.MessageSelector = "color = ’green’ AND custom2 = ’1234543’";
Handling a retrieved message
The ReceiveJMSMessage function uses three variables to store message information
that is retrieved from a Java Message Service (JMS) topic or queue.
Table 1 shows the built-in variables that store the message information:
Table 29. Built-in Message Variables
Variable
Description
JMSMessage
JMS message body. If the message is a text message, the
value of this variable is a string. If the message is a map
message, the value of this variable is a context where each
member variable in the context corresponds to a
name-value pair in the message map.
MessageType
If the message is a text message, the value of this variable
is a string "Text". If the message is a map message, the
value of this variable is a string "Map".
JMSProperties
Custom JMS message properties that are attached to the
message.
This example shows how to handle a retrieved message:
// Call ReceiveJMSMessage and pass the JNDI properties,
// message properties and other information as runtime parameters
ReceiveJMSMessage(JMSDataSource, MsgProps);
// Print the
Log("Message
Log("Message
Log("Message
contents of the message to the policy log
type: " + MessageType);
properties: " + JMSProperties.Custom1);
properties: " + JMSProperties.Custom2);
If (MessageType == "Text") {
Chapter 7. Working with the JMS DSA
79
Log("Message body: " + JMSMessage);
} Else {
Log("Message map value 1: " + JMSMessage.MyValue1);
Log("Message map value 2: " + JMSMessage.MyValue2);
}
Handling incoming messages from a JMS message listener
When a Java Message Service (JMS) message listener receives a message from a
JMS destination, it compares the contents of the message to message selectors
specified in its configuration.
If the message matches the message selector, or if no selector is specified, the JMS
message listener puts the message in its queue. The EventProcessor service picks
up the message, and sends it to the policy as an EventContainer.
The JMS message listener uses the message variables that are used when you use
the ReceiveJMSMessage function - JMSMessage, MessageType, and JMSProperties to retrieve a policy. For more information about these variables, see “Handling a
retrieved message” on page 79. When you handle these variables as set by a JMS
message listener, you must reference them by using the @ notation in an IPL
policy, or the dot notation in a JavaScript policy, for example,
EventContainer.MessageType.
This example shows how to handle an incoming message from a JMS message
listener by using the @ notation.
// Print the
Log("Message
Log("Message
Log("Message
contents of the message to the policy log
type: " + @MessageType);
properties: " + @JMSProperties.Custom1);
properties: " + @JMSProperties.Custom2);
If (MessageType == "Text")
Log("Message body: " +
} Else {
Log("Message map value
Log("Message map value
}
{
@JMSMessage);
1: " + @JMSMessage.MyValue1);
2: " + @JMSMessage.MyValue2);
Example of receiving a map message
This example shows how to use the ReceiveJMSMessage function to receive a map
message.
The example uses the map message that was used in “Example of sending a map
message to a JMS destination” on page 77.
/// Use a existing and valid JMSDataSource
JMSDataSource = “JMSDS1”;
// Create a message properties object and populate its
// member variables with optional parameters like MessageSelector and Timeout
MsgProps = NewObject();
// MessageSelector is used for filtering incoming messages so that messages
// with properties matching the MessageSelector expression are delivered.
MsgProps.MessageSelector = "color = ’green’ AND Custom2 = ’Value 2’";
// Timeout must be
// MessageConsumer
// MessageConsumer
MsgProps.Timeout =
specified in milliseconds. This parameter specifies how long the
blocks to receive a Message. A Timeout of zero makes the
wait indefinitely to receive a message.
6000;
// Call ReceiveJMSMessage and pass the JMSDataSource and message properties
ReceiveJMSMessage(JMSDataSource, MsgProps);
80
Netcool/Impact: DSA Reference Guide
// Print the contents of the message to the policy log
Log("Message type: " +MessageType);
Log("Message prop.Custom1: " + JMSProperties.Custom1);
Log("Message prop.Custom2: " + JMSProperties.Custom2);
If (MessageType == "Text") {
Log("Message body: " + JMSMessage);
} Else {
Log("Message map.name: " + JMSMessage.name);
Log("Message map.location: " + JMSMessage.location);
}
The If (MessageType == "Text") statement also checks whether the message is a
text message, and prints the message to the log, if it is.
Connecting to WebSphere MQ and JMS DSA
Netcool/Impact can communicate with WebSphere MQ 7 through the JMS data
source.
There are two possible configuration options:
v Option 1: WebSphere MQ client and server and Netcool/Impact all on one
machine.
v Option 2: WebSphere MQ client and Netcool/Impact on one machine and
WebSphere MQ server on a separate machine.
For more information about WebSphere MQ, see http://www-03.ibm.com/
software/products/en/wmq/#.
Configuration option 1
How to configure the WebSphere MQ client and server and Netcool/Impact all on
one machine.
Procedure
1. Configure WebSphere MQ server. For information see, http://
publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp.
2. Copy the following four JAR files from MQ_HOME/java/lib to
IMPACT_HOME/dsalib.
v com.ibm.mq.jmqi.jar
v com.ibm.mqjms.jar
v com.ibm.mq.headers.jar
v fscontext.jar
v providerutil.jar
3. Restart the Impact Server so that it picks up the new JAR files.
4. The Netcool/Impact JMS DSA will have the following parameters: For more
information about configuring JMS DSA, see JMS data source configuration
properties.
v JNDI Factory initial: com.sun.jndi.fscontext.RefFSContextFactory
v JNDI Provider URL: file:/<PathToBindingDirOnMQClient> for example,
file:/C:/MQClientBindings.
v JMS Connection Factory Name as configured on the WebSphere MQ Server.
v JMS Destination Name as configured on the WebSphere MQ Server.
Chapter 7. Working with the JMS DSA
81
Configuration option 2
How to connect the WebSphere MQ client and Netcool/Impact on one machine
and WebSphere MQ server on a separate machine.
Procedure
1. Copy the following five JAR files from MQ_HOME/java/lib to
IMPACT_HOME/dsalib.
v com.ibm.mq.jmqi.jar
v com.ibm.mqjms.jar
v com.ibm.mq.headers.jar
v fscontext.jar
v providerutil.jar
v dhbcore.jar
2. Restart the Impact Server so that it picks up the new JAR files.
3. You must configure the MQSeries® server to use a file system-based JNDI
provider. WebSphere MQ then uses the local file system as a JNDI registry
when it registers the JMS resources accessed by the DSA.
4. You must use "client" mode in your connection factory on the WebSphere MQ
server to ensure that the WebSphere MQ Client communicates through tcp with
the WebSphere MQ Server. For more information see http://
publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp.
5. Ensure that you have a listener that is configured on your preferred port on the
WebSphere MQ server.
6. Create the queues and destinations that you need as specified by the
WebSphere MQ documentation. For information see, http://
publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp.
7. Copy the bindings directory, which is configured on the WebSphere MQ server,
to the local file system of the WebSphere MQ client.
8. The Netcool/Impact JMS DSA will have the following parameters: For more
information about configuring JMS DSA, see JMS data source configuration
properties.
v JNDI Factory initial: com.sun.jndi.fscontext.RefFSContextFactory
v JNDI Provider URL: file:/<PathToBindingDirOnMQClient> for example,
file:/C:/MQClientBindings.
v JMS Connection Factory Name as configured on the WebSphere MQ Server.
v JMS Destination Name as configured on the WebSphere MQ Server.
9. If there are any configuration changes on the WebSphere MQ Server, you must
repeat 7 to ensure that the WebSphere MQ Client picks up the configuration
changes.
Connecting Netcool/Impact to WebSphere Business Events
About this task
Tip: When installing Netcool/Impact and WebSphere Business Events on the same
computer, install WebSphere Business Events first and make sure it is running
before installing Netcool/Impact.
The Netcool/Impact integration with WebSphere Business Events uses this
pre-defined XML file based project Netcool_Impact_Integration in
82
Netcool/Impact: DSA Reference Guide
$IMPACT_HOME/integrations/wbe. The integration also uses a predefined connection
factory that is called ImpactTopicConnectionFactory and the following two topics:
The jms/impactTopic topic receives events from Netcool/Impact.
The jms/wbeTopic topic sends events to Netcool/Impact.
Complete the following steps to configure WebSphere Business Events. For more
information about the steps, see WebSphere Business Events documentation
http://pic.dhe.ibm.com/infocenter/wbevents/v7r0m1/index.jsp
Procedure
1. Create a connection factory called ImpactTopicConnectionFactory.
2. Create two new topics that are called jms/impactTopic and jms/wbeTopic.
3. Using the WebSphere Business Events Data Design application, load the project
XML file $IMPACT_HOME/integrations/wbe/Netcool_Impact_Integration.xml. Or
you might want to save the project XML file to the Server Store and create
Business Events to send and test events to the two topics.
Configure Netcool/Impact for WebSphere Business Events
integration
To configure Netcool/Impact for WebSphere Business Events integration you must
copy JAR files from WebSphere Business Events into Netcool/Impact.
Procedure
1. Within <WBE HOME>/WAS/runtime copy the two JAR files
com.ibm.ws.sib.client.thin.jms_<version>.jar and
com.ibm.ws.ejb.thinclient_<version>.jar, where <version> is 7.0.0 for
WebSphere Business Events version 7.0.1. Paste the two JAR files into
<IMPACT_HOME>/dsalib.
2. Within <IMPACT_HOME>/wlp/user/shared/config/features.xml, comment or
remove the following line:
<feature>wasJmsClient-1.1</feature>
3. Restart the Netcool/Impact server.
Using the WebSphere Business Events integration
Included in Netcool/Impact, in <IMPACT_HOME>/integrations/wbe, see theWBE
project that is in XML format file. The WBE project has pre-configured policies,
data sources, and a JMS listener.
Data sources
You must update the data sources with the WebSphere Business Events host name
and port details.
v The SendToWBE data source is configured to connect to the jms/impactTopic
destination topic.
v The ReceiveFromWBE data source is configured to connect to the jms/wbeTopic
destination topic.
Policies
v The WBEPolicy policy includes two library functions that are called the
SendEventToWBE function and the ParseWBEMessage function.
v The WBESend policy uses the SendEventToWBE function to accept a
Netcool/Impact object and create a JMS message. It uses the configured
Chapter 7. Working with the JMS DSA
83
SendToWBE data source to send the JMS message to WebSphere Business
Events. The JMS message, or event, consists of a few fields from the
ObjectServer:
MsgObject = NewObject();
MsgObject.Identifier=’Test Id’;
MsgObject.Node=’Test Node’;
MsgObject.AlertKey=’Key 5’;
MsgObject.AlertGroup=’Group 5’;
MsgObject.Serial=5;
MsgObject.Severity =5;
MsgObject.AdditionalField="Test";
WBEPolicy.SendEventToWBE(MsgObject);
v The WBERecieve policy is attached to the WBEJMSMessageListener listener.
The policy uses the ParseWBEMessage function to receive a JMS message, or
event, from WebSphere Business Events through the listener and converts it to a
Netcool/Impact object.
JMS Listener
The JMS listener WBEJMSMessageListener receives messages from jms/wbeTopic
and runs the WBEReceive policy.
The WBE project includes two Touchpoints that are called Netcool Impact Event
and Netcool Impact Action.
v The Netcool Impact Event listens on the jms/impactTopic destination topic for
the Netcool/Impact event over the JMS bus and create an intermediate object
called Netcool Omnibus Event.
v The Netcool Impact Action sends data to Netcool/Impact over the JMS bus
through the jms/wbeTopic destination topic.
Note: The topics and connection factory are optional. Complete the following
steps, if you want to use the existing topics and connection factory.
1. Edit the data sources in the WBE project to reflect the connection factory and
topics.
2. Using any text/XML editor, update the Netcool_Impact_Integration XML file
in IMPACT_HOME/integrations/wbe directory to replace the topics and
connection factory with the existing information.
84
Netcool/Impact: DSA Reference Guide
Chapter 8. Working with the XML DSA
The XML DSA is a data source adaptor that is used to read and to extract data
from any well-formed XML document.
XML DSA overview
The XML DSA is used to read and extract data from any XML document.
The XML DSA can read XML data from files, strings, and HTTP servers by way of
the network (XML over HTTP). The Xerces DOMParser 2.6 parser is used for the
XML DSA.
The XML DSA is installed with Netcool/Impact so you do not need to complete
any additional installation or configuration steps.
Before you can use the XML DSA, you must complete the following tasks:
v Create a set of XML data types that corresponds to the structure of the XML
document you want to read with Netcool/Impact. For more information about
creating XML data types, see “Creating XML data types” on page 87.
v Set up XML data type mappings that show the relationship between an XML
data source, an XML document, and XML data types.
v Write one or more XML DSA policies that read XML data from a file, a string or
from an HTTP server over a network.
XML documents
The DSA considers an XML document to be any well-formed set of XML data that
descends from a single root element.
This document can be in a string, a text file, or on an HTTP server.
XML DTD and XSD files
XML DTD and XSD files contain a document type description.
You must provide an XML DTD or XSD file for each type of XML document that
you want the DSA to read.
XML data types
XML data types are Netcool/Impact data types that represent XML documents and
their contents.
The DSA uses the following XML data types Super data types and Element data
types:
Super data types
Super data types represent types of XML documents. The DSA uses one data type
for each type of document that it reads.
© Copyright IBM Corp. 2006, 2015
85
A super data type contains a single data item, called the document data item. This
data item represents the instance of the document that the DSA uses. The display
name of the document data item is the same as the name of the super data type.
The document data item contains a static link to the element data item that
represents the root level element of the document.
Element data types
Element data types represent the elements in an XML document. The DSA requires
one such data type for each type of XML element.
An element data type contains one field for each attribute in the corresponding
XML element. In addition, the data type contains a field that corresponds to the
PCDATA value of the element, if any.
Element data types contain one or more data items, called element data items.
Each such data item represents an instance of the element in the document.
The hierarchical relationship between XML elements is represented at the data item
level by static links. Element data items are statically linked in such a way that
each data item contains links to other data items. The other data items represent
the child elements of the corresponding element in the XML document.
Element namespaces are a convention that is used by the DSA to show that a set of
element data types is related to a single XML document. The DSA uses element
namespaces to avoid ambiguity in cases where more than one type of XML
document that is used by the DSA has an element of the same name.
XML configuration files
XML configuration files are text files that store mapping information for XML data
types.
The DSA reads the configuration files at startup and uses the information during
run time to locate the DTD or XSD file and data source for each XML document.
For more information about XML configuration files, see “Data type mappings” on
page 88.
XML document and data type mapping
The XML DSA provides mapping between an XML document and a set of data
types.
The DSA uses the information in an XML DTD or XSD file to understand the
structure of the XML data and to map the data to the corresponding data types.
One aspect of the structure of the XML data is the hierarchical relationship
between XML elements. The DSA uses static links to map this relationship to the
XML data types. Each element data item is linked to its logical child data item by a
static link. When you read the XML data in a policy, you use the GetByLinks
function to traverse the resulting structure. You can also use the embedded linking
syntax to traverse the structure.
This example shows a partial XML document, and the linking relationship between
the corresponding element data items.
86
Netcool/Impact: DSA Reference Guide
<XML_alert id="0123456789">
<XML_head>
<XML_sender>IBM</XML_sender>
<XML_subject>Alert</XML_subject>
</XML_head>
<XML_body>
<XML_node>NodeXYZ</XML_node>
<XML_summary>Node not responding</XML_summary>
</XML_body>
</XML_alert>
This figure shows the linking relationship between the corresponding element data
items:
Figure 1. Linking relationships between corresponding element data items
Creating XML data types
You must create XML data types to represent the structure of the XML document
that you want to read with Netcool/Impact.
To create the XML data types, you run either the create DTD types script or the
create XSD types script, depending on which type of schema you are using. The
create types script creates a super data type and then reads the XML DTD or XSD
file. The create types script creates one element data type for each type of element
that is defined in the file, including the root level element. The script uses the
names of the elements in the DTD or XSD file as the names of the element data
types. If you specify an element namespace, add a prefix to the name of each
element data type. The script then uses the command-line service to insert data
types into Netcool/Impact. For more information, see “Create data types scripts”
on page 88.
You can also use the XML DSA wizard to automate creating XML data types. For
more information about XML DSA wizards, see Policy wizards in the online help.
Chapter 8. Working with the XML DSA
87
Important: If you create an XML data type in a server cluster, either by using the
wizard or the script, cluster members are updated with the new .type files. The
following configuration files are not updated:
v XmlHttpTypes
v XmlFileTypes
The $NCHOME/dsa/XmlDsa will be replicated during startup of the secondary cluster
members from the primary server. If you are using XML DSA wizard, or using the
scripts provide, the changes will replicate in real time.
Create data types scripts
The XML DSA provides two scripts that you can run from the command line to
create XML data types.
You can find these scripts in the $NCHOME/dsa/XmlDsa/bin directory. You use the
CreateDtdTypes script to create data types from an XML DTD. The script has the
following syntax:
CreateDtdTypes server_name user password dtdFile type_name namespace_prefix
You use the CreateXsdTypes script to create data types from an XML XSD. The
script has the following syntax:
CreateXsdTypes server_name user password xsdFile type_name namespace_prefix
Table 30 explains the options that are used with the scripts.
Table 30. Create data type scripts options
Option
Description
server_name
The name of the Impact Server.
user
The name of the Impact Server user.
password
The Impact Server user's password.
dtdFile
The path and file name of the XML DTD file that describes the
XML document. Relative to the $NCHOME/dsa/XmlDsa/bin directory.
xsdFile
The path and file name of the XML XSD file that describes the
XML document. Relative to the $NCHOME/dsa/XmlDsa/bin directory.
type_name
The name of the resulting super data type.
namespace_prefix
The optional prefix added to the names of element data types. This
string is not prefixed to the name of the super data type.
The CreateDtdTypes and CreateXsdTypes scripts replace any colon character in XML
element names with an underscore when you create the data types. For example, if
a DTD file contains an element named netcool:alert, the create DTD types script
creates a corresponding element data type named netcool_alert.
Important: The Impact Server must be up for these scripts to run successfully.
Here is an example of the CreateDtdTypes script usage on UNIX:
./CreateDtdTypes.sh NCI impactadmin netcool ../TOC.dtd XmlStringTOC STEST_
Data type mappings
After you create the XML data types, you must set up data type mappings.
88
Netcool/Impact: DSA Reference Guide
A data type mapping is a set of information that shows the relationship between
an XML data source, an XML document, and XML data types. The DSA uses this
information to map the contents of an XML document to the data types in
Netcool/Impact. You must set up one data type mapping for each type of XML
document you want Netcool/Impact to read.
Data type mapping information is stored in XML configuration files. The DSA uses
the following XML configuration files:
v XmlFileTypes
v XmlHttpTypes
These files are in the $NCHOME/dsa/XmlDsa directory.
Note: After you edit the data types, you must restart the Impact Server.
Setting up mappings for XML files and strings
For each XML string or file that you want the DSA to read, you must add the
mapping information to the XmlFileTypes file.
Add the following mapping information:
v Name of the super data type
v Path and file name of the corresponding XML DTD/XSD file
v Path and file name of the corresponding XML file (XML files only)
v Namespace prefix that is used for the element data types (optional)
You use the following format to specify mapping information:
XmlDsa.fileTypes.n.property=value
where n is a numeric value that identifies the mapping, property is the name of the
mapping property, and value is the value.
Table 1 shows the mapping properties in the XmlFileTypes file.
Table 31. XmlFileTypes mapping properties
Property
Description
typeName
Specifies the name of the corresponding super data type.
dtdFile
Specifies the path and file name of a corresponding XML DTD or XSD
file. The path can be an absolute path or a path relative to the $NCHOME
directory.
isXsd
Boolean variable that specifies whether the schema is defined in XSD or
DTD format. If it is not specified, the default is DTD format. If it is not
specified, the default is DTD format.
xmlFile
Specifies the path and file name of the corresponding file for XML files.
The path is relative to the $NCHOME directory. For XML strings, use the
hyphen character as a placeholder.
prefix
Specifies the namespace prefix that is used to identify the
corresponding element data types. This property is optional.
This example shows a set of mapping properties for an XML document that is
contained in a file.
Chapter 8. Working with the XML DSA
89
XmlDsa.fileTypes.1.typeName XML_file_superType
XmlDsa.fileTypes.1.dtdFile dsa/XmlDsa/file.dtd
XmlDsa.fileTypes.1.xmlFile dsa/XmlDsa/file.xml
XmlDsa.fileTypes.1.prefix XML_
This example shows a set of mapping properties for an XML document that is
contained in a string.
XmlDsa.fileTypes.2.typeName XML_string_superType
XmlDsa.fileTypes.2.dtdFile dsa/XmlDsa/string.dtd
XmlDsa.fileTypes.2.xmlFile XmlDsa.fileTypes.2.prefix XML_
Note: this example uses the hyphen character (-) for the xmlFile property.
The following example shows an expression that uses the XmlFileTOC data type
with isXsd set to true. The name space prefix is FTEST. This prefix must be added
to all data types that are a part of the XML file.
XmlDsa.fileTypes.1.typeName XmlFileTOC
XmlDsa.fileTypes.1.dtdFile dsa/XmlDsa/TOC.xsd
XmlDsa.fileTypes.1.xmlFile dsa/XmlDsa/TOC.xml
XmlDsa.fileTypes.1.prefix FTEST_
XmlDsa.fileTypes.1.isXsd true
Setting up mappings for XML over HTTP
For each XML document that you want the DSA to read over HTTP, you must add
the mapping information to the XmlHttpTypes file.
Add the following mapping information:
v Name of the super data type.
v Base URL for the HTTP server.
v User name, password, and authentication realm (optional). This information is
only required if the XML document is in a password-protected area of the HTTP
server.
v Namespace prefix that is used for the element data types (optional).
You use the following format to specify mapping:
XmlDsa.httpTypes.n.property=value
where n is a numeric value that identifies the mapping, property is the name of
the mapping property, and value is the value.
Table 1 shows the mapping properties in the XmlHttpTypes file.
Table 32. XmlHttpTypes mapping properties
90
Property
Description
typeName
Name of the corresponding super data type.
dtdFile
Path and file name of the corresponding XML DTD file. Can be an
absolute path, or relative to the $NCHOME directory.
xsdFile
Path and file name of a corresponding XML XSD file. Can be an
absolute path, or relative to the $NCHOME directory. Used only if the
XML schema is an XSD.
isXsd
This Boolean variable specifies whether the schema is defined in
XSD or DTD format. Default is DTD, if not specified.
Netcool/Impact: DSA Reference Guide
Table 32. XmlHttpTypes mapping properties (continued)
Property
Description
url
Base URL for the HTTP server. The base URL includes the server
host name, and the path where the script or executable file that
provides the XML data is located. You do not need to specify the
trailing backslash in the base URL. This URL is combined with the
contents of the FilePath parameter to form the complete URL
when you retrieve the XML data in a policy.
user
User name valid under HTTP server authentication (optional).
password
Password valid under HTTP server authentication (optional).
realm
Authentication realm on the HTTP server (optional).
prefix
Namespace prefix that is used to identify the corresponding
element data types (optional).
connectionsPerHost
Number of connections per host. The default is 2. (Optional)
This example shows a set of mapping properties for XML data that is provided by
an HTTP server.
XmlDsa.httpTypes.1.typeName XML_http_superType
XmlDsa.httpTypes.1.dtdFile dsa/XmlDsa/http.dtd
XmlDsa.httpTypes.1.url http://localhost:9080/cgi-bin
XmlDsa.httpTypes.1.user jsmith
XmlDsa.httpTypes.1.password pwd
XmlDsa.httpTypes.1.realm primary
XmlDsa.httpTypes.1.connectionsPerHost 5
Reading XML documents
You can read XML documents from within a policy.
Procedure
1. Retrieve the document data item.
You retrieve the data item by calling the GetByFilter function and passing the
name of the super data type and a filter string.
2. Retrieve the root level element data item.
To retrieve the root level element data item, use the GetByLinks function.
3. Retrieve the child element data item.
To retrieve child element data items, you can use successive calls to the
GetByLinks function or you can use the embedded linking syntax.
4. Access attribute values.
To access an element data item's attribute values, reference the corresponding
data type fields.
Retrieving the document data item
You retrieve the data item by calling the GetByFilter function and passing the
name of the super data type and a filter string.
The content of the filter string varies depending on whether the data source is an
XML string, XML file, or XML data that is located on an HTTP server.
For XML strings, the filter is the entire XML string that you want to read. For XML
files, the filter is an empty string. For XML over HTTP, the filter string is an
Chapter 8. Working with the XML DSA
91
expression that specifies the method to use in retrieving the XML data and the
path to a script or executable file that provides the data on the HTTP server. For
more information, see “XML over HTTP.”
This example shows how to retrieve the document data item that is associated
with an XML string, where the corresponding super type is named
XML_string_SuperType:
// Call GetByFilter and pass the name of the super type
// and the filter string
Type = "XML_string_superType";
Filter = "<alert><node>Node1234</node><summary>
Node not responding</summary></alert>";
CountOnly = False;
DocDataItem = GetByFilter(Type, Filter, CountOnly);
This example shows how to retrieve the document data item that is associated
with an XML file, where the corresponding super type is named
XML_file_superType:
// Call GetByFilter and pass the name of the super type// and the filter
stringType = "XML_file_superType";Filter = "";CountOnly = False;DocDataItem =
GetByFilter(Type, Filter, CountOnly);
XML over HTTP
For XML over HTTP, the filter string is an expression that specifies the method to
use in retrieving the XML data and the path to a script or executable file that
provides the data on the HTTP server.
The XML DSA uses either the GET or POST method to retrieve the XML data. For
example::
Operation = ’method’ AND FilePath = ’path’
Where method is either GET or POST and path is the location of the script or
executable relative to the base URL. You specify the base URL when you set the
mapping information for the document in the XmlHttpTypes file.
Note: The FilePath specification can include query string values. You can retrieve
XML documents from the HTTP server that are dynamically created depending on
values that are sent by Netcool/Impact as part of the HTTP request.
This example shows how to use an HTTP GET request to retrieve the document
data item that is associated with XML data. In this example, the name of the super
data type is XML_http_superType and the location of the script that provides the
XML data is getXMLdoc.pl.
// Call GetByFilter and pass the name of the super type// and the filter
stringType = "XML_http_superType";Filter = "Operation = ’GET’ AND
FilePath = ’getXMLdoc.pl?node=NodeXYZ’";CountOnly = False;DocDataItem =
GetByFilter(Type, Filter, CountOnly);
Retrieving the root level element data item
To retrieve the root level element data item, use the GetByLinks function.
When you call GetByLinks, you must pass the name of the root level element data
type, an empty filter string, and the document data item.
This example shows how to use GetByLinks to retrieve the root level element data
item.
92
Netcool/Impact: DSA Reference Guide
// Call GetByLinks and pass the name of theDataTypes = {"XML_alert"};Filter = "";
MaxNum = "10000";DataItems = DocDataItem;RootDataItem =
GetByLinks(DataTypes, Filter, MaxNum, DataItems);
Retrieving child element data items
To retrieve child element data items, you can use successive calls to the GetByLinks
function or you can use the embedded linking syntax.
This example shows how to use the linking syntax to retrieve the first child
element data item that is linked to the root level element data item. Where the data
type of the child data item is XML_body.
ChildNode = RootDataItem[0].links.XML_body.first;
This example shows how to retrieve an array that contains all child element data
items that are linked to the root level element data item.
ChildNodes = RootDataItem[0].links.XML_body.array;
links is a keyword that is used to retrieve the linked data types that are associated
with RootDataItem.
v RootDataItem[0].links returns all the linked data types:
v RootDataItem[0].links.XML_body returns all elements for the linked data type
XML_body.
Once the elements retrieved, you can get an array of the elements by using the
following command then loop through every element by using an index.
bodyArray=RootDataItem[0].links.XML_body.array
In addition, RootDataItem[0].links.XML_body is treated as enumerated elements.
You can traverse the data by using the following example.
/*RootDataItem[0].links.XML_body.first to get the first element
RootDataItem[0].links.XML_body.last to get the last element
RootDataItem[0].links.XML_body.next to get the next element.
To use next keyword:*/
bodyElement=RootDataItem[0].links.XML_body.next;
while(bodyElement != null && bodyElement != NULL) {
Log("bodyElement : " + bodyElement);
}
The following policy example shows how to get PDCDATA from the XmlFileTOC
and exists in XmlFileTestPolicy in the project XML. Enumerated elements means
when the element is retrieved by using next, it is removed from the list and does
not exist anymore.
BookNode = TopNodes[0].links.FTEST_JavaXML_Contents;
Log("BookNode size: " + BookNode.size);
BookNodeLinksTypes=BookNode.links;
Log("BookNodeLinksTypes size : " + BookNodeLinksTypes.size);
Log("BookNodeLinksTypes: " +BookNodeLinksTypes);
Chapters=BookNodeLinksTypes.first.FTEST_JavaXML_Chapter;
Log("Chapters and size: " + Chapters.links.size + " " + Chapters);
index =0;
Chapter= Chapters.first;
while(Chapter != null && Chapter != NULL) {
index = index + 1;
Log("Chapter" +index + ": " + Chapter);
Chapter= Chapters.next;
Topics =Chapter.links.FTEST_JavaXML_Topic;
i = 1;
Topic=Topics.first;
Chapter 8. Working with the XML DSA
93
while(Topic != null && Topic != NULL) {
Log("Topic"+i+": " + Topic.PCDATA);
Topic=Topics.next;
i = i +1;
}
}
Accessing attribute values
To access an element data item's attribute values, reference the corresponding data
type fields.
This example shows how to log the value of the ID attribute that is associated with
the current element data item:
Log("The message ID is: " + DataItem.id);
This example shows how to log the PCDATA value that is associated with the
current element data item:
Log(DataItem.PCDATA);
Sample policies
The DSA provides four sample policies.
v XmlStringTestPolicy
v XmlFileTestPolicy
v XmlHttpTestPolicy
v XmlXsdFileTestPolicy
These policies are configured to use the TOC.dtd, TOC.xsd and TOC.xml files in the
$NCHOME/dsa/XmlDsa directory.
XmlStringTestPolicy
The XmlStringTestPolicy shows how to use the XML DSA to read data from an
XML string.
The policy reads the contents of an XML-formatted string and then prints the data
to the policy log. Before you use this policy, you must run the create DTD types
script as follows:
./CreateDtdTypes.sh NCI impactadmin impactpass ../TOC.dtd XmlStringTOC STEST_
You do not need to edit the contents of the XmlFileTypes configuration file. By
default, this file contains the necessary data source mappings. The data type
mappings are defined as follows:
This type declaration shows how to define an XmlFile type to parse an XML file. It
also uses a DTD file as the property "isXsd" is not defined.
XmlDsa.fileTypes.1.typeName=XmlFileTOC
XmlDsa.fileTypes.1.dtdFile=dsa/XmlDsa/TOC.dtd
XmlDsa.fileTypes.1.xmlFile=dsa/XmlDsa/TOC.xml
XmlDsa.fileTypes.1.prefix=FTEST_
This type declaration shows how to define an XmlFile type to parse an XML file.
The difference between this type and the previous one is that this one uses an XSD
file to get the schema info from.
94
Netcool/Impact: DSA Reference Guide
XmlDsa.fileTypes.2.typeName=XmlXsdFileTOC
XmlDsa.fileTypes.2.dtdFile=dsa/XmlDsa/TOC.xsd
XmlDsa.fileTypes.2.xmlFile=dsa/XmlDsa/TOC.xml
XmlDsa.fileTypes.2.prefix=XSDFTEST_
XmlDsa.fileTypes.2.isXsd=true
This type declaration shows how to define a XmlString type.
XmlDsa.fileTypes.3.typeName=XmlStringTOC
XmlDsa.fileTypes.3.dtdFile=dsa/XmlDsa/TOC.dtd
XmlDsa.fileTypes.3.xmlFile=XmlDsa.fileTypes.3.prefix=STEST_
XmlFileTestPolicy
The XmlFileTestPolicy shows how to use the XML DSA to read data from an XML
file.
This policy reads the contents of the TOC.xml file and then prints the data to the
policy log. Before you use this policy, you must run the create DTD types script as
follows:
./CreateDtdTypes.sh NCI impactadmin impactpass ../TOC.dtd XmlFileTOC FTEST_
You do not need to edit the contents of the XmlFileTypes configuration file. By
default, this file contains the necessary data source mappings. The following are
the data type mappings:
XmlDsa.fileTypes.1.typeName XmlFileTOC
XmlDsa.fileTypes.1.dtdFile dsa/XmlDsa/TOC.dtd
XmlDsa.fileTypes.1.xmlFile dsa/XmlDsa/TOC.xml
XmlDsa.fileTypes.1.prefix FTEST_
XmlHttpTestPolicy
The XmlHttpTestPolicy shows how to use the XML DSA to read data from a
location on an HTTP server.
This policy reads the XML data from an HTTP server and then prints it to the
policy log. Before you use this policy, you must run the CreateDtdTypes script as
follows:
./CreateDtdTypes.sh NCI impactadmin impactpass ../TOC.dtd XmlHttpTOC HTEST_
You must also install a Perl CGI script on the HTTP server that generates the XML
output that is requested by the DSA. This script is named xml.cgi and is located in
$NCHOME/dsa/XmlDsa. You must check to make sure that the first line of the script
references the actual location of the Perl executable file on the system before you
install the script. To install, copy the script into the cgi-bin directory that is used
by the HTTP server.
After you install the script, modify the XmlHttpTypes configuration file to reflect
the location of the script and to include a valid user name and password for the
authentication realm, if any.
The following example shows the data type mappings:
XmlDsa.httpTypes.1.typeName XmlHttpTOC
XmlDsa.httpTypes.1.dtdFile dsa/XmlDsa/TOC.dtd
XmlDsa.httpTypes.1.prefix HTEST_
XmlDsa.httpTypes.1.url http://localhost:9080
XmlDsa.httpTypes.1.user John
XmlDsa.httpTypes.1.password Smith
XmlDsa.httpTypes.1.realm basicrealm
Chapter 8. Working with the XML DSA
95
XmlXsdFileTestPolicy
The XmlXsdFileTestPolicy shows how to use the XML DSA to read data from an
XML file.
This policy reads XML data returned from a URL and then prints the data to the
policy log. Before you use this policy, you must run the create XSD types script as
follows:
./CreateXsdTypes.sh NCI impactadmin impactpass ../TOC.xsd XmlXsdFileTOC XSDFTEST_
where filename is the name and path of an XML file stored on the file system.
You do not need to edit the contents of the XmlFileTypes configuration file. By
default, this file contains the necessary data source mappings. The following are
the data type mappings:
XmlDsa.fileTypes.2.typeName=XmlXsdFileTOC
XmlDsa.fileTypes.2.dtdFile=dsa/XmlDsa/TOC.xsd
XmlDsa.fileTypes.2.xmlFile=dsa/XmlDsa/TOC.xml
XmlDsa.fileTypes.2.prefix=XSDFTEST_
XmlDsa.fileTypes.2.isXsd=true
96
Netcool/Impact: DSA Reference Guide
Chapter 9. Working with the SNMP DSA
The SNMP DSA is a data source adaptor that is used set and retrieve management
information stored by SNMP agents.
SNMP DSA overview
The SNMP DSA is a data source adaptor that is used to set and retrieve
management information stored by SNMP agents. It is also used to send SNMP
traps and notifications to SNMP managers.
The SNMP DSA is installed automatically when you install Tivoli Netcool/Impact.
You must make sure that any MIB files that are to be used by the DSA are located
in the $NCHOME/dsa/snmpdsa/mibs directory when you start the Impact Server. For
more information about installing MIB files, see “Installing MIB files” on page 100.
You are not required to perform any additional installation or configuration steps.
Impact reuses the SNMP sessions it creates to connect to the SNMP agent. If you
need to clear the SNMP session cache in Impact, make changes to the SNMP data
source.
You must perform the following tasks when you use the SNMP DSA:
v Create one data source for each SNMP agent that you want to access using the
DSA, or create a single data source and use it to access all agents. For more
information about working with SNMP data sources, see “Working with SNMP
data sources” on page 100.
v Create data types that you will use to access variables and tables managed by
SNMP agents. For more information about working with SNMP data types, see
“Working with SNMP data types” on page 102.
v Write one or more policies that set or retrieve variables and tables managed by
SNMP agents, or that send SNMP traps and notifications. For more information
about SNMP policies, see “SNMP policies” on page 104.
SNMP data model
An SNMP data model is an abstract representation of SNMP data managed by
agents in your environment.
SNMP data models have the following elements:
v SNMP data sources
v SNMP data types
SNMP data sources
SNMP data sources represent an agent in the environment.
The data source configuration specifies the host name and port where the agent is
running, and the version of SNMP that it supports. For SNMP v3, the
configuration also optionally specifies authentication properties.
You can either create one data source for each SNMP agent that you want to access
using the DSA, or you can create a single data source and use it to access all
© Copyright IBM Corp. 2006, 2015
97
agents. You can create and configure data sources using the GUI. After you create
a data source, you can create one or more data types that represent the OIDs of
variables managed by the corresponding agent.
SNMP data types
SNMP data types are Netcool/Impact data types that specify the structure and
content of data associated with an agent.
The identity of the agent is determined by the data source that is associated with
the data type. Each data type specifies one or more object IDs (OIDs) that reference
variables managed by the agent.
The SNMP DSA supports the following categories of data types:
v Packed OID data types
v Table data types
Previous versions of this DSA supported another category of data type called
discrete OID data types. This category was used to reference single variable OIDs.
In this version of the DSA, you access single variables in the exact same way that
you access the sets of variables represented by packed OID data types.
For more information about OIDs and SNMP variables, see the reference
documentation for the agent you want to access using the SNMP DSA.
Packed OID data types
Packed OID data types are data types that reference the OIDs of one or more
variables managed by a single agent. You use this category of data type when you
want to access single variables or sets of related variables. When you create a
packed OID data type, you specify the name of the associated data source, the OID
for each variable and options that determine the behavior of the DSA when
connecting to the agent.
For more information about creating packed OID data types, see “Working with
SNMP data types” on page 102.
Table data types
Table data types are data types that reference the OIDs of one or more SNMP
tables managed by a single agent. When you create a table data type, you specify
the name of the associated data source, the OID for the table and options that
determine the behavior of the DSA when connecting to the agent.
For more information about creating data types, see “Creating SNMP data types”
on page 102.
SNMP DSA process
The SNMP DSA process has the following phases:
v Sending Data to Agents
v Retrieving Data from Agents
v Sending Traps and Notifications to Managers
v Handling Error Conditions
v Handling Timeouts
98
Netcool/Impact: DSA Reference Guide
Sending data to agents
The DSA supports two functions in the Netcool/Impact policy language (IPL) that
allow you to send data to an SNMP agent. These functions are the standard
function AddDataItem and the SNMP function SnmpSetAction.
When Netcool/Impact encounters a call to one of these functions in a
Netcool/Impact policy, it assembles an SNMP SET command using the information
specified in the function parameters and passes this command to the DSA for
processing. The DSA then sends the command to the agent.
If the SET command is successful, the agent sends a confirmation message to the
DSA and Netcool/Impact continues processing the policy.
Retrieving data from agents
The DSA supports three functions that allow you to retrieve data from an agent.
These functions are the standard function GetByFilter and the SNMP functions
SnmpGetAction and SnmpGetNextAction.
When Netcool/Impact encounters a call to one of these functions in a
Netcool/Impact policy, it assembles an SNMP GET or GETNEXT command using the
information specified in the function parameters. It then passes this command to
the DSA for processing. The DSA then sends the command to the agent.
If the GET or GETNEXT command is successful, the agent sends the requested data
back to the DSA. The DSA returns the information to Netcool/Impact, which then
stores the information in a policy-level variable that you can access in subsequent
parts of the policy.
Sending traps and notifications to managers
The DSA supports an SNMP function named SNMPTrapAction that you use to send
traps or notifications to an SNMP manager.
When the Netcool/Impact encounters a call to SNMPTrapAction, it assembles an
SNMP TRAP command using the information specified in the function parameters.
It then passes this command to the DSA for processing. The DSA then sends the
command to the manager.
If the TRAP command is successful, the manager sends a confirmation message to
the DSA and the policy is processed.
Handling error conditions
If a SET, GET, GETNEXT, or TRAP command sent to an agent or manager is
unsuccessful, the DSA returns an error string to Netcool/Impact that can be
printed to the policy log or otherwise handled in the body of the policy.
Handling timeouts
If an agent or manager does not respond to a SET, GET, GETNEXT, or TRAP command
sent by the DSA within the timeout period specified in the function call or the
related SNMP data type, the DSA sets a timeout message in the error string and
returns it to Netcool/Impact. This error string can be handled in the body of the
policy in the same was as any other error message.
Chapter 9. Working with the SNMP DSA
99
Installing MIB files
You must make sure that any MIB files that are to be used by the DSA are located
in the $NCHOME/impact/dsa/snmpdsa/mibs directory when you start the
Netcool/Impact server. By default, this directory contains the RFC1213-MIB and
RFC1271-MIB files. Other commonly used MIB files are installed with
Netcool/Impact and are located in the $NCHOME/impact/dsa/snmpdsa/mibs directory.
You must copy these or other MIB files that you provide to the
$NCHOME/impact/dsa/snmpdsa/mibs directory before you can use them with the
DSA. After you copy a new file to this directory, you must stop and restart the
Netcool/Impact server.
Working with SNMP data sources
You use the GUI to perform the following tasks with SNMP data sources:
v Create new data sources
v Edit data sources
v Delete data sources
Creating SNMP data sources
About this task
You can either create one data source for each SNMP agent that you want to access
using the DSA, or you can create a single data source and use it to access all
agents.
If you plan to use the standard data-handling functions AddDataItem and
GetByFilter to access SNMP data, you must create a separate data source for each
agent. In this scenario, the host name, port, and other connection information for
the agent is encapsulated as part of the data source configuration. When you make
a call to the AddDataItem or GetByFilter function, you pass the name of a data
type associated with the data source and Netcool/Impact uses this information to
derive the identity and location of the agent in the environment.
If you plan to use the SNMP functions that are provided with this release of the
DSA, you can create a single data source and use it to access all agents. In this
scenario, the host name and port are passed as runtime parameters when you call
each function. You can dynamically specify the agent during policy runtime that is
based on host name information from incoming ObjectServer events or derived
from other external data sources.
This version of the DSA provides additional support for SNMP v3 authentication.
If you are creating a data source for use with SNMP v3, you must perform
additional configuration tasks.
Creating SNMP v1 and v2 data sources
Use this procedure to create an SNMP v1 or v2 data source.
Procedure
1. Log in to the Netcool/Impact GUI using a web browser.
2. Click the Data Sources tab and select SNMP from the Source list.
3. Click the New Data Source button.
The New Data Source dialog box opens.
100
Netcool/Impact: DSA Reference Guide
4. Type a unique name for the data source in the Data Source Name field.
5. If you are creating this data source for use with the standard data-handling
functions AddDataItem and GetByFilter, type the host name or IP address
where the agent resides in the Host Name field and the port in the Port field.
If you are creating this data source for use with the new SNMP functions, you
can accept the default values with no changes.
6. Type the name of the SNMP read-community in the Read Community field.
The default is public.
7. Type the name of the SNMP write-community in the Write Community field.
The default is public.
8. Type a timeout value in seconds in the Timeout field. When the DSA connects
to an agent associated with this data source, it waits for the specified timeout
period before returning an error to Netcool/Impact.
9. Select 1 or 2 from the Version list.
10. Click OK.
Creating SNMP v3 data sources
About this task
To create a data source with SNMP v3 authentication, you specify the configuration
properties and then provide the information required for the agent to authenticate
the DSA as an SNMP user. The authentication parameters can be overridden by
calls to the SNMP functions in the Impact Policy Language.
For information about authentication parameters, see the documentation provided
by the SNMP agent and manager.
To create an SNMP v3 data source:
Procedure
1. Log in to the GUI using a web browser.
2. Click the Data Sources tab and select SNMP from the Source list.
3. Click the New Data Source button.
The New Data Source dialog box opens.
4. Type a data source name, the host name and IP address of the SNMP agent,
community strings and timeout values as specified in the previous section.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Select 3 from the Version list.
Type the name of an SNMP v3 authentication user in the User field.
Select a protocol from the Authentication Protocol list. The default is MD5.
Type the password for the authentication user in the Password field.
Select a protocol from the Privacy Protocol field.
Type a privacy password in the Privacy Password field.
Type a context ID in the Context ID field.
Type a context name in the Context Name field.
Click OK.
Editing SNMP data sources
You can edit the configuration for a data source after you create it. To edit an
SNMP data source:
Chapter 9. Working with the SNMP DSA
101
Procedure
1. Log in to the GUI using a web browser.
2. Click the name of the data source in the Data Sources tab. The Edit Data
Source window opens.
3. Set the configuration properties for the data source as described in the previous
sections.
4. Click OK.
Results
Any changes to the configuration take effect immediately after you finish editing
the data source. There is no need to restart the Impact Server after making a
change.
Deleting an SNMP data source
About this task
To delete an SNMP data source:
Procedure
1. Log in to the Netcool/Impact GUI using a web browser.
2. In the Data Sources tab, click the Delete Data Source icon next to the name of
the data source you want to delete.
Working with SNMP data types
You use the GUI to perform the following tasks with SNMP data types:
v Create new data types
v Edit data types
v Delete data types
Creating SNMP data types
About this task
If you plan to use the standard data-handling functions AddDataItem and
GetByFilter to access SNMP data, you must create a separate data type for each
set of variables (packed OID data types) or each set of tables (table data types) that
you want to access. In this scenario, the object IDs (OIDs) for the variables or
tables are encapsulated as part of the data type configuration. When you make a
call to the AddDataItem or GetByFilter function, you pass the name of a data type
and this information is used to determine the identity of the variables or table.
If you plan to use the SNMP functions that are provided with this release of the
DSA, you can create a single data type for each data source and use it to access all
the variables and tables associated with the agent. In this scenario, the variable or
table OIDs are passed as runtime parameters when you call each function. You can
dynamically specify the OIDs during policy runtime that is based on information
from an external data source.
Creating packed OID data types
Packed OID data types are data types that reference the OIDs of one or more
variables managed by a single agent. You use this category of data type when you
want to access single variables or sets of related variables. When you create a
102
Netcool/Impact: DSA Reference Guide
packed OID data type, you specify the name of the associated data source, the OID
for each variable and options that determine the behavior of the DSA when
connecting to the agent.
To create a packed OID data type:
1. Log in to the Netcool/Impact GUI using a web browser.
2. Click the Data Types tab and select an SNMP data source from the Data
Source list.
3. Click the New Data Type icon. The New Data Type editor opens.
4. Type a name for the data type in the Data Type Name field.
5. Select an SNMP data source from the Data Source Name field. By default, the
data source you chose in step 2 is selected.
6. Select Packed from the OID Configuration list.
7. If you are creating this data type for use with the standard data-handling
functions AddDataItem and GetByFilter, you must create an attribute on the
data type for each variable you want to access. To create an attribute, click the
New Attribute button and specify an attribute name and the OID for the
variable.
If you are creating this data source for use with the new SNMP functions, you
do not need to explicitly create attributes for each variable. In this scenario, you
pass the variable OIDs when you make each function call in the
Netcool/Impact policy.
8. Click Save.
Creating table data types
Use this procedure to create a table data type.
Procedure
1. In the data types tab, select an SNMP data source from the list.
2. Click the New Data Type button to open the New Data Type editor.
3. Type a name for the data type in the Data Type Name field.
Important:
The data type name must match the table name that will be queried, for
example, ifTable, or ipRouteTable.
4. Select an SNMP data source from the Data Source Name field. By default, the
data source you chose in step 2 is selected.
5. Select Table from the OID Configuration list.
6. If you are creating this data type for use with the standard data-handling
functions AddDataItem and GetByFilter, you must create a new attribute on the
data type for each table you want to access. To create an attribute, click the
New Attribute button and specify an attribute name and the OID for the table.
Important:
The attributes are the column names in each table. For example, in the
following ifTable, the attributes will be ifIndex, ifDescr and other column
names:
Column Names
ifIndex
ifDescr
...
OID
.1.3.6.1.2.1.2.2.1.1
.1.3.6.1.2.1.2.2.1.2
...
Chapter 9. Working with the SNMP DSA
103
If you are creating this data source for use with the new SNMP functions, you
do not need to explicitly create attributes for each table. In this scenario, you
pass the table OIDs when you make each function call in the Netcool/Impact
policy.
7. If you want the DSA to retrieve table data from the agent using the SNMP
GETBULK command instead of an SNMP GET, select Get Bulk.
The GETBULK command retrieves table data using a continuous GETNEXT
command. This option is suitable for retrieving data from very large tables.
8. If you have selected Get Bulk, you can control the number of variables in the
table for which the GETNEXT operation is performed using the specified
Non-Repeaters and Max Repetitions values.
The Non-Repeaters value specifies the first number of non-repeating variables
and Max Repetitions specifies the number of repetitions for each of the
remaining variables in the operation.
9. Click Save.
Editing SNMP data types
You can edit the configuration for a data type after you create it. To edit an SNMP
data types:
Procedure
1. Log in to the GUI using a web browser.
2. Click the name of the data type in the Data Types tab.
The Edit Data Type window opens.
3. Set the configuration properties for the data type as described in the previous
sections.
4. Click OK.
Results
Any changes to the configuration take effect immediately after you finish editing
the data type. There is no need to restart the Impact Server after making a change.
Deleting SNMP data types
About this task
To delete an SNMP data type:
Procedure
1. Log in to the Netcool/Impact GUI using a web browser.
2. In the Data Types tab, click the Delete Data Type button next to the name of
the data type you want to delete.
SNMP policies
You can perform the following tasks related to the SNMP DSA in a policy:
v Set packed OID data on SNMP agents using standard data-handling functions
v Set packed OID data on SNMP agents using SNMP functions
v Set table data on SNMP agents using standard data-handling functions
v Set table data on SNMP agents using SNMP functions
104
Netcool/Impact: DSA Reference Guide
v Retrieve packed OID data on SNMP agents using standard data-handling
functions
v Retrieve packed OID data on SNMP agents using SNMP functions
v Send SNMP traps and notifications
Setting packed OID data with standard data-handling
functions
About this task
You can use the standard data-handling function AddDataItem to set the value of a
single variable managed by an agent or to set the value of multiple variables.
Setting the value of a single variable
To set the value of a single variable, you create a context, and populate its Oid and
Value member variables. You can also populate optional HostId and Port members
variables. After you populate the context variables, you call AddDataItem and pass
the name of an SNMP data type and the context as input parameters. If you
specified values for the HostId and Port variables in the context, these override the
host and port information as defined in the data type.
To create a context, you call the NewObject function as shown in the following
example.
// Call the NewObject function
MyContext = NewObject();
After you create the context, you can set the Oid and Value variables, as shown in
the following example. All member variables of the context must be set as strings.
// Populate the context variables
MyContext.Oid = ".1.3.6.1.2.1.1.4.0";
MyContext.Value = "MyValue";
Oid and Value represent the OID of the variable managed by the agent and its
corresponding value.
After you populate the context variables, you can call AddDataItem and pass the
name of an SNMP data type and the context as input parameters, as shown in the
following example.
// Call AddDataItem and pass the name of an SNMP data type and the context
AddDataItem("MySnmpType", MyContext);
In this example, the host name, and port where the agent is located is specified by
the MySnmpType data type.
If the DSA is unable to successfully send the data to the agent, it stores an error
message in the policy-level variable ErrorString. The following example shows
how to print the error message to the policy log.
// Print any error message to the policy log
Log("Errors: " + ErrorString);
The following example shows how to set the value of a variable managed by an
agent, where the host name and port are specified by the MySnmpType data type. In
this example, the variable OID is .1.3.6.1.2.1.1.4.0 and the value is MyValue.
Chapter 9. Working with the SNMP DSA
105
// Create a new context with the NewObject function
MyContext = NewObject();
// Populate the context variables
MyContext.Oid = ".1.3.6.1.2.1.1.4.0";
MyContext.Value = "MyValue";
// Call AddDataItem and pass the name of an SNMP data type and the context
AddDataItem("MySnmpType", MyContext);
// Print any error message to the policy log
Log("Errors: " + ErrorString);
The following example shows how to set the value of a variable managed by an
agent, where the host name and port specified by the data type are overridden by
context variables set in the policy. In this example, the host is 192.168.1.1 and the
port is 161.
// Create a new context with the NewObject function
MyContext = NewObject();
// Populate the context variables
MyContext.Oid = ".1.3.6.1.2.1.1.4.0";
MyContext.Value = "MyValue";
MyContext.HostId = "192.168.1.1";
MyContext.Port = 161;
// Call AddDataItem and pass the name of an SNMP data type and the context
AddDataItem("MySnmpType", MyContext);
// Print any error message to the policy log
Log("Errors: " + ErrorString);
Setting the value of multiple variables
To set the value of multiple variables, you create a context and populate member
variables that correspond to the attributes you configured when you created the
corresponding SNMP data type. You can also populate optional HostId and Port
members variables.
After you populate the context variables, you call AddDataItem and pass the name
of the SNMP data type and the context as input parameters. If you specified values
for the HostId and Port variables in the context, these override the host and port
information as defined in the data type.
To create a context, you call the NewObject function as shown in the following
example.
// Call the NewObject function
MyContext = NewObject();
After you create the context, you can set the member variables, and the optional
variables, as shown in the following example. All member variables of the context
must be set as strings.
106
Netcool/Impact: DSA Reference Guide
// Populate the context variables
MyContext.SysLocation = "New York";
MyContext.SysName = "SYS01";
Here, SysLocation, and SysName are attributes that you defined in the configuration
for the corresponding SNMP DSA data source.
After you populate the context variables, you can call AddDataItem and pass the
name of an SNMP data type and the context as input parameters, as shown in the
following example.
// Call AddDataItem and pass the name of an SNMP data type and the context
AddDataItem("MySnmpType", MyContext);
In this example, the host name, and port where the agent is located is specified in
the data type configuration.
If the DSA is unable to successfully send the data to the agent, it stores an error
message in the policy-level variable ErrorString. The following example shows
how to print the error message to the policy log.
// Print any error message to the policy log
Log("Errors: " + ErrorString);
The following example shows how to set the value of variables managed by an
agent, where the host name and port is specified by the MySnmpType data type.
// Create a new context with the NewObject function
MyContext = NewObject();
// Populate the context variables
MyContext.SysLocation = "New York";
MyContext.SysName = "SYS01";
// Call AddDataItem and pass the name of an SNMP data type and the context
AddDataItem("MySnmpType", MyContext);
// Print any error message to the policy log
Log("Errors: " + ErrorString);
The following example shows how to set the value of a variable managed by an
agent, where the host name and port specified by the data type are overridden by
context variables set in the policy. In this example, the host is 192.168.1.1 and the
port is 161.
// Create a new context with the NewObject function
MyContext = NewObject();
// Populate the context variables
MyContext.SysLocation = "New York";
MyContext.SysName = "SYS01";
MyContext.HostId = "192.168.1.1";
MyContext.Port = 161;
// Call AddDataItem and pass the name of an SNMP data type and the context
Chapter 9. Working with the SNMP DSA
107
AddDataItem("MySnmpType", MyContext);
// Print any error message to the policy log
Log("Errors: " + ErrorString);
Setting packed OID data with SNMP functions
Procedure
You can use the SNMP function SnmpSetAction to set the value of a single or
multiple variables managed by an agent.
When you call SnmpSetAction, you pass an SNMP data type, the host name and
port of the agent, an array of OIDs, and the array of values that you want to set. If
you are using SNMP v3, you can also specify the information required to
authenticate as an SNMP user.
For more information about SnmpSetAction, see “SNMPSetAction” on page 121.
Example
The following example shows how to set SNMP variables by calling SnmpSetAction
and passing the name of an SNMP data type, an array of OIDs, and an array of
values as input parameters. In this example, the SNMP data type is named
SNMP_PACKED.
// Call SnmpSetAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP SET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = {".1.3.6.1.2.1.1.4.0", ".1.3.6.1.2.1.1.5.0"};
ValueList = {"Value_01", "Value_02"};
SnmpSetAction(TypeName, HostId, Port, VarIdList, ValueList, NULL, NULL,
NULL, NULL, NULL, NULL, NULL, NULL, NULL);
For more examples, see “SNMPSetAction” on page 121.
Retrieving packed OID data from SNMP agents
About this task
Packed OID data types reference the OIDs of one or more variables managed by a
single agent. You use this category of data type when you want to access single
variables or sets of related variables.
You can retrieve packed OID data from SNMP agents using one of the following
functions:
Procedure
v Standard data-handling functions
v SNMP functions
Retrieving packed OID data with standard data-Handling
functions
You can use the standard data-handling function GetByFilter to retrieve packed
OID data managed by an agent.
108
Netcool/Impact: DSA Reference Guide
To retrieve the packed OID data, you call GetByFilter and specify the name of an
SNMP data type as a runtime parameter. The data type configuration contains a
list of OIDs for the variables whose value you want to retrieve and attribute names
that you can use to reference the values. The data source associated with the data
type specifies the host name and port where the agent is located.
The GetByFilter function returns an array of data items whose first element stores
a context where the member variables represent values retrieved from the agent.
You can reference the returned values using the attribute names that you defined
when you created the data type.
If the DSA is unable to successfully retrieve the data, it stores an error message in
a member variable on the context called ErrorString.
The following example shows how to call GetByFilter and specify the name of an
SNMP data type. You can set the Filter parameter to an empty string and
CountOnly to False.
// Call GetByFilter and pass the name of an SNMP data type
TypeName = "MySnmpType";
Filter = "";
CountOnly = False;
MySNMPValues = GetByFilter(TypeName, Filter, CountOnly);
The following example shows how to access values returned by the function. In
this example, MySnmpType defines attributes named HostId, SysContact, SysName,
and SysLocation.
// Access the member variables of the context returned by GetByFilter
Log("HostId: " + MySNMPValues[0].HostId);
Log("SysContact: " + MySNMPValues[0].SysContact);
Log("SysName: " + MySNMPValues[0].SysName);
Log("SysLocation: " + MySNMPValues[0].SysLocation);
The following example shows how to access an error message returned by the call
to GetByFilter.
Log("Errors: " + MySNMPValues[0].ErrorString);
The following complete example shows how to use GetByFilter and handle the
values it returns.
// Call GetByFilter and pass the name of an SNMP data type
TypeName = "MySnmpType";
Filter = "";
CountOnly = False;
MySNMPValues = GetByFilter(TypeName, Filter, CountOnly);
// Access the member variables of the context returned by GetByFilter
Log("HostId: " + MySNMPValues[0].HostId);
Log("SysContact: " + MySNMPValues[0].SysContact);
Log("SysName: " + MySNMPValues[0].SysName);
Log("SysLocation: " + MySNMPValues[0].SysLocation);
Log("Errors: " + MySNMPValues[0].ErrorString);
Chapter 9. Working with the SNMP DSA
109
Retrieving packed OID data with SNMP functions
You can use the SNMP function SnmpGetAction to retrieve packed OID data
managed by an agent.
When you call SnmpGetAction, you pass an SNMP data type, the host name and
port of the agent, and other parameters. If you are using SNMP v3, you can also
specify the information required to authenticate as an SNMP user.
For more information about SnmpGetAction, see “SNMPGetAction” on page 113.
The following example shows how to use SnmpGetAction. In this example, the
variable OIDs are specified by the SNMP_PACKED data type configuration.
// Call SnmpGetAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP GET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
SnmpGetAction(TypeName, HostId, Port, NULL, NULL, NULL, NULL, NULL, NULL, NULL,
NULL, NULL, NULL);
// Print the results of the SNMP GET to the policy log
Count = 0;
While (Count < Length(ValueList)) {
Log(ValueList[Count]);
Count = Count + 1;
}
Traversing SNMP trees
You can use the SnmpGetNextAction function to retrieve the value of the next
SNMP variables in the variable tree from an agent. This function is useful in
situations where you want to traverse an entire tree or in situations where you do
not know the OID of subsequent variables in a tree that you want to retrieve.
When you call SnmpGetNextAction, you pass an SNMP data type and the host
name and port where the agent is located. If you are using SNMP v3, you can also
specify the information required to authenticate as an SNMP user. You can also
optionally pass a list of OIDs and other information needed to retrieve the data.
For more information about the SnmpGetNextAction function, see
“SNMPGetNextAction” on page 117.
The following example shows how to use SnmpGetNextAction.
// Call SnmpGetNextAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP GETNEXT
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
SnmpGetNextAction(TypeName, HostId, Port, NULL, NULL, NULL, NULL, NULL,
NULL, NULL, NULL, NULL, NULL);
// Print the results of the SNMP GETNEXT to the policy log
Count = 0;
110
Netcool/Impact: DSA Reference Guide
While (Count < Length(ValueList)) {
Log(VarIdList[Count] + ": " + ValueList[Count]);
Count = Count + 1;
}
Retrieving table data from SNMP agents
About this task
Table data types reference the OIDs of one or more tables managed by a single
agent. You use this category of data type when you want to access SNMP tables.
You can retrieve table data from SNMP agents using:
Procedure
v Standard data-handling functions
v SNMP functions
Retrieving table data with standard data-handling functions
You can use the standard data-handling function GetByFilter to retrieve table data
managed by an agent.
To retrieve the table data, you call GetByFilter and specify the name of an SNMP
data type as a runtime parameter. The data type configuration contains a list of
OIDs for the tables whose value you want to retrieve and attribute names that you
can use to reference the tables. The data source associated with the data type
specifies the host name and port where the agent is located.
The GetByFilter function returns an array of data items whose first element stores
a context where the member variables represent values retrieved from the agent.
You can reference the returned values using the attribute names that you defined
when you created the data type.
If the DSA is unable to successfully retrieve the data, it stores an error message in
a member variable on the context called ErrorString.
The following example shows how to call GetByFilter and specify the name of an
SNMP data type. You can set the Filter parameter to an empty string and
CountOnly to False.
// Call GetByFilter and pass the name of an SNMP data type
TypeName = "MySnmpType";
Filter = "";
CountOnly = False;
MySNMPValues = GetByFilter(TypeName, Filter, CountOnly);
The following example shows how to access values returned by the function. In
this example, MySnmpType defines attributes named HostId, SysContact, SysName,
and SysLocation.
// Access the member variables of the context returned by GetByFilter
Log("HostId: " + MySNMPValues[0].HostId);
Log("SysContact: " + MySNMPValues[0].SysContact);
Log("SysName: " + MySNMPValues[0].SysName);
Log("SysLocation: " + MySNMPValues[0].SysLocation);
Chapter 9. Working with the SNMP DSA
111
The following example shows how to access an error message returned by the call
to GetByFilter.
Log("Errors: " + MySNMPValues[0].ErrorString);
The following complete example shows how to use GetByFilter and handle the
values it returns.
// Call GetByFilter and pass the name of an SNMP data type
TypeName = "MySnmpType";
Filter = "";
CountOnly = False;
MySNMPValues = GetByFilter(TypeName, Filter, CountOnly);
// Access the member variables of the context returned by GetByFilter
Log("HostId: " + MySNMPValues[0].HostId);
Log("SysContact: " + MySNMPValues[0].SysContact);
Log("SysName: " + MySNMPValues[0].SysName);
Log("SysLocation: " + MySNMPValues[0].SysLocation);
Log("Errors: " + MySNMPValues[0].ErrorString);
Sending SNMP traps and notifications
About this task
You use the SnmpTrapAction function to send a trap (for SNMP v1) or a notification
(for SNMP v2) to an SNMP manager.
To send the trap or notification, you call the function and pass the host name and
port where the manager is located, a list of OIDs and corresponding values for the
trap, and other related information. If the trap or notification is not successful, the
function stores an error message in the policy-level ErrorString variable. You can
handle the contents of ErrorString in subsequent parts of the policy.
For more information about the SnmpTrapAction function, see “SnmpTrapAction”
on page 124.
Example
The following example shows how to send a trap using the SnmpTrapAction
function.
// Call SnmpTrapAction and pass the host name, port, OID list, OID values
// and other required parameters
HostId = "192.168.1.1";
Port = 162;
Version = 1;
Community = "public";
SysUpTime = 1001;
Enterprise = ".1.3.6.1.2.1.11";
GenericTrap = 3;
SpecificTrap = 0;
VarIdList = {".1.3.6.1.2.1.2.2.1.1.0", "sysDescr"};
ValueList = {"2", "My system"};
SnmpTrapAction(HostId, Port, VarIdList, ValueList, Community, Version,
112
Netcool/Impact: DSA Reference Guide
SysUpTime, Enterprise, GenericTrap, SpecificTrap, NULL);
// Print any errors to the policy log
Log("Error: " + ErrorList);
The following example shows how to send a notification using the SnmpTrapAction
function. In this example, you set a value for the SnmpTrapOid parameter.
// Call SnmpTrapAction and pass the host name, port, OID list, OID values
// and other required parameters
HostId = "192.168.1.1";
Port = 162;
Version = 1;
Community = "public";
SysUpTime = 1001;
Enterprise = ".1.3.6.1.2.1.11";
GenericTrap = 3;
SpecificTrap = 0;
VarIdList = {".1.3.6.1.2.1.2.2.1.1.0", "sysDescr"};
ValueList = {"2", "My system"};
SnmpTrapOid = ".1.3.6.1.2.4.1.11";
SnmpTrapAction(HostId, Port, VarIdList, ValueList, Community, Version,
SysUpTime, Enterprise, GenericTrap, SpecificTrap, SnmpTrapOid);
// Print any errors to the policy log
Log("Error: " + ErrorList);
SNMP functions
The SNMP DSA supports a special set of functions that you can use to send data
to and retrieve data from SNMP agents. You can also use the SNMP functions to
send SNMP traps and notifications to SNMP managers.
The SNMP DSA supports the following functions:
v SnmpGetAction
v SnmpGetNextAction
v SnmpSetAction
v SnmpTrapAction
The SNMP DSA also supports the use of standard data-handling functions as
described in “SNMP policies” on page 104.
SNMPGetAction
The SnmpGetAction function retrieves a set of SNMP variables from the specified
agent.
The values are stored in a variable named ValueList. This function operates by
sending an SNMP GET command to the specified agent.
When you call SnmpGetAction, you pass an SNMP data type and, for SNMP v3,
any authorization parameters that are required. To override the agent and variable
Chapter 9. Working with the SNMP DSA
113
information specified in the SNMP data type, you can also optionally pass a host
name, a port number, a list of OIDs, and other information needed to retrieve the
data.
Syntax
The following is the syntax for SnmpGetAction:
SnmpGetAction(TypeName, [HostId], [Port], [VarIdList], [Community], [Timeout],
[Version], [UserId], [AuthProtocol], [AuthPassword], [PrivPassword],
[ContextId], [ContextName])
Parameters
The SNMPGetAction function has the following parameters.
Table 33. SNMPGetAction function parameters
Parameter
Format
Description
TypeName
String
Name of the SNMP data type that specifies the host name,
port, OIDs, and other information needed to retrieve the
SNMP data.
HostId
String
Optional. Host name or IP address of the system where the
SNMP agent is running. Overrides value specified in the
SNMP data type.
Port
Integer
Optional. Port where the SNMP agent is running. Overrides
value specified in the SNMP data type.
VarIdList
Array
Optional. Array of strings containing the OIDs of SNMP
variables to retrieve from the agent. Overrides values
specified in the SNMP data type.
Community
String
Optional. Name of the SNMP write community string.
Default is public.
Timeout
Integer
Optional. Number of seconds to wait for a response from the
SNMP agent before timing out.
Version
Integer
Optional. SNMP version number. Possible values are 1, 2
and 3. Default is 1.
UserId
String
Required for SNMP v3 authentication. If using SNMP v1 or
v2, or using v3 without authentication, pass a null value for
this parameter.
AuthProtocol
String
Optional. For use with SNMP v3 authentication only.
Possible values are. MD5, MD5_AUTH, NO_AUTH, SHA, SHA_AUTH.
NO_AUTH is the default.
AuthPassword
String
Optional. For use with SNMP v3 authentication only.
Authentication password associated with the specified
SNMP User ID.
PrivProtocol
String
Optional. Privacy policy to be used with this function.
Possible values are. DES, AES, None. None is the default.
Note: This parameter does not form a part of the function
call. It must be defined before the call to the function.
114
PrivPassword
String
Optional. For use with SNMP v3 authentication only. Privacy
password associated with the specified SNMP User ID.
ContextId
String
Optional. For use with SNMP v3 authentication only.
Authentication context ID.
Netcool/Impact: DSA Reference Guide
Table 33. SNMPGetAction function parameters (continued)
Parameter
Format
Description
ContextName
String
Optional. For use with SNMP v3 authentication only.
Authentication context name.
Return Values
When you call SnmpGetAction, it sets the following variables in the policy context:
ValueList.
The ValueList variable is an array of strings, each of which stores the value of one
variable retrieved from the SNMP agent. The strings in the array are assigned in
the order that the variable OIDs are specified in the SNMP data type or the
VarIdList parameter.
Error handling
If the SNMP operation fails, the Impact policy engine throws an SnmpDSAException.
You can handle this exception using the Handle() function:
// Handle SNMP DSA Exceptions
Handle com.micromuse.dsa.snmpdsa.SnmpDSAException {
log("ErrorMessage: " + ErrorMessage);
javaCall("com.micromuse.dsa.snmpdsa.SnmpDSAException", ExceptionMessage, "getCause", null);
log("MyException is " + ExceptionMessage);
}
Example 1
The following example shows how to retrieve a set of SNMP variables by calling
SNMPGetAction and passing the name of an SNMP data type as an input parameter.
In this example, the SNMP data type is named SNMP_PACKED. The data type
configuration specifies the host name and port where the SNMP agent is running
and the OIDs of the variables you want to retrieve.
// Call SNMPGetAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP GET
TypeName = "SNMP_PACKED";
SnmpGetAction(TypeName, "192.168.1.1", 161, null, null, null,
null, null, null, null, null, null, null);
// Print the results of the SNMP GET to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(ValueList[Count]);
Count = Count + 1;
}
Example 2
The following example shows how to retrieve a set of SNMP variables by calling
SNMPGetAction and explicitly overriding the default host name, port, and other
configuration values set in the SNMP data type.
Example 2 using IPL.
Chapter 9. Working with the SNMP DSA
115
// Call SnmpGetAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP GET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = {".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"};
Community = "private";
Timeout = 15;
SnmpGetAction(TypeName, HostId, Port, VarIdList, Community,
Timeout, null, null, null, null, null, null,null);
// Print the results of the SNMP GET to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(ValueList[Count]);
Count = Count + 1;
}
Example 2 using JavaScript.
// Call SnmpGetAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP GET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = [".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"];
Community = "private";
Timeout = 15;
SnmpGetAction(TypeName, HostId, Port, VarIdList, Community,
Timeout, null, null, null, null, null, null,null);
// Print the results of the SNMP GET to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(ValueList[Count]);
Count = Count + 1;
}
Example 3
The following example shows how to retrieve a set of SNMP variables using
SNMP v3 authentication.
Example 3 using IPL.
// Call SnmpGetAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP GET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = {".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"};
Community = "private";
Timeout = 15;
Version = 3;
UserId = "snmpusr";
AuthProtocol = "MD5_AUTH";
AuthPassword = "snmppwd";
ContextId = "ctx";
SnmpGetAction(TypeName, HostId, Port, VarIdList, Community,
Timeout, Version, UserId, AuthProtocol, AuthPassword, null, ContextId, null);
// Print the results of the SNMP GET to the policy log
116
Netcool/Impact: DSA Reference Guide
Count = 0;
while (Count < Length(ValueList)) {
Log(ValueList[Count]);
Count = Count + 1;
}
Example 3 using JavaScript.
// Call SnmpGetAction and pass the name of the SNMP data type that contains
// configuration information required to perform the SNMP GET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = [".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"];
Community = "private";
Timeout = 15;
Version = 3;
UserId = "snmpusr";
AuthProtocol = "MD5_AUTH";
AuthPassword = "snmppwd";
ContextId = "ctx";
SnmpGetAction(TypeName, HostId, Port, VarIdList, Community,
Timeout, Version, UserId, AuthProtocol, AuthPassword, null, ContextId, null);
// Print the results of the SNMP GET to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(ValueList[Count]);
Count = Count + 1;
}
SNMPGetNextAction
The SnmpGetNextAction function retrieves the next SNMP variables in the
variable tree from the specified agent.
It stores the resulting OIDs in a variable named VarIdList, the resulting values in
a variable named ValueList. The function sends a series of SNMP GETNEXT
commands to the specified agent where each command specifies a single OID for
which the next variable in the tree is to be retrieved.
When you call SnmpGetNextAction, you pass an SNMP data type and, for SNMP
v3, any authorization parameters that are required. To override the agent and
variable information specified in the SNMP data type, you can also optionally pass
a host name, a port number, a list of OIDs, and other information needed to
retrieve the data.
Syntax
The following is the syntax for SnmpGetNextAction:
SnmpGetNextAction(TypeName, [HostId], [Port], [VarIdList], [Community],
[Timeout], [Version], [UserId], [AuthProtocol], [AuthPassword],
[PrivPassword], [ContextId], [ContextName])
Chapter 9. Working with the SNMP DSA
117
Parameters
The SnmpGetNextAction function has the following parameters.
Table 34. SnmpGetNextAction function parameters
Parameter
Format
Description
TypeName
String
Name of the SNMP data type that specifies the host name,
port, OIDs, and other information needed to retrieve the
SNMP data.
HostId
String
Optional. Host name or IP address of the system where
the SNMP agent is running. Overrides value specified in
the SNMP data type.
Port
Integer
Optional. Port where the SNMP agent is running.
Overrides value specified in the SNMP data type.
VarIdList
Array
Optional. Array of strings containing the OIDs of SNMP
variables to retrieve from the agent. Overrides values
specified in the SNMP data type.
Community
String
Optional. Name of the SNMP write community string.
Default is public.
Timeout
Integer
Optional. Number of seconds to wait for a response from
the SNMP agent before timing out.
Version
Integer
Optional. SNMP version number. Possible values are 1, 2
and 3. Default is 1.
UserId
String
Required for SNMP v3 authentication. If using SNMP v1
or v2, or v3 without authentication, pass a null value for
this parameter.
AuthProtocol
String
Optional. For use with SNMP v3 authentication only.
Possible values are. MD5, MD5_AUTH, NO_AUTH, SHA, SHA_AUTH.
NO_AUTH is the default.
AuthPassword
String
Optional. For use with SNMP v3 authentication only.
Authentication password associated with the specified
SNMP User ID.
PrivProtocol
String
Optional. Privacy policy to be used with this function.
Possible values are. DES, AES, None. None is the default.
Note: This parameter does not form a part of the function
call. It must be defined before the call to the function.
PrivPassword
String
Optional. For use with SNMP v3 authentication only.
Privacy password associated with the specified SNMP
User ID.
ContextId
String
Optional. For use with SNMP v3 authentication only.
Authentication context ID.
ContextName
String
Optional. For use with SNMP v3 authentication only.
Authentication context name.
Error handling
If the SNMP operation fails, the Impact policy engine throws an SnmpDSAException.
You can handle this exception using the Handle() function:
118
Netcool/Impact: DSA Reference Guide
// Handle SNMP DSA Exceptions
Handle com.micromuse.dsa.snmpdsa.SnmpDSAException {
log("ErrorMessage: " + ErrorMessage);
javaCall("com.micromuse.dsa.snmpdsa.SnmpDSAException", ExceptionMessage, "getCause", null);
log("MyException is " + ExceptionMessage);
}
Example 1
The following example shows how to retrieve SNMP variables in the variable tree
by calling SNMPGetNextAction and passing the name of an SNMP data type as an
input parameter. In this example, the SNMP data type is named SNMP_PACKED. The
data type configuration specifies the host name and port where the SNMP agent is
running and the OIDs of the variables whose subsequent values in the tree you
want to retrieve.
// Call SNMPGetNextAction and pass the name of the SNMP
// data type that contains configuration information required
// to perform the SNMP GETNEXT
TypeName = "SNMP_PACKED";
SnmpGetNextAction(TypeName, "192.168.1.1", 161, null, null,
null, null, null, null, null, null, null, null);
// Print the results of the SNMP GETNEXT to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(VarIdList[Count] + ": " + ValueList[Count]);
Count = Count + 1;
}
Example 2
The following example shows how to retrieve SNMP variables in the variable tree
by calling SNMPGetNextAction and explicitly overriding the default host name, port,
and other configuration values set in the SNMP data type.
Example 2 using IPL.
// Call SnmpGetNextAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP GETNEXT
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = {".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"};
Community = "private";
Timeout = 15;
SnmpGetNextAction(TypeName, HostId, Port, VarIdList, Community,
Timeout, null, null, null, null, null, null, null);
// Print the results of the SNMP GETNEXT to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(VarIdList[Count] + ": " + ValueList[Count]);
Count = Count + 1;
}
Chapter 9. Working with the SNMP DSA
119
Example 2 using JavaScript.
// Call SnmpGetNextAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP GETNEXT
TypeName = "ipRouteTable";
HostId = "localhost";
Port = 161;
VarIdList = [".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"];
Community = "public";
Timeout = 15;
SnmpGetNextAction(TypeName, HostId, Port, VarIdList, Community, Timeout, null, null,
null, null, null, null, null);
// Print the results of the SNMP GETNEXT to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(VarIdList[Count] + ": " + ValueList[Count]);
Count = Count + 1;
}
Example 3
The following example shows how to retrieve subsequent SNMP variables in the
variable tree using SNMP v3 authentication.
Example 3 using IPL.
// Call SnmpGetNextAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP GETNEXT
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = {".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"};
Community = "private";
Timeout = 15;
Version = 3;
UserId = "snmpusr";
AuthProtocol = "MD5_AUTH";
AuthPassword = "snmppwd";
ContextId = "ctx";
SnmpGetNextAction(TypeName, HostId, Port, VarIdList, Community,
Timeout, Version, UserId, AuthProtocol, AuthPassword, null,
ContextId, null);
// Print the results of the SNMP GET to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(VarIdList[Count] + ": " + ValueList[Count]);
Count = Count + 1;
}
Example 3 using JavaScript.
// Call SnmpGetNextAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP GETNEXT
TypeName = "ipRouteTable";
HostId = "localhost";
Port = 161;
VarIdList = [".1.3.6.1.2.1.1.5.0", ".1.3.6.1.2.1.1.6.0"];
Community = "public";
Timeout = 15;
120
Netcool/Impact: DSA Reference Guide
Version = 3;
UserId = "snmpuser";
AuthProtocol = "MD5";
AuthPassword = "snmppwd";
PrivProtocol = "DES";
PrivPassword = "privpwd";
SnmpGetNextAction(TypeName, HostId, Port, VarIdList, Community, Timeout, Version,
UserId, AuthProtocol, AuthPassword, PrivPassword, null, null);
// Print the results of the SNMP GET to the policy log
Count = 0;
while (Count < Length(ValueList)) {
Log(VarIdList[Count] + ": " + ValueList[Count]);
Count = Count + 1;
}
SNMPSetAction
The SnmpSetAction function sets variable values on the specified SNMP agent.
This function operates by sending an SNMP SET command to the specified agent.
When you call SNMPSetAction, you pass an SNMP data type, the host name, and
port of the agent, an array of OIDs, and the array of values that you want to set. If
you are using SNMP v3, you can also include information required to authenticate
as an SNMP user.
Syntax
The following is the syntax for SNMPSetAction:
SnmpSetAction(TypeName, [HostId], [Port], [VarIdList],
ValueList, [Community], [Timeout], [Version], [UserId], [AuthProtocol],
[AuthPassword], [PrivPassword], [ContextId], [ContextName])
Parameters
The SNMPSetAction function has the following parameters.
Table 35. SNMPSetAction function parameters
Parameter
Format
Description
TypeName
String
Name of the SNMP data type that specifies the host
name, port, OIDs, and other information needed to
set the SNMP data.
HostId
String
Optional. Host name or IP address of the system
where the SNMP agent is running. Overrides value
specified in the SNMP data type.
Port
Integer
Optional. Port where the SNMP agent is running.
Overrides value specified in the SNMP data type.
VarIdList
Array
Array of strings containing the OIDs of SNMP
variables to set on the agent. Overrides values
specified in the SNMP data type.
ValueList
Array
Array of strings containing the values you want to
set. You must specify these values in the same order
that the OIDs appear either in the SNMP data type
or in the VarIdList variable.
Community
String
Optional. Name of the SNMP write community
string. Default is public.
Chapter 9. Working with the SNMP DSA
121
Table 35. SNMPSetAction function parameters (continued)
Parameter
Format
Description
Timeout
Integer
Optional. Number of seconds to wait for a response
from the SNMP agent before timing out.
Version
Integer
Optional. SNMP version number. Possible values are
1, 2 and 3. Default is 1.
UserId
String
Required for SNMP v3 authentication. If using SNMP
v1 or v2, or using v3 without authentication, pass a
null value for this parameter.
AuthProtocol
String
Optional. For use with SNMP v3 authentication only.
Possible values are. MD5, MD5_AUTH, NO_AUTH, SHA,
SHA_AUTH. NO_AUTH is the default.
AuthPassword
String
Optional. For use with SNMP v3 authentication only.
Authentication password associated with the
specified SNMP User ID.
PrivProtocol
String
Optional. Privacy policy to be used with this
function. Possible values are. DES, AES, None. None is
the default.
Note: This parameter does not form a part of the
function call. It must be defined before the call to the
function.
PrivPassword
String
Optional. For use with SNMP v3 authentication only.
Privacy password associated with the specified
SNMP User ID.
ContextId
String
Optional. For use with SNMP v3 authentication only.
Authentication context ID.
ContextName
String
Optional. For use with SNMP v3 authentication only.
Authentication context name.
Error handling
If the SNMP operation fails, the Impact policy engine throws an SnmpDSAException.
You can handle this exception using the Handle() function:
// Handle SNMP DSA Exceptions
Handle com.micromuse.dsa.snmpdsa.SnmpDSAException {
log("ErrorMessage: " + ErrorMessage);
javaCall("com.micromuse.dsa.snmpdsa.SnmpDSAException", ExceptionMessage, "getCause", null);
log("MyException is " + ExceptionMessage);
}
Example 1
The following example shows how to set SNMP variables by calling SNMPSetAction
and passing the name of an SNMP data type, an array of OIDs, and an array of
values as input parameters. In this example, the SNMP data type is named
SNMP_PACKED.
Example 1 using IPL.
// Call SnmpSetAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP SET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
122
Netcool/Impact: DSA Reference Guide
VarIdList = {".1.3.6.1.2.1.1.4.0", ".1.3.6.1.2.1.1.5.0"};
ValueList = {"Value_01", "Value_02"};
SnmpSetAction(TypeName, HostId, Port, VarIdList, ValueList,
null, null, null, null, null, null, null, null, null);
Example 1 using JavaScript.
// Call SnmpSetAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP SET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = [".1.3.6.1.2.1.1.4.0", ".1.3.6.1.2.1.1.5.0"];
ValueList = ["Value_01", "Value_02"];
SnmpSetAction(TypeName, HostId, Port, VarIdList, ValueList,
null, null, null, null, null, null, null, null, null);
Example 2
The following example shows how to set SNMP variables using SNMP v3
authentication.
Example 2 using IPL.
// Call SnmpSetAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP SET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = { ".1.3.6.1.2.1.1.4.0", ".1.3.6.1.2.1.1.5.0"};
ValueList = {"Value_01", "Value_02"};
Community = "private";
Timeout = 15;
Version = 3;
UserId = "snmpusr";
AuthProtocol = "MD5_AUTH";
AuthPassword = "snmppwd";
ContextId = "ctx";
SnmpSetAction(TypeName, HostId, Port, VarIdList, ValueList,
Community, Timeout, Version, UserId, AuthProtocol,
AuthPassword, null, ContextId, null);
Example 2 using JavaScript.
// Call SnmpSetAction and pass the name of the
// SNMP data type that contains configuration information
// required to perform the SNMP SET
TypeName = "SNMP_PACKED";
HostId = "192.168.1.1";
Port = 161;
VarIdList = [".1.3.6.1.2.1.1.4.0", ".1.3.6.1.2.1.1.5.0"];
ValueList = ["Value_01", "Value_02"];
Community = "private";
Timeout = 15;
Version = 3;
UserId = "snmpusr";
AuthProtocol = "MD5_AUTH";
AuthPassword = "snmppwd";
ContextId = "ctx";
SnmpSetAction(TypeName, HostId, Port, VarIdList, ValueList,
Community, Timeout, Version, UserId, AuthProtocol,
AuthPassword, null, ContextId, null);
Chapter 9. Working with the SNMP DSA
123
SnmpTrapAction
The SnmpTrapAction function sends a trap (for SNMP v1) or a notification (for
SNMP v2) to an SNMP manager. Sending traps or notifications is not supported
for SNMP v3.
Syntax
The following is the syntax for SnmpTrapAction:
SnmpTrapAction(HostId, Port, [VarIdList], [ValueList],
[Community], [Timeout], [Version], [SysUpTime], [Enterprise],
[GenericTrap], [SpecificTrap], [SnmpTrapOid])
Parameters
The SnmpTrapAction function has the following parameters.
Table 36. SnmpTrapAction function parameters
Parameter
Format
Description
HostId
String
Host name or IP address of the system where the
SNMP manager is running.
Port
Integer
Port where the SNMP manager is running.
VarIdList
Array
Optional. Array of strings containing the OIDs of
SNMP variables to send to the manager.
ValueList
Array
Optional. Array of strings containing the values you
want to send to the manager. You must specify these
values in the same order that the OIDs appear in
the VarIdList variable.
Community
String
Optional. Name of the SNMP write community
string. Default is public.
Timeout
Integer
Optional. Number of seconds to wait for a response
from the SNMP agent before timing out.
Version
Integer
Optional. SNMP version number. Possible values are
1 and 2. Default is 1.
SysUpTime
Integer
Optional. Number of milliseconds since the system
started. Default is the current system time in
milliseconds.
Enterprise
String
Required for SNMP v1 only. Enterprise ID.
GenericTrap
String
Required for SNMP v1 only. Generic trap ID.
SpecificTrap
String
Required for SNMP v1 only. Specific trap ID.
SnmpTrapOid
String
Optional for SNMP v1. Required for SNMP v2.
SNMP trap OID.
Example 1
The following example shows how to send an SNMP v1 trap to a manager using
SnmpTrapAction.
// Call SnmpTrapAction
HostId = "localhost";
Port = 162;
Version = 1;
Community = "public";
SysUpTime = 1001;
124
Netcool/Impact: DSA Reference Guide
Enterprise = ".1.3.6.1.2.1.11";
GenericTrap = 3;
SpecificTrap = 0;
VarIdList = {".1.3.6.1.2.1.2.2.1.1.0", "sysDescr"};
ValueList = {"2", "My system"};
SnmpTrapAction(HostId, Port, VarIdList, ValueList,
Community, 15, Version, SysUpTime, Enterprise, GenericTrap,
SpecificTrap, NULL);
Example 2
The following example shows how to send an SNMP v2 notification to a manager
using SnmpTrapAction. SNMP v2 requires that you specify an SNMP trap OID
when you call this function.
// Call SnmpTrapAction
HostId = "localhost";
Port = 162;
Version = 1;
Community = "public";
SysUpTime = 1001;
Enterprise = ".1.3.6.1.2.1.11";
GenericTrap = 3;
SpecificTrap = 0;
VarIdList = {".1.3.6.1.2.1.2.2.1.1.0", "sysDescr"};
ValueList = {"2", "My system"};
SnmpTrapOid = ".1.3.6.1.2.4.1.11";
SnmpTrapAction(HostId, Port, VarIdList, ValueList,
Community, 15, Version, SysUpTime, Enterprise,
GenericTrap, SpecificTrap, SnmpTrapOid);
Chapter 9. Working with the SNMP DSA
125
126
Netcool/Impact: DSA Reference Guide
Chapter 10. Working with the ITNM DSA
The ITNM DSA is a Direct Mode, bi-directional DSA that is used to send queries to
the Netcool/Impact ITNM application and get the results of those queries.
ITNM DSA overview
The ITNM DSA is a Direct Mode, bi-directional DSA that is used to send queries to
the ITNM application and get the results of those queries.
After you set up Netcool/Impact and install the DSA, you can read the data in a
policy using the GetByFilter function. The DSA can also receive asynchronous
messages from ITNM regarding alerts.
The ITNM DSA requires ITNM version 3.8 or higher.
For more information about ITNM hardware and software requirements, see the
Tivoli Network Manager IP Edition Knowledge Center at http://www-01.ibm.com/
support/knowledgecenter/SSSHRK/landingpage/product_welcome_itnm.html.
Setting up the DSA
The drivers required to connect Netcool/Impact to ITNM version 3.8 and 3.9 are
available in $NCHOME/integrations/itnm in your Netcool/Impact installation.
v To connect to ITNM 3.8 use, ncp_j_api-3.8.0.50.jar.
v To connect to ITNM 3.9 or higher use, ncp_j_api-3.9.0.32.jar.
For the version of ITNM you want to receive events from, complete the following
steps:
1. Copy the appropriate jar file from $NCHOME/integrations/itnm and place it in
$NCHOME/dsalib folder.
2. Restart the Netcool/Impact server.
3. If you are running in a clustered mode, repeat this step for each server in the
cluster.
To set up the ITNM DSA, complete following tasks:
1. Edit the precisiondsa.properties file. For more information about this task,
see “Editing the DSA properties file” on page 128.
2. Configure the ITNM Event Listenerservice for the DSA (optional). For more
information about this task, see “Running the ITNM event listener service for
the DSA” on page 128.
3. If you plan to receive asynchronous events from ITNM, start the ITNM Event
Listener Service.
A preconfigured data type, data source, and two sample policies are included in
Netcool/Impact.
© Copyright IBM Corp. 2006, 2015
127
Editing the DSA properties file
Procedure
1. After you set up the DSA and restarted the server, you must edit the
precisiondsa.properties file, which you can find in the directory
$IMPACT_HOME/dsa/precisiondsa.
2. The following image shows an example of the ITNM DSA properties file. Edit
the information as required to connect to the ITNM Listener Daemon, following
the instructions in the file.
Running the ITNM event listener service for the DSA
The ITNM event listener service is preconfigured in Netcool/Impact. When the
INTNM DSA is set up you can log in to Tivoli Netcool/Impact and, run the
ITNMEventListener service available in theServices node for the ITNM project.
This step is optional. It is only necessary to set up an event listener service if you
want to listen for events asynchronously from IBM Tivoli Network Manager.
About this task
The ITNMEvent Listener service monitors a non-ObjectServer event source for
events. They typically work with DSAs that allow bidirectional communication
with a data source.
To run the ITNMEvent Listener service:
128
Netcool/Impact: DSA Reference Guide
Procedure
From the Project selection list, select the ITNM project.
Click the Services tab.
The ITNMEvent Listener service is displayed.
Enter the required information in new the Event Listener configuration
window.
5. If you want to view the preconfigured settings, right click the service and click
Edit.
v Listener Filter Leave this field blank
v Policy To Execute shows the ITNMSampleListenerPolicy that runs when an
event is received from the IBM Tivoli Network Manager application.
1.
2.
3.
4.
v Direct Mode Class Name this field is prepopulated
con.micromuse.dsa.precisiondsa.
PrecisionEventFeedSource
v Direct Mode Source Name this field is prepopulated with a unique name
that identifies the data source, for example, ITNMServer
6. Close the ITNMEvent Listener service tab.
7. To run the service, in the Services tab, select the ITNMEvent Listener service
and click the Start Service icon to receive events from IBM Tivoli Network
Manager. For information about IBM Tivoli Network Manager, see the IBM
Tivoli Network Manager documentation available from the following link,
http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/topic/
com.ibm.tivoli.namnmip.doc/welcome_nmip.htm.
ITNM DSA data type
The ITNM data type is the only one that works with the ITNM DSA.
You cannot rename an ITNM data type.
When the DSA queries the ITNM database, the records are returned as data items
of the ITNM data type. Each field in the records is turned into an attribute of the
corresponding data item.
For example, a record can contain fields such as:
v ObjectId
v
v
v
v
EntityName
Address
Description
ExtraInfo
To access the values, you can directly access the attributes just like any other data
items using the following command:
log("Description is " + DataItem.Description);
This command prints out the Description field string that was on the ITNM
record returned by the query.
Chapter 10. Working with the ITNM DSA
129
ExtraInfo field
Some fields that are returned by the query to IBM Tivoli Network Manager contain
a hierarchy with sub fields. One example in IBM Tivoli Network Manager 3.8 and
3.9 is the ExtraInfo field in the master.entityByName table, which has sub fields
such as m_BaseName and DNSName.
If you log the complex field as
log("ExtraInfo is " + DataItem.ExtraInfo);
you get a print out of the fields in ExtraInfo in a long String, like the following
example.
ExtraInfo is {m_AccessProtocol=, m_IfDescr=FastEthernet9/6,
m_BaseName=r6509-k02-1.b7199, m_LocalNbrVlan=601, m_IfSpeed=100000000}
Individual fields in ExtraInfo can be extracted by using string parsing in the
policy.
In the example the m_BaseName field could be obtained by extracting the portion of
the string between m_BaseName and the following comma using this command:
m_basename = rextract(DataItem.ExtraInfo, ".*m_BaseName=([^,]+).*");
In IBM Tivoli Network Manager 4.1 and 4.1.1 the master.entityByName table has
been replaced. You can access the entities with the ncimCache.entityData table.
This table contains several hierarchal fields similar to ExtraInfo, and the fields can
be extracted by using rextract in a similar way as described for the ExtraInfo
field.
Writing policies using the ITNM DSA
The ITNM DSA supports only the GetByFilter function. This function has three
components for the filter argument for this DSA, as described in Table 37.
Table 37. ITNM DSA Filter Arguments
Argument
Description
Subject
This argument specifies on what service the OQL query has been sent
to.
For MODEL, the value is RIVERSOFT.3.0.MODEL.QUERY.
Query
This is the actual query to be sent to the subject described in the
previous row. If this component exists, than all the records from the
subject will be retrieved.
Make sure that the OQL query contains NO " ' " characters.
Timeout
This is the timeout value for getting the results back. It uses the value
in the precisiondsa properties file if you do not specify the timeout
value in the filter.
GetByFilter
The GetByFilter function retrieves data items from a data type by using a filter as
the query condition.
130
Netcool/Impact: DSA Reference Guide
To retrieve data items using a filter condition, you call GetByFilter and pass the
data type name and the filter string as input parameters. The syntax for the filter
string varies depending on whether the data type is an internal, SQL database,
LDAP, or Mediator data type.
GetByFilter returns an array of references to the retrieved data items. If you do
not assign the returned array to a variable, the function assigns it to the built-in
DataItems variable and sets the value of the Num variable to the number of data
items in the array.
You can use GetByFilter with internal, SQL database, and LDAP data types. You
can also use GetByFilter with some Mediator data types.
Important: When data items are assigned to the built-in DataItem variable, they
are not immediately updated but are stored in a queue to optimize the number of
calls to the database. So, for example, if you update multiple fields in the
DataItems variable there will only be one call to update the underlying database,
when a function call is made. To force all queued updates, call the
CommitChanges() function in your policy. The CommitChanges() function does not
take any arguments.
Syntax
The GetByFilter function has the following syntax:
[Array =] GetByFilter(DataType, Filter, [CountOnly])
Parameters
The GetByFilter function has the following parameters.
Table 38. GetByFilter function parameters
Parameter
Format
Description
DataType
String
Name of the data type.
Filter
String
Filter expression that specifies which data items to retrieve from
the data type.
CountOnly
Boolean
Pass a false value for this parameter. Provided for
compatibility with earlier versions only.
Return value
Array of references to the retrieved data items. Optional.
Examples
The following example shows how to retrieve data items from an internal or SQL
database data type.
// Call GetByFilter and pass the name of the data type
// and an SQL database filter expression
DataType = "Admin";
Filter = "Level = ’Supervisor’ AND Location LIKE ’NYC.*’";
CountOnly = false;
MyAdmins = GetByFilter(DataType, Filter, CountOnly);
Chapter 10. Working with the ITNM DSA
131
The following example shows how to retrieve data items from an LDAP data type.
// Call GetByFilter and pass the name of the data type
// and an LDAP filter expression
DataType = "Customer";
Filter = "(|(facility=NYC)(facility=NNJ))";
CountOnly = false;
MyCustomers = GetByFilter(DataType, Filter, CountOnly);
The following example shows how to retrieve data items from a Mediator data
type.
// Call GetByFilter and pass the name of the data type
// and the Mediator filter exprssion
DataType = "SWNetworkElement";
Filter = "ne_name = ’DSX1 PNL-01 (ORP)’";
CountOnly = false;
MyElements = GetByFilter(DataType, Filter, CountOnly);
Writing policies to receive events from ITNM
The ITNM Event Listener Service that you optionally configured after installing
the DSA is similar to the OMNIbusEventReader, with the exception that it can
asynchronously receive events from ITNM.
Policy Variables
After an event is received, the policy assigned to it is invoked with the variables
described in Table 39. The variables are stored in the EventContainer and must be
referenced in the policy using the EventContainer or @ notation. See the
ITNMSampleListenerPolicy for an example.
Table 39. Variables Returned by a Policy after Event Received from ITNM
Variable
Description
ActionName
This variable describes the type of action that is in the update. The
possible values are:
v "REC_DELETE"
v "REC_UPDATE"
v "REC_NEW"
v "DontKnow"
FieldNames
This variable gives the names of the fields that are in the
CRIV_Record that is received from ITNM. Since the field names
returned in this record are not known before the policy is executed,
a string concatenation of all these fieldNames, with a delimiter of
"##", is used. This is a sample value in the FieldNames variable:
##Field1##Field2##Field3##field4 and so on.
132
Field1
One of the fields in the record returned by ITNM.
Field2
One of the fields in the record returned by ITNM.
Field3
One of the fields in the record returned by ITNM.
Field4
One of the fields in the record returned by ITNM.
Netcool/Impact: DSA Reference Guide
Sample policies
The DSA provides the following sample policies:
v ITNMSampleListenerPolicy
v ITNMSamplePolicy
ITNMSampleListenerPolicy
ITNMSampleListenerPolicy.ipl shows how to use the ITNM DSA to read data
from an ITNM Listener. The policy reads the contents of an ITNM formatted string
and then prints the data to the Policy log.
ITNMSamplePolicy
ITNMSamplePolicy.ipl shows how to use the ITNM DSA to read data from an
ITNM database. The policy reads the contents of an ITNM formatted string and
then prints the data to the Policy log.
Chapter 10. Working with the ITNM DSA
133
134
Netcool/Impact: DSA Reference Guide
Appendix. Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain
transactions, therefore, this statement might not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
© Copyright IBM Corp. 2006, 2015
135
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758 U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurement may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
136
Netcool/Impact: DSA Reference Guide
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at “Copyright and
trademark information” at www.ibm.com/legal/copytrade.shtml.
Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
Linux is a trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other product and service names might be trademarks of IBM or other companies.
Appendix. Notices
137
138
Netcool/Impact: DSA Reference Guide
Index
A
accessibility vi
adding JDBC drivers 7
authentication 64
with plain text password
65
handling a retrieved message
v
C
calling WSSetDefaultPKGName 43
categories of DSAs 3
changing character set encoding 8
compiler script
See Web services DSA
compiling WSDL files 34
Connecting to WebSphere MQ. 81
conventions
typeface ix
create data types scripts 88
creating a message properties context 79
Creating an event listener service for the
DSA 128
creating message body string or
context 76
creating message properties context 75
creating UI data provider data
sources 17
creating UI data provider data types 19
customer support vii
customizing
failover 15
D
data items 30
data model 4, 17, 29
data source 17
data source adapter
ITNM 127
JMS 69
data sources 17
JMS 70
LDAP 29
SQL database 8
data type
table 103
data type mapping 86
data types 19, 30
definition of DSAs 3
directory names
notation x
DSA
XML 85
DSAs
categories 3
© Copyright IBM Corp. 2006, 2015
Editing the DSA properties file
education
See Tivoli technical training
element data types 86
Enabling and disabling proxy
settings 35
encrypt messages
See Web services security
encryption
See Web services security
environment variables
notation x
even readers 4
event listeners 4
ExtraInfo field 130
79
I
E
B
books
see publications
DSAs (continued)
definition 3
even readers 4
event listeners 4
policies 5
128
integration with third party Web
services 57
ITNM DSA data type 129
ITNMSampleListenerPolicy 133
ITNMSamplePolicy 133
J
JMS
data source 70
JMS data source 72
JMS DSA
creating a message properties
context 79
creating message body string or
context 76
creating message properties
context 75
handing incoming messages from a
JMS message listener 80
handling a retrieved message 79
overview 69
retrieving JMS messages from a topic
or queue 78
sending messages to JMS topic or
queue 74
setting up OpenJMS 70
setting up the JMS DSA 69
writing JMS DSA policies 74
JMS DSA policies
writing 74
JNDI properties 72
F
failback 14
failover 13
configurations 13
customizing 15
defaults 14
setting up 14
standard 13
fixes
obtaining vi
function
GetByFilter 131
ReceiveJMSMessage 78
SendJMSMessage 75
SnmpGetAction 113
SnmpGetNextAction 117
SNMPSetAction 121
WSInvokeDL 39
WSNewArray 38
WSNewEnum 42
WSNewObject 37
WSNewSubObject 37
WSSetDefaultPKGName 36
functions 36
L
LDAP data sources
creating 29
LDAP DSA
data items 30
data model 29
data types 30
international character support
overview 29
policies 31
retrieving data 31
supported LDAP servers 29
32
G
GetByFilter 131
GetByFilter output parameters
19
H
handing incoming messages from a JMS
message listener 80
M
manuals
see publications v
Mediator DSAs 3
message body string or context
message integrity
See Web services security
76
139
message properties context
75
N
non-repudiation
See Web services security
notation
environment variables x
path names x
typeface x
nternational character support
See LDAP DSA
O
obtaining WSDL files 34
online publications
accessing v
OpenJMS 70
ordering publications vi
P
path names
notation x
plain text password
See authentication
policies 5, 31, 43, 49, 74
sample 54
using editor 56
using wizard 55
Policy Variables 132
problem determination and
resolution viii
process 46
publications v
accessing online v
ordering vi
R
ReceiveJMSMessage 78
retrieving data 22
retrieving JMS messages from a topic or
queue 78
Retrieving packed OID data with SNMP
functions 110
run Policy 52
run Policy Response 53
runtime parameters 49
S
Sample policies 133
sending messages 43
to JMS topic or queue 74
SendJMSMessage 75
service
JMS message listener 73
setting up
failover 14
JMS DSA 69
Web services listener 47
Setting up the DSA 127
140
sign messages
See Web services security
SNMP DSA
data model 97
data sources 97
creating 100
deleting 102
editing 102
data types 98
creating 102
deleting 104
editing 104
functions 113
policies 104
retrieving packed OID data 108
retrieving table data from SNMP
agents 111
sending traps and notifications 112
setting packed OID data with SNMP
functions 108
setting packed OID data with
standard data-handling
functions 105
traversing SNMP trees 110
SNMPGetAction 113
SnmpGetNextAction 117
SNMPSetAction 121
SNMPTrapAction 124
SOAP endpoints 51
Software Support
contacting vii
overview vi
receiving weekly updates vii
SQL database DSA 7, 8
SQL database DSAs 5
adding data 10
calling database functions 12
calling stored procedures 12
customizing failover 15
data items 9
data model 8
data types 9
deleting data 11
failback 14
failover 13
failover configurations 13
failover defaults 14
list of provided 5
modifying data 11
policies 9
retrieving data 10
setting up failover 14
standard failover 13
SSL 55
super data types 86
supported LDAP servers 29
T
Tivoli Information Center v
Tivoli technical training vi
training
Tivoli technical vi
typeface conventions ix
Netcool/Impact: DSA Reference Guide
U
UI data provider data model 17
UI data provider data source 17
UI data provider data type 19
UI data provider data types 19
UI data provider DSA 17, 19
UI Data Provider server cache 25
uidataprovider data source 22
V
variables
notation for
x
W
Web Service Listener 55
Web services DSA 33
calling WSSetDefaultPKGName 43
compiling WSDL files 34
creating policies using editor 56
creating policies using wizard 55
examples 44
functions 36
integration with third party Web
services 57
obtaining WSDL files 34
overview 33
policies 43
running the WSDL compiler
script 34
sample client 54
sample policies 54
sending messages 43
SOAP endpoints 51
Web services listener 46, 47, 49
writing applications that call into Web
services 51
WSDL file 52, 53
WSListenerResult 49
Web services listener
process 46
runtime parameters 49
setting up 47
writing policies 49
Web services security
enabling 59
encryption 66
message integrity and non-repudiation
with signature 65
sign and encrypt messages 66
user name token authentication 64,
65
WebSphere MQ 81
writing
Web services listener policies 49
writing applications that call into Web
services 51
Writing policies to receive events from
ITNM 132
Writing policies using the ITNM
DSA 130
WSDL 47
WSDL file 52
message 52, 53
WSDL files 35
WSInvokeDL 39
WSListenerException 53
WSListenerResult
See Web services DSA
WSListenerResult variable 50
WSNewArray 38
WSNewEnum 42
WSNewObject 37
WSNewSubObject 37
WSSetDefaultPKGName 36
X
XML configuration files 86
XML documents 85
XML DSA
create data types scripts 88
data type mapping 86
overview 85
reading XML data 91
sample policies 94
XML configuration files 86
XML data types 85, 86
creating 87
setting up mappings 89
XML documents 85
XML DTD files 85
XML mapping 86
XML XSD files 85
XML DTD files 85
XML XSD files 85
Index
141
142
Netcool/Impact: DSA Reference Guide
IBM®
Printed in USA
SC27-4919-02