BSM Connector Developers Guide 0

HPBusiness Service Management
For the Linux and Windows operating systems

Software Version: 9.22
BSM Connector Developer's Guide for Integrations
Document Release Date: November 2013

Software Release Date: May 2013
Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be
construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.
Restricted Rights Legend

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer
Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial
license.
Copyright Notice
Copyright 2012-2013 Hewlett-Packard Development Company, L.P.
Trademark Notices
Adobe and Acrobat are trademarks of Adobe Systems Incorporated.
AMD and the AMD Arrow symbol are trademarks of Advanced Micro Devices, Inc.
Google and Google Maps are trademarks of Google Inc.
Intel, Itanium, Pentium, and Intel Xeon are trademarks of Intel Corporation in the U.S. and other countries.
iPod is a trademark of Apple Computer, Inc.
Java is a registered trademark of Oracle and/or its affiliates.
Microsoft, Windows, Windows NT, Windows XP, and Windows Vista are U.S. registered trademarks of Microsoft Corporation.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
UNIX is a registered trademark of The Open Group.
Acknowledgements
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This product includes software developed by the JDOM Project (http://www.jdom.org/).
This product includes software developed by the MX4J project (http://mx4j.sourceforge.net).
Documentation Updates
The title page of this document contains the following identifying information:
l
l
l
Software Version number, which indicates the software version.

Document Release Date, which changes each time the document, is updated.
Software Release Date, which indicates the release date of this version of the software.
To check for recent updates or to verify that you are using the most recent edition of a document, go to: www.hp.com/go/livenetwork. This site requires that you register
for an HP Passport and sign in. To register for an HP Passport ID, go to: http://h20229.www2.hp.com/passport-registration.html
Or click the New users - please register link on the HP Passport login page.
Support
This document is part of the HP Live Network Community Content. Hewlett Packard Software does not test, certify or support Community Content. Please use the
Community Content discussion forums on HP Live Network or contact the original submitter of the Community Content directly if any support, configuration or usability
questions arise.
To access the Community Content discussion forums, go to: https://hpln.hp.com/node/14127/og/forum.
Please back up all appropriate Business Service Management files before applying Community Content in your environment.
HP Business Service Management (9.22)
Page 2 of 30
Contents
Chapter 1: Introduction
Chapter 2: Integration Basics
Data Types and Data Exchange
OMi/BSM Data Handling
BSM Connector Data Handling
Collectors
How to Collect Data
When to Collect Data
Policies
Custom Topology Policy
Installation
9
10
10
Package Naming
11
File Placement
11
Chapter 3: Event Channel

Event Collection
Rollover Mechanism
13
13
15
Event Mapping
15
BackSync
16
Event Drilldown
17
Tips and Tricks
18
Chapter 4: Topology Channel
19
Topology Collection
20
Topology Mapping
23
TopoSync-based Mapping
Tips & Tricks
Chapter 5: Metric Channel
25
27
28
Metric Data Collection
28
Metrics Mapping
30
Tips & Tricks
30
Page 3 of 30
Chapter 1: Introduction
This guide is for anyone who would like to create an integration for BSM.
You should already have an understanding of the basic concepts of HP BSM OMi and the HP BSM
Connector. You need to build the knowledge of integrations and their development process on this
foundation. The following sections introduce the concepts behind integrations, and the technical
details and best practices about how to create them. Please note that the concepts of creating
integrations and how integrations work are described generically. The application of these concepts
for a connector implementation may very much dependent on the nature of the third-party product to
be integrated and might require alternative solutions to those described. Therefore, some
experience in programing is essential.
The guide is divided into the following sections:
1. "Integration Basics" on page 5
2. "Event Channel" on page 13
3. "Topology Channel" on page 19
4. "Metric Channel" on page 28
Page 4 of 30

Integrations act as a mediator between two heterogeneous domain managers, transferring event,
topology and metric data from a third-party domain manager to HP Business Service Manager
(BSM) and its components.
BSM Connector integrations work in conjunction with HP BSM Connector (BSMC), which performs
the complex mapping of versatile forms of data and then sends this data, using a common format,
to the appropriate component of BSM. BSMC can be regarded as the general part of the data bus for
the BSM server. The specific part of the data bus required to communicate with a particular thirdparty domain manager is provided by the integration itself.
The integration collects data from a third-party domain manager and exposes it in a predefined way
so that it can be read by BSMC. The whole process, from the third-party domain manager to the HP
BSM server can be viewed as a pipeline, where each of its components: third-party domain
manager, the integration, BSM Connector and the HP BSM represents one stage in it.
An integration or connector consists of two parts:
Collectors
Collectors acquire data from the third-party domain manager, process this data, and forward it using
a consistent structure to BSM. For more details, see "Collectors" on page 7.
Policies
Policies are responsible for the mapping of data provided by the collector into the form understood
by BSM. Usually, an integration provides a set of policies which are installed to BSMC and are
already configured to map different types of data into the expected final structure. Those policies
can be easily extended by the user, if required. For more details, see "Policies" on page 9.
An Integration in the Data Transfer Pipeline between a Domain Manager and BSM/OMi:
Page 5 of 30

Data Types and Data Exchange

Integrations collect different types of data and transfer it (using BSMC) to the appropriate BSM
component:
l
Event data is directed to OMi (Operations Management)
Topology data is directed to RTSM (Real-Time Service Model)
Metric data is directed to PMi (Performance Manager) or SAM (System Availability Manager).
Each data-type has a dedicated receiver and must be handled (mapped) individually by the BSM
Connector.
OMi/BSM Data Handling

The OMi event server is one of the key components of BSM. It displays to its operators an overview
of the state of the monitored infrastructure - nodes, applications installed on them, and their
resources.
Data about the state of the infrastructure is collated in the form of events, which are stored in the
"Event Database". Each event contains a list of attributes (key-value pairs) which are displayed in
their associated fields in the Event Browser, providing a better overview and easier manageability
of the monitored environment. Events can also contain additional indicators and hints that add
additional value to the contained data and enable OMi to relate such events to an appropriate object
in the topology.
You can find more information on OMi in the Business Service Management Using Operations
Management guide.
BSM Connector Data Handling

BSM Connector can be regarded as a general bus that can deliver multiple types of data to the BSM
server in the format that the BSM server understands. Its concepts can be split into two
complementary groups:
l
Processing and mapping of generic data into BSM's native form using policies
Policies are sets of rules that define how a particular data source (for example, an XML file, a log
file, or a database) should be read and how its data can be mapped so that BSM can understand
it. Various BSMC web UI policy editors are available to aid working with policies.
Transfer of data to the BSM server and its components

Transfer of data to the BSM server and its components requires BSMC to be connected to a
BSM server. If a particular data type has been mapped, it is sent to the designated component of
the BSM server. No further interaction for the integrator is required.
More information is contained in the Business Service Management Connector User Guide.
Page 6 of 30

Note: All BSM and BSM Connetor guides can be found in the HP Software Product Manuals
repository, under the product "Operations Manager i".
Collectors
Collectors represent one or more processes that collect data from a third-party domain manager
(domain manager). Their design is highly dependent on various factors including:
l
Full or Lightweight Collector

When a full integration, with a broad version support for a domain manager is developed, it is
designed around the domain manager communication method chosen.
The lightweight integration usually relies on a more direct data collection method, such asan
SNMP trap, reading of log files, direct SQL queries of database (see Database below). It is
easier and faster to develop direct data collection, but as mentioned below,has the risk of not
working with a newer version of the domain manager or at least require some configuration
(policy) changes.
Domain Manager Version Range

Support a single, specific version of a domain manager or a broader version range.
Development Effort
Time and resources available to develop the integration.
How to Collect Data

When investigating the implementation options available,work throughthe following list.This is the
usual order in which to evaluate the implementation options. Generally,the higher the
implementation abstraction level (level of implementation, and higher in the following list), the more
consistency there is and, usually,more documentation is available.
l
SDK -A set of libraries that can be integrated with the collectors. This is the recommended way,
as they usually provide detailed instructions on how to collect data and guarantee consistency
across multiple versions of the domain manager. However, the number domain managers
providing theseSDKs is very low.
Web Service - Some domain managers provide a web-service interface using which the
required data can be acquired. Remote communication is already implemented and consistency
is usually similar to that of an SDK. However, functions are usually less well documented,
providing a lower level of detail. There may also be a much higher communication overhead. For
example, you might need to request additional data for each item in list of items.
Extensions/Add-Ons/Plug-ins - Some domain managers enable extension of their

functionality using extension frameworks. Such frameworks usually provide access to data in
its database, with the benefit of the raw data being abstracted and presented as higher-level data
structures, so they are easier to read and provide some consistency. This framework, however,
is usually not designed for the export of data, but to extend what data can be collected by the
Page 7 of 30

domain manager. As a result, multiple concepts might need to be combined for the extension to
work as a collector. Typically, documentation describing how to access the database is
available from the domain manager producer, and examples can often be found on the Internet.
l
Event Forwarding (only for event data) - If the domain manager includes event forwarding
functionality, it can usually be used to forward all events. Bear in mind that in some cases,
performance might be limited due to the functionality having only been provided to send
exceptional/critical events to alert operators/administrators and not designed to send a large
volume of events. Another limitation might be that only new events are forwarded, but not
changes to events, for example, if the states of events change or if operators add instructions.
Dump/Export Tools - If the domain manager provides any tools to dump or export the required
data, the collector can periodically request the dump or just read the dumped data provided by a
scheduled task and processes it. Relying on dumped data comes with some risks, particularly
as the format of dumped data might be changed even as a result of a minor version change.
Additional effort is needed to handle the various versions of the domain manager. Typically,
there is limited or no documentation on the structure of the data in the dump and it needs to be
examined in detail.
Data Bus Interception - Some domain managers include functionality that allows the collector
to listen to the domain managers data-inflow bus, which provides a copy of the event at the
same time or even before it reaches the domain manager. This is fine for collecting events, and
possibly topology or metrics, but there is the risk of only getting partial data. If the data received
by the domain manager is enhanced using some internal business logic, these enhancements
will not be available to the collector. It is also not always possible to get the event ID from
messages that have not been written to the domain manager database. There might also be the
added problem of the in-flow data not being consistent. For example, the domain manager might
support older message syntax, and the collector would have to be able to read those as well.
Database - Data is either stored using a common database application or simply in plain files.
The database being used by the domain manager can usually be determined from the domain
manager installation guide (prerequisites). However, implementing a collector to directly read
from the database is fraught with problems. The biggest being that column names often change
even between minor versions of the domain manager, making it extremely onerous to support
multiple versions.
When to Collect Data

Ideally, the domain manager would actively contact the collector when a change is identified,
minimizing the delay experienced by the collector. This also requires an asynchronous data
collection because you must be able to start a new collection at any time, even if the previous
collection is still running. The only two concepts that come close to this active approach are Event
Forwarding and Data Bus Interception. Neither is common, so data is usually collected periodically,
for example, every 30 seconds.
Microsoft SCOM requires you to acknowledge each event you processed each time it changes.
Zenoss, on the other hand, allows only the collection of events using a query where you can define
a filter for all events in the database. The time of the last collection must be used to create such a
filter so that only events that were received or changed after that time are collected.
Page 8 of 30

The polling concept usually also implies that the collector is a Windows Service or a UNIX daemon,
because it needs to run all the time. But there are also reasons why the collector is usually designed
as an always-running process.
After the data is collected, it is processed (the required processing is determined by the nature of
the domain manager and on the type of data), and written to an output sink (for example, an XML
file). Output type and format depend on the data type and the policy type used. More details on
output writing are discussed in the "Event Channel" on page 13, "Topology Channel" on page 19,
and "Metric Channel" on page 28 pages.
Policies
A policy consists of two parts:
l
Named container for settings that define where and how the policy should get and read data from
a data source.
Set of rules that define how to process different entries from the data-source.
Policies are managed by BSM Connector and are accessed using its web-based user interface,
which can be opened in a web browser using the following URL:
https://<bsmc_hostname>:30000/bsmconnector
Currently, the following data sources can be used:
l
Structured log file
XML file (similar to a normal XML file but with multipleroot tags)
Database
SNMP trap
Web-service received data
All data sources can be used for each data type (event, metric or topology), except for the XML file
and SNMP, which are specifically intendedfor event data. All policy types are defined based on the
data source type.
Page 9 of 30

Data Sources in BSM Connector:
Note: The XML file data sourceis similar to a normal XML file, with the distinction that theroot
tag is replaced with a root tag for each entry.
When a collector writes collected data to a data source, it must ensure that the data source is one
of those listed above. The exception is the custom topology policy (see below).
Custom Topology Policy

The custom topology policy is a policy type that does not define any specific data source. It is
intended for reading the topology data type by defining a blank Jython script which can be set to
read and process data in any form that is supported by the programing language.
If a collector needs to write collected data to a custom topology policy data source, the whole
business logic for mapping and creating of the data type, native to BSM, needs to be reimplemented. Therefore, it is recommended to use other types of policies if at all possible.
Installation
In general, there are no strict guidelines on how to package an integration. It is recommended that
the complete integration is contained in one installer. If some files or components need to be
installed on a remote, third party domain manager, these are then manually copied to the remote
system by the user.
Each integration should aim to cover as many platforms as possible, therefore, multiple platform
native installers should be created. This is not always possible, for example, when an integration is
supported on one type of platform only. The collector of BSM Connector for Microsoft SCOM is
Page 10 of 30

written in C# using the Microsoft SCOM SDK, which has official support on Windows platforms
only. As a result, only the Windows installer was created for that integration.
Package Naming
When it comes to naming of packages that contain the integration (usually in the form of an
installer), HPapplies thefollowing naming scheme:
HpBsmInt_<integration_name>-<version>-<platform>.<extension>
Examples:
HpBsmIntZenoss-1.0.91-Win5.2_x64.msi
HpBsmIntZenoss-1.0.91-Linux2.6_x64.rpm
File Placement
While the various aspects of an integration installer are flexible and can be adjusted to best suit the
third-party domain manager, the installation location of the files on the BSMC system must follow
these guidelines.
There are three system/environment variables that are used when file placement is defined:
l
BSMC_HOME
n
Windows: C:\BSMConnector
Note: Can be re-defined by user during BSMC installation.
Linux: /opt/HP/BSMConnector
OvInstallDir
n
Windows: C:\Program Files\HP

Note: Can be re-defined by user if the Operation Agent is pre-installed to a non-default
location.
Linux: /opt/OV
OvDataDir
n
Windows:
Note: Can be re-defined by user if the Operation Agent is pre-installed to a non-default
location.
Page 11 of 30

Windows 2003: C:\Documents and Settings\AllUsers\HP\HP BTO Software
Windows 2008: C:\ProgramData\HP\HP BTO Software
Linux: /var/opt/OV
These variables are created during the BSM Connector installation.

Note: These environment variables do not exist on the Linux platform, but are used to express
the full file path on all platforms.
When the installer installs the integration, it should unpack all files to:
%OvDataDir%\installation\<package_name>
The %OvDataDir%\installation folder already exists if you have a valid installation of BSMC.
The <package_name> must be created by the installer before it starts unpacking the files. After the
files are unpacked, they should be copied to their designated locations.
All variable data (configuration, log files, output files) of the integration should be placed in the
following folder. There are no restrictions to the organization of files and folders within this folder.
%OvDataDir%\datafiles\<package_name>
All binaries of the collector (if it is installed on the BSMC system) should be placed in:
%OvInstallDir%\bin
The BackSync script must be called OMBackSync.pl and placed in:
%OvDataDir%\conf\backsync
BSMC currently supports only one BackSync script per installation. When BSMC is installed, it
copies a placeholder/dummy script to that location. If another script from an integration should be
used, the original script must be renamed, (for example, to OMBackSync_dummy.pl) and only after
that, should the integration installer copy its own script to the %OvDataDir%\conf\backsync
location.
If there is already an integration installed and still required, its script must not be removed. The user
must manually merge the two scripts.
If any additional perl libraries are used by the BackSync script, they should be placed into the
following folder:
%OvInstallDir%\nonOV\perl\a\lib\curr
The package must also contain policies that map the different types of data that we want to transfer
to HP BSM. The policies should remain in the "installation" folder. The user should use the BSMC
UI "Import" functionality and import them from that location.
Optionally, if the integration uses the local TopoSync component of the BSMC, a suitable name for
the sync-package needs to be used. Usually, it is <integration_name>Topology, for example,
SCOMTopology. The sync-package must be placed in the %BSMC_HOME%\conf\topology\xml
folder.
Page 12 of 30

Events represent one of the three data-types that are currently supported by the BSM Connector. In
the context of an integration, the BSM Event Channel transfers events (all or a configured sub-set
of them) from a third-party domain manager to the OMi server of BSM. It is encouraged to get and
map all available event data (in the form of attributes and values) because each additional piece of
information you can retrieve from the third-party domain manager is additional data available to the
OMi operator working on the issue reported by the event. Some attributes can also be used by OMi
to further reduce effort required from the operator to resolve a reported issue.
There is one functionality that distinguishes this channel from the other two - currently it is the only
one where data flows in both directions (see section "BackSync" on page 16).
Note, not all functionality described here is required to create a simple integration, but with each
additional functionality, you add value to each event or increase the ease-of-handling of events.
Event Collection
Events are usually collected in one of two ways:
l
Actively - The collector periodically executes a method - a request to a web service to provide
all events received since the last request. The request returns a list of events. After the list has
been generated, each event in the list is processed.
Passively - The collector is in a stand by mode, waiting to receive a new event. When the
domain manager forwards a new event to the collector, it receives it and processes it
immediately.
Each event is then processed in the same way. Usually, events are printed in an XML file format,
so that the XML file policy can be used. The XML file policy must reside on the same system as
BSMC.
The XML file policy provides the easiest way of creating complex mapping of events. It requires the
XML output file to be formatted a little differently to normal there is no root tag, rather each event is
appended to the output file and has its own root tag (root tag name is the same for each event, for
example, SCOM_Alert or MyDM_event). The root tag contains sub-tags, which represent the
attribute-key/value-pairs of the message.
Example:
MyDM already has an event (written in the output file), but now receives the following events:
l
Message with ID A with text This is a short message, created on 4th Mar 2013, 12:15:31
Message with ID B with text Another alert message, created on 4th Mar 2013, 13:01:48
Page 13 of 30

These two events are appended to the output file as follows:

<?xml version="1.0" ecoding="UTF-8" ?>
<MyDM_Event>
<id>X</id>
<text>This is an old event</text>
<created>2nd Mar 2013, 23:56:12</created>
</MyDM_Event>
<MyDM_Event>
<id>A</id>
<text>This is a short message</text>
<created>4th Mar 2013, 12:15:31</created>
</MyDM_Event>
<MyDM_Event>
<id>B</id>
<text>Another alert message</text>
<created>4th Mar 2013, 13:01:48</created>
</MyDM_Event>
Note: The MyDM_Event root tag is chosen as an example. The root tag does not need to
follow any rules butshould be descriptive, for example,indicating that it is an alert, event or
message from a domain manager.
Sample Code for Collecting Events:
event_list = get_events(last_collection_timestamp)
last_collection = datetime.now()
if len(event_list) > 0:
output_file = open(output_path, "a")
for event in event_list:
output_file.write("<my_event>\n")
full_event = process_event(event)
for attribute in full_event.attributes:
output_file.write("<" + attribute.key + "><![CDATA[" + attribute.val
ue + "]]></" + attribute.key + ">\n")
output_file.write("</my_event>\n")
output_file.close()
Page 14 of 30

Rollover Mechanism
Each new event is appended to the end of the XML output file. When the output file reaches its
configured limit, the full output file is renamed and now acts as the event buffer and replaced by a
new, empty output file to which the integrations collector (writer process) continues to write new
event data. The output file is read by the BSMC reader process, which is controlled by the
integration's policy. The reader process starts from the oldest file in the buffer and only switches to
the next newest file when it has processed all events in the first buffer file. This is mechanism is
known as rollover and is required because the reader and writer processes are completely
independent of each other and cannot communicate with each other. The writer process should not
remove events from the output file as it cannot ascertain whether the reader process has processed
all the older data.
You can use multiple files to increase the size of the buffer. Typically, 5 files of identical maximum
size are configured. Every time a new file is required, all active files in the buffer must be rolled
over. If all configured files are in use, and the latest file becomes full, the oldest file must be deleted,
all the files in the buffer and the output file rolled-over, freeing the output file for further events.
Note: Currently, only the Event XML File policy is capable of reading/handling rollover files.
The phrase <*> can be used to determine the dynamic part of the file name. For example:
"myoutput.xml<*>" would make it read "myoutput.xml", "myoutput.xml.1",
"myoutput.xml.2", and so on.
Event Mapping
We have no control over the format of the data used by a third-party domain manager, for example,
a Java class (format DM domain manager). This data is collected and written to the output in a
format that the BSMCs data-source reader can consume, for example, XML structure (format TR transfer). The conversion to a BSMC-compatible format should be simple - each attribute in format
DM should be represented as a key-value pair in format TR.
There are two guidelines that should be followed during this conversion:
l
Each structure in format TR should be consistent. It should contain all possible attributes, even
if some of them are not part of the object in the format DM. For such cases, set the attribute's
value to an empty string.
Try to get as many attributes of each object in format DM as possible (you never know what
another user would like to have mapped).
Data written in format TR is now accessible to one of the BSMC reader processes (for example,
XML interceptor. You now need to provide the reader with instructions on where to find that data (for
example, file path), and how to use and process that data into a form that BSMC can send to BSM
(format BSM).
Page 15 of 30

Mapping refers to the process of relating of a pair of attribute names between format TR and format
BSM which can be executed as follows:
1. Identify an object.
2. For each attribute of the object, read its value in format TR and use it to fill in the associated
attribute in format BSM.
For example, take the attribute from the object O with name text in format TR and use it to fill in the
attribute MSG_TEXT in format BSM.
Formats TR and BSM are, from the perspective of a reader process, predefined. Mapping is
performed for every object, so only the two attribute names from formats TR and BSM are the parts
that change.
Note: Mappings discussed so far are mappings in the global sense and are not directly related
to the Mappings in the XML file policy. Mappings in the global sense copy data from one source
and paste it to the other. Mappings in the XML file policy, however, deal with specific situations
- when a third-party domain manager has used a set or a range of values for a particular
attribute, BSM uses another set or range. In that case, the controls inside the Mappings tab
can be used to define how to map one set or range to the other.
This last part, conversion fromformat TR to format BSM is split further into two mapping instruction
groups:
l
Defaults - Defines how each event is mapped by default if no additional rules define it.
Rules - Set of additional rules (in addition to the defaults), that try to identify specific event types
(for example,all event types that have the RelatedObjectType attribute set to MSExchange),
thus identifying additional properties which let you set some attributesin amore precise way
compared to the default mapping. Each rule can set additional mappings or override already
existing mappings thatare inherited from the defaults.
Note: In this context, the format BSM is already the BSM native event format, so the policy
just defines how to fill in the various attributes of the event that is then sent toBSM.
More details on how to edit policies can be found in the "BSMConnector User Guide".
BackSync
The majority of the integration functionality deals with getting data from the third-party domain
manager to the HP BSM. BackSync functionality is required to update the data available on the
third-party domain manager. After the events are received by BSM, and displayed in the OMi Event
Browser, operators will be working on and resolving the issues reported by the events. Resolved
events are closed in OMi, and should also be closed in the source manager. BackSync is used to
close events on the third-party domain manager that have been closed in OMi.
When an operator closes an event in OMi and the event has a value for the Source Event ID, OMi
provides the BSM Connector with this Source Event ID. In our case, the source is the third-party
Page 16 of 30

domain manager from which the event originated. The Source Event ID is the event ID used by the
third-party domain manager to identify the original event. The BSM Connector calls the BackSync
script, written in PERL, which is executed with only one parameter - the source event ID.
There are no limitations to the contents of the PERL. However, it must take the source event ID
provided as the parameter and send it to the source third-party domain manager, where a closure of
the event is requested. That is usually done by creating a specific URL.
The BackSync script must be located at:
%OvDataDir%\conf\backsync\OMBackSync.pl
Because the script's path is fixed, there are certain aspects that need to be taken care of during
installation or if the user wants to use multiple integrations with one BSM Connector. Those
considerations are discussed in "Installation" on page 10.
BSMC provides a template script for BackSync. That script only reports the arrival of a request
from BSM, but does not actually close it anywhere. However, the script is a good starting point for
developing a the BackSync script.
Event Drilldown
Unless the third-party domain manager possesses very limited functionality or uses a very similar
model to represent event data as used by OMi, there will always be some discrepancies between
the data contained by the event in third-party domain manager and the data available to OMi after
forwarding to OMi.
If data of interest was not initially forwarded to OMi, you can access this as long as the following
two conditions are fulfilled:
l
Third-party domain manager provides the functionality to access/show event data via a Web
Console.
Event policy sets the Event Drilldown field value to the URL of the event inside that web
console.
To access this functionality, select an event that possesses this functionality, right-click it (to open
its context menu), select Show > Event in Source Manager.
Page 17 of 30

Event Drilldown Menus:
In addition, you can access the event drill down URL (including the source event ID)to the thirdparty domain managerfromthe Forwarding tab in the OMi Event Browser.
Event Drilldown URL:
Tips and Tricks

OMi provides theRESTful web service which you canuseto generatea list of received events in
different contexts at: http://<bsm>/opr-web/rest
Page 18 of 30

Topology objects in the BSM world are used to correlate other data types (events or metrics), so
more advanced processing of it can be performed or displayed in a more intuitive way. They are
created and stored in the RTSM database, where such an object is called a CI.
To relate these other data types to their related CI, it must provide additional information to the
related topology object. This information is called a CI Hint. CI Hint values must uniquely identify
an object inside the RTSM. This implies that the topology object must already be in the RTSM.
Event, metric and topology data are sent via separate channels to dedicated processing
components and stored in three different databases. The aim is to have an interconnection between
topology objects and the events and metrics data types. It is not possible to relate to a topology
object if it is not stored in the RTSM. Therefore, it is essential that the full topology is always
available. As a result, the topology data collector always tries to discover the full set of topology
objects.
The volume of topology object data that needs to be sent to the RTSM can be very high, creating
heavy network traffic and processing loads on the RTSM. To minimize these loads, the BSM
Connector uses a mechanism which filters out unchanged objects and sends only those that have
changed since the last transfer. This is done behind the scenes and without any interaction required
by the user. The exceptions being the first transfer of the topology data or after the cache/filter is
forcefully cleaned, when there is no previous data set available, and the complete data set must be
sent.
The third-party domain manager usually uses a database to store the topology objects. If possible,
the integration extracts the topology data directly from that database. In this way, the complete
topology is already available before we start sending the event and metric data to BSM. If topology
data is not stored in a database or the database does not allow simple access to its topology data, it
might be possible to create the topology directly from the event or metric data, if you get all key
attributes of a CI before you try to create a database object in the RTSM. You must also have a
node CI (create it if it does not exist), to which this database object is related. This approach is
usually used to create nodes and their directly related components (event or topology data in most
cases does not contain any additional attributes).
Transfer of topology data to BSM is achieved using a Jython script (programmatic approach) that
imports the DDM API Java classes. It is capable of creating structures that the RTSM uses to
create its CIs. To simplify the mapping step in this process, a local TopoSync library is provided by
the BSM Connector (version 9.21 and later). The local TopoSync library enables the mapping of
complex topologies using rules based on a predefined set of operations, written in XML. While the
rules in XML do adhere to a XML schema which defines its syntax, they can be checked on-the-fly
against that schema.
Conversely, Jython is the preferred way to perform mapping of simple topologies, where objects
have only one relationship to the object above it and are spread across only a few levels.
Page 19 of 30

Topology Collection
Instant discovery of new events and metrics is regarded as very important. An event exists from
the time when a problem is discovered but the problem can only be addressed after the event is
displayed to the responsible operator. Therefore, collection and forwarding of event and metric data
to BSM should aim to keep any delays to a minimum.
Compared to event or metric data, topology objects are not considered time-dependent (or even
important over a short period). Topology object, such as a production SQL server or a location of a
company office, usually exist for at least a few days (virtual system instance) to many years
(servers and office locations). Instant discovery of new topology objects is not regarded as very
important. Therefore, when periodically collecting topology data, the discovery interval is usually
set to a high value (for example, once per hour or even once per day). It also can be done only onrequest from an external source.
Topology collection is the most complex integration task, due to different types and multiplicity of
relations between objects in the topology. This usually results in a more complex code compared to
a single loop for events or metrics.
The recommended way to collect topology is as follows:
l
Establish a method to collect a filtered set of multiple objects.

Tip: Collect all objects of a certain type or even multiple types together. This approach
avoids individually requesting each object from the server or the database.
For each received object, only establish to which child objects it is connected. For example, for
a discovered SQL server object, do not try to figure out on which computer it is installed, but just
try and resolve the relations to its databases. The computer -> sql server relation will be
handled by the computer object. This method is also used in the predefined XML output file
format that is read by the TopoSync library.
Processing of topology data is highly-dependent on the third-party domain manager, but in general
the code could be written as described in the following example.
Page 20 of 30

Topology Collection Example:

configuration_set = read_discovery_configuration()
discovered_objects = []
for topo_group in configuration_set:
topo_filter = create_filter(topo_group)
topo_objects = get_topology_objects(topo_filter)
for obj in topo_objects:
topo_obj = process_object(obj)
child_relations = obj.get_related_children()
for relation in child_objects:
if check_relation(relation):
topo_obj.add_relation(relation.type(), relation.target_id())
discovered_objects.append(topo_obj)
print_objects(discovered_objects)
The example code exposes some additional functionality that may or may not be present on the
third-party domain manager:
l
Filtered collection of topology objects
Relations to children can be of more than one type
TopoSync supports the use of different types of relations - "Generic Relations". If more than one
type is used, make sure to identify the one that is commonly used to represent the "parent-child"
type of relation (as opposed to "member of", "using", ...). For the "parent-child" type of relation, the
normal (empty-type) relation type should be used. It is also recommended to create relations using
object IDs instead of the objects themselves.
In some cases the topology objects and concepts differ from those in BSM. For example, in
Microsoft SCOM, the IP address is just an attribute of a computer or a network adapter. In BSM,
the IP address is a CI Type and BSM expects it to be a standalone object. The TopoSync library
cannot to do m:n mapping, only 1:1. Therefore, post-discovery processing is required that
transforms the discovered topology into a semi-transformed form. In the example of the IP address,
you must create a copy of the IP address object, and change a few of its properties, so that it can
be processed as a different type of object.
In a similar way to the semi-transformation required for the mapping of topology objects, the
collection print-out may also need to be processed before it can be used. It is recommended to have
only one attribute in each printed object that defines its type. If the third-party domain manager uses
different attribute names to represent the type, an additional attribute should be introduced to
uniquely expose the type property.
Page 21 of 30

Finally, the objects should be printed to an XML file using the format describe in the following
example:
Topology Output Example:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Service>
<NewInstance ref="aaaa">
<Key>aaaa</key>
<Std>DiscoveredElement</Std>
<Attributes>
<Attribute name="name" value="mynode.mydomain.com" />
<Attribute name="type" value="win" />
<Attribute name="domain" value="mydomain.com" />
</Attributes>
</NewInstance>
<NewInstance ref="bbbb">
<Key>bbbb</key>
<Attributes>
<Attribute name="name" value="mynode02.mydomain.com" />
<Attribute name="type" value="linux" />
<Attribute name="domain" value="mydomain.com" />
</Attributes>
</NewInstance>
<NewInstance ref="cccc">
<Key>cccc</key>
<Attributes>
<Attribute name="name" value="Berlin" />
<Attribute name="type" value="ad_domain" />
</Attributes>
</NewInstance>
<NewInstance ref="dddd">
<Key>dddd</key>
<Attributes>
<Attribute name="name" value="MSSQLSERVER" />
<Attribute name="type" value="sqlserver" />
<Attribute name="version" value="2008R2" />
</Attributes>
</NewInstance>
<NewRelationship>
<Parent>
<Instance ref="aaaa" />
</Parent>
<Components>
<Instance ref="bbbb" />
<Instance ref="dddd" />
</Components>
Page 22 of 30

<GenericRelations>
<Relations type="member">
<Instance ref="cccc" />
</Relations>
</GenericRelations>
</NewRelationship>
<NewInstance ref="eeee">
<Key>eeee</key>
<Attributes>
<Attribute name="name" value="test" />
<Attribute name="type" value="sqldatabase" />
<Attribute name="encoding" value="utf-8" />
</Attributes>
</NewInstance>
<NewRelationship>
<Parent>
<Instance ref="dddd" />
</Parent>
<Components>
<Instance ref="eeee" />
</Components>
</NewRelationship>
</Service>
There can be as many instances of NewInstance and NewRealtionship as required. Each

relationship can have only one parent object and one or more normal and generic relations. Each
relation should be written below the objects that are referenced.
Topology Mapping
The BSM Connector includes a number of topology-related policies used to populate the RTSM.
Some extract topology data from the other data-types while others get all topology objects at once
and map the full topology tree to the RTSM.
The Custom Topology Policy is recommended when a complex topology must be mapped. It is
easier to create many relations between many objects when you have all the objects, compared to
only having one or two objects created from data contained in a metric or an event. The core
technology that makes it possible to map objects to the RTSM is based on DDM APIs and uses a
Jython script to execute methods from that API. Each integration must create its own custom
Jython script to perform the mapping.
Page 23 of 30

In general, this custom script has no limitations. However, the following must be successfully
executed:
l
There must be one function called discoveryMain, with Framework as its input parameter.
The discoveryMain function must return the ObjectStateHolderVector which contains zero
or more ObjectStateHolder objects which represent CIs.
For example, to create a computer and a SQL server related to it, the following script should be
executed:
def DiscoveryMain(Framework):
OSHVResult = ObjectStateHolderVector()
host = ObjectStateHolder("host_node")
hostKey = "127.0.0.1 DefaultDomain"
hostName = "mynode.mydomain.com"
shortHostName = "mynode"
host.setStringAttribute("host_key", hostKey)
host.setStringAttribute("name", shortHostName)
host.setStringAttribute("primary_dns_name", hostName)
OSHVResult.add(host)
databaseOSH = ObjectStateHolder("oracle")
databaseOSH.setStringAttribute("discovered_product_name", "Oracle DB")
databaseOSH.setStringAttribute("database_dbsid", "Oracle")
databaseOSH.setStringAttribute("database_dbtype", "oracle")
databaseOSH.setStringAttribute("application_category", "Database")
databaseOSH.setContainer(hostOSH)
OSHVResult.add(databaseOSH)
return OSHVResult
Results of the process should be viewed in the following log files:

%BSMC_HOME%\logs\error.log
%BSMC_HOME%\logs\bac_integration\bac_integration.log
%BSMC_HOME%\logs\bac_integration\discovery.log
This type of script works well, but has the following drawbacks:
l
It is difficult to handle more complex relations between objects The API can usually support it,
but writing the output in an appropriate way and parsing everything correctly requires significant
effort.
It is recommended to send a maximum of 20000 objects (relations are also counted as objects)
in one transfer. It is possible to split larger topologies into batches, but this has one major
requirement - all objects that are used for relations have to be within the same batch, otherwise
duplicate objects are created in the RTSM.
More on script debugging can be read in the BSM Connector Troubleshooting documentation.
Page 24 of 30

TopoSync-based Mapping
To avoid the two problematic areas, the TopoSync library is bundled BSM Connector (9.21 and
later). The mechanism for mapping is done using XML files, which let you work not only with the
current object, but also let you read data of other related object. It also includes an internal
mechanism for bundling all related objects into a single batch.
To make use of the TopoSync library functionality, create a Topology - Custom policy and use the
following code for its script:
import logger
#################################################
# Import Java Classes
#################################################
# TopoSyncSA classes
from com.hp.opr.bsmc.toposyncstandalone.control import TopoFlowControl
from com.hp.opr.bsmc.toposyncstandalone.exception import FlowControlException
# Java structures
from java.util import Properties
from java.lang import Boolean
# DDM API
from appilog.common.system.types.vectors import ObjectStateHolderVector
from appilog.common.system.types import ObjectStateHolder
##############################################
# Global variable values
##############################################
configDir = "%BSMC_HOME%\\conf\\topology\\xml"
topologyOutputFile = "%OvDataDir%\\datafiles\\MyOM\\output\\topology.xml"
rawDataInput = Boolean.TRUE
##############################################
# Main function
##############################################
def DiscoveryMain(Framework):
OSHVResult = ObjectStateHolderVector();
# Set up toposync flow control
flowControl = TopoFlowControl()
flowControl.setConfigDir(configDir);
flowControl.setTransferFile(topologyOutputFile);
runProps = Properties();
Page 25 of 30

runProps.setProperty("opr.toposync.taskName", "SyncMyOMTopology");
runProps.setProperty("opr.toposync.selectedBundles", "MyOMTopology");
flowControl.setSyncConfig(runProps);
flowControl.setRawDataInput(rawDataInput);
flowControl.setBulkingStrategy("structural")
# finally run the toposync
try:
flowControl.doSync()
except FlowControlException, e:
logger.errorException("sync failed")
return OSHVResult
finished = flowControl.prepareOSHV()
while not finished:
logger.debug('oshv incomplete, but bulk size breached')
OSHVResult = flowControl.getResult()
Framework.sendObjects(OSHVResult)
Framework.flushObjects()
finished = flowControl.prepareOSHV()
OSHVResult = flowControl.getResult()
logger.debug('finished oshv conversion returning result ')
logger.debug(OSHVResult.size())
return OSHVResult
The Topology-XML policy type was introduced with BSM Connector 9.22. It is designed to replace
the Custom Topology policy type and the associated need to copy paste the above script to it. It
exposes the two most important settings as user-configurable input fields in the policy editor:
l
XML file that contains the topology
Synchronization packages list
It can execute a collection script or command on a local or remote system. A limitation remains - is
not possible to manipulate the executing script when the default behavior is not as desired.
Page 26 of 30

The sync-package list contains a semi-colon separated list of one or more TopoSync syncpackages. Sync-packages contain rules for mapping of topology objects. Each package contains
the following files:
l
package.xml
contextmapping.xml
typemapping.xml
attributemapping.xml
relationsmapping.xml
Most integrations provide one package for the integration itself, usually called XxxTopology (for
example, SCOMTopology or ZenosTopology). You can add your own packages to the list in the
policy, extending the mapping process with further rules for additional topology object types or even
to extend the mapping of an existing object with additional attributes or relations.
If you do not want tochange the current package, you can create a new one. It must contains all
five XML files withthe rules and must be placed in the same directory as XxxTopology (%BSMC_
HOME%/conf/topology/xml/). The only thing you must change in that case is the package name
within the Topology policy:
1. Open the Topology Policy jython script.
2. Find: runProps.setProperty("opr.toposync.selectedBundles", "XxxTopology");
3. Change XxxTopology with the name you choose for the new package or append it after
XxxTopology, separated by a semicolon. For example:
runProps.setProperty("opr.toposync.selectedBundles",
"XxxTopology;MyNewPackage");
For more information on TopoSync sync-packages and how to write mapping rules please check
the "BSM Extensibility Guide" and the BSM Connector Online Help.
Tips & Tricks

More help about the development in the Jython layer can be obtained in the BSM Connector online
help under Working with Jython-Based Topology Scripts.
Page 27 of 30

A monitor represents a trail of a monitored aspect of a topology object (for example, CPU usage,
free disk space, or the number of processes running on a system). A monitor consists of:
l
Attributes which define it
Pairs of values
Timestamps of when those values were collected
Each monitor's set of values and its related timestamps can be used to create graphs or do
additional metric data analysis and processing inside BSM.
Metric data (often referred to asmetrics) is the term given to the data required by monitors.
In general, metric data can be used to monitor the behavior of an object and can result in:
l
Creation of events
Changes to the health status of the object
In the case of integrations, this functionality is usually realized within the third-party domain
manager, and the integration should not need to recreate it. Therefore, as a minimum, the
integration must transfer data to the BSM Graphing Component (for example, PMi) to let the user
monitor the object in BSM. The events reporting significant changes to an object are already
created in the third-party domain manager and are transferred to BSM using the event channel. For
this simple case, the metric policy used for mapping of metric data to BSMs native form does not
set a health indicator for the metric. However, if Application Performance Management (APM) data
collectors are available that make use of health indicators attached to metrics, it makes sense to
send health indicators as well.
Metric data in BSM is stored in the Profile database.
Metric Data Collection

Metric data collection is very similar to event collection. The metric data collector must periodically
request the values for the defined set of objects. You can usually get a value for a metric, even if it's
the same value as acquired during the previous collection. Event data, on the other hand, is only
available when an issue or a fix on a monitored object occurs. If metrics do not contain too many
attributes per metric, the Log File Policy is best suited to process them, where each metric value
(with its timestamp and other defining attributes) is written in its own line in the output log file:
Example
1343233537|vm7msspint24.lyncdemo.com|MSSQL$RTCLOCAL : Database|master|DB Allocat
ed Size (MB)|0|Microsoft.SQLServer.Database
1343233537|vm7msspint24.lyncdemo.com|MSSQL$RTCLOCAL : Database|master|DB Total F
ree Space (MB)|0|Microsoft.SQLServer.Database
1343233537|vm7msspint24.lyncdemo.com|MSSQL$RTCLOCAL : Database|master|DB Total
Page 28 of 30

Free Space (%)|0|Microsoft.SQLServer.Database

1343233573|FALSE.RIESLING.INTERN|Network Interface|8|Bytes Total/sec|230545.9218
75|Microsoft.Windows.Server.2008.NetworkAdapter
1343233572|FALSE.RIESLING.INTERN|LogicalDisk|C:|% Free Space|24.9104537963867|Mi
crosoft.Windows.Server.2008.LogicalDisk
1343233572|FALSE.RIESLING.INTERN|LogicalDisk|C:|Free Megabytes|8902|Microsoft.Wi
ndows.Server.2008.LogicalDisk
1343233606|MALT.RIESLING.INTERN|General Response|MALT|Active Directory Last Bind
|0.11|Microsoft.Windows.Server.2008.AD.DomainControllerRole
1343233606|MALT.RIESLING.INTERN|General Response|MALT|Global Catalog Search Time
|0|Microsoft.Windows.Server.2008.AD.DomainControllerRole
1343233607|MALT.RIESLING.INTERN|PDC Op Master|MALT|Op Master PDC Last Bind|0.016
|Microsoft.Windows.Server.2008.AD.DomainControllerRole
1343233602|MALT.RIESLING.INTERN|Network Interface|7|Bytes Total/sec|8849.7285156
25|Microsoft.Windows.Server.2008.NetworkAdapter
1343233602|MALT.RIESLING.INTERN|PhysicalDisk|\\.\PHYSICALDRIVE0|Avg. Disk sec/Tr
ansfer|0.00556244049221277|Microsoft.Windows.Server.2008.PhysicalDisk
Metric data is represented as timestamp-value pairs. The example above contains much more
information than this - timestamp is the first column and the value is in the sixth column. The
information in the other columns is as important as the timestamp-value pairs. It is used to identify
the monitor to which the timestamp-value data belongs. The column values represent the following
things:
l
Timestamp - When the value was collected (in this example, it is unix time, where 1343233537
represents Wed, 25 Jul 2012 16:25:37 GMT).
Node On which system the monitored object is hosted (for example, mynode.mydomain.com).
Monitor Type - Type of object being indirectly monitored (information from Microsoft SCOM
only, where some of objects are represented as attributes of other objects. For example,
Memory usage is an attribute of the Operating System object, not the Memory object. Hence,
the monitor type is Memory, but in the last column, where the object type is usually be defined, it
would say Microsoft.Windows.Server.2008.OperatingSystem).
Object Name - Name of the object being monitored (for example, C: partition on the node
mynode.mydomain.com).
Metric Name - Name of the aspect being monitored (for example, % Free Space).
Value - Value of the monitored aspect (for example, 24.9104537963867, which combined with a
metric name set to % Free Space represents 24.9% free disk space).
Object Type - Type of the object being monitored (for example,

Microsoft.Windows.Server.2008.NetworkAdapter).
Why all this data is needed each time we read a value for a particular aspect for an object is
described in the following section - Metrics Mapping.
Page 29 of 30

Metrics Mapping
Each metric to be mapped from a generic data format or structure needs to contain some
information that clearly defines it as unique. The attributes that identify a metric as unique are:
l
Timestamp - Recommended to use unix timestamps for defining time. The value must be set in
double type. As data is read in string format, the timestamp should be cast using the
parseDouble(myval) function.
Value - Can be any value, but it must be set in double type. The value should be cast using the
parseDouble(myval) function.
In addition to changing values, the following attributes need to be attached to the Timestamp and
Value attributes:
l
Monitor Type - Usually defines the type of object being monitored. From the example, above it
would be LogicalDisk, but a better and more descriptive name, would be System Disk Usage.
Monitor Name - Defines the monitor if there are multiple instances of the specified monitor type.
Usually the name of the object (for example, C:). It is also recommended to prepend the name
with the monitor type, in case there is another type of monitor on the same object that could have
the same name, for example, LogicalDisk (C:).
Target - Should be set to the node on which the object is hosted (for example,
mynode.mydomain.com).
Name - Should be set to the name of the aspect that is monitored on the object (for example, %
Free space).
Ci Hint - By default, it should be set to the same value as Target, but can be changed in the
subsequent rules to use the usual BSMC/integration CI Hint format:
<CIType>:<CIName>@@<Node>
There is also the requirement to set some of the attributes of a metric to predefined fixed values:
l
Quality - set to QUALITY_GOOD (without quotes)
Monitor State - set to "OK" (with quotes)
Tips & Tricks

See the Tips and Tricks section in the chapter Collecting and Viewing Metrics Data of the BSMC
online help.
There are many online time converters on the internet, which you can use to convert time formats.
For example:
Epoch Converter - website which converts time to and from the unix timestamp.
Page 30 of 30

BSM Connector Developers Guide 0

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

BSM Connector Developers Guide 0

Hochgeladen von

Copyright:

Verfügbare Formate

HPBusiness Service Management

For the Linux and Windows operating systems

BSM Connector Developer's Guide for Integrations

Document Release Date: November 2013

BSM Connector Developer's Guide for Integrations

Restricted Rights Legend

Software Version number, which indicates the software version.

HP Business Service Management (9.22)

Chapter 2: Integration Basics

Data Types and Data Exchange

OMi/BSM Data Handling

BSM Connector Data Handling

How to Collect Data

When to Collect Data

Chapter 3: Event Channel

Tips and Tricks

Chapter 4: Topology Channel

Chapter 5: Metric Channel

Metric Data Collection

Tips & Tricks

HP Business Service Management (9.22)

HP Business Service Management (9.22)

Chapter 2: Integration Basics

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

Data Types and Data Exchange

Event data is directed to OMi (Operations Management)

Topology data is directed to RTSM (Real-Time Service Model)

OMi/BSM Data Handling

BSM Connector Data Handling

Transfer of data to the BSM server and its components

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

Full or Lightweight Collector

Domain Manager Version Range

How to Collect Data

Extensions/Add-Ons/Plug-ins - Some domain managers enable extension of their

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

When to Collect Data

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

Structured log file

Web-service received data

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

Data Sources in BSM Connector:

Custom Topology Policy

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

Windows: C:\Program Files\HP

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

Windows 2003: C:\Documents and Settings\AllUsers\HP\HP BTO Software

Windows 2008: C:\ProgramData\HP\HP BTO Software

These variables are created during the BSM Connector installation.

HP Business Service Management (9.22)

Chapter 3: Event Channel

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

These two events are appended to the output file as follows:

HP Business Service Management (9.22)

BSM Connector Developer's Guide for Integrations

HP Business Service Management (9.22)