Business Service Management

Home > Integration Scenarios > Integrating TBSM 4.1 with Tivoli Application Dependency Discovery Manager

Integrating TBSM 4.2 with Tivoli Application Dependency Discovery Manager

This paper is an update to the original IBM Tivoli Business Services Manager (TBSM) Integration With IBM Tivoli Application Dependency Discovery Manager (TADDM) white paper, "TBSM Integration with TADDM, Document version 1.0", published in December 2007. The focus of this paper is still the integration between TBSM and TADDM, but it reflects the changes that have been implemented in TBSM 4.2 and TADDM 7.1.2 with respect to the integration between the two products.

This integration involves the importing of data from TADDM into TBSM. The data import includes TADDM Business Applications and Business Services, which will be added to TBSM's list of services, and also the physical TADDM CI's, which will be added to TBSM's Service Component Repository (SCR). The SCR can be thought of as a physical list of resources that are available to be added to TBSM services. A key aspect of the SCR is the relationship information that is imported from TADDM, when an SCR resource is added to a service, not only the resource but also resources with relationships to that resource will be associated with the service.

One of the functions of the TBSM Discovery Library toolkit is to transition data from the IBM Common Data Model (CDM) into the template-based model used by TBSM. Both TADDM and the Discovery Library Adapters (DLA) represent data in the CDM. There have been a number of papers that have focused on the integration of TBSM with DLAs from other products, including Tivoli Monitoring and IBM Tivoli Composite Application Manager (ITCAM) for SOA. These papers are listed in the references below, and you are urged to also read these papers in order to get a complete understanding of the features available in the toolkit's CDM support. These papers have covered the customization available in the TBSM Discovery Library toolkit. This paper will include customization, but focus more on the mechanics involved in the TADDM integration and on issues that have come up as customers have worked to implement this integration.

The features mentioned in this paper are based on TBSM Discovery Library toolkit 4.2 and TADDM 7.1.2. Earlier levels of these products may not include all of the functionality mentioned in this paper.

Introduction

The TBSM Discovery Library toolkit acts as a bridge between the IBM Common Data Model (CDM) and the template-based model of TBSM. The toolkit can either interface with Tivoli Application Dependency Discovery Manager (TADDM) or read Discovery Library Adapter (DLA) books directly. This paper will primarily focus on the toolkit's interface with TADDM, although many of the principles discussed here are applicable to DLA books also.
The toolkit consists of a process that collects information defined by the CDM and through a series of transforms, stores the data in the TBSM Service Component Repository (SCR). The SCR acts as a data source to TBSM, where an ESDA is used to extract data from the SCR and place the data into the TBSM server's data store.

Figure 1: TADDM-TBSM integration data flow

The toolkit can either automatically poll TADDM for new and changed resources or it can wait until directed by a command line interface (CLI) to request data. Requests can be either bulk or delta. A bulk request asks TADDM for all of the objects of interest to TBSM. The toolkit will then update the SCR to match this data. An example of this is, if previously the SCR had objects A, B, and C from TADDM, and a new bulk request returned objects A, B, and D, then the SCR updates objects A and B, object C is deleted and object D is created. A delta request is simply a request to get any created, deleted, or modified objects since the last time an import was run.

The toolkit requests objects from TADDM on an object class basis. Filtering determines which object classes are imported. Requests interface with TADDM through TADDM's Java API. Jar files that are maintained on both the TADDM server and the TBSM server provide this API.

The returned data is further filtered and then passed through a series of transforms. The transforms are XSLT based, and use a series of XML files to take the CDM modeled data received from TADDM, and transforms these objects into objects and relationships consumable by the template based TBSM server. The XML files used by these transforms can be customized to better suit the needs of the customer.

Imported resources from TADDM to TBSM

The data stored in the SCR is pulled into the TBSM server through an external service dependency adaptor (ESDA). This ESDA will populate the Service Component Repository tab in the TBSM user interface. All "physical" resources received from TADDM are placed in the Service Component Repository. As an example, the following TADDM screen capture shows several Apache Web Servers.

Figure 2: TADDM Apache Web Server

These Apache Web Servers can be found in TBSM's Service Component Repository under the Application Servers, HTTP Servers.

!figure3.gif
Figure 3: TBSM view of imported web servers

Imported Business Application and Business Services from TADDM to TBSM

Business Applications and Business Services defined in TADDM will also populate the TBSM service tree. In the example below, TADDM contains the business application "Order Management".

Figure 4: TADDM Business Application

This business application is placed in the TBSM Service tree under the Imported Business Services.

Figure 5: TBSM view of imported business application

All Business Applications and Business Services, plus their contained/dependent children, imported from TADDM are placed under the Imported Business Services folder. When a physical object from the SCR is added to a service in TBSM, objects associated to that object via relationships provided by TADDM will also be added to the service. Relationships are followed, pulling in dependent objects until additional relationships that are interpreted as dependency relationships (see the CDM_TO_TBSM41x_MAP.xml file) are not found. Also, when the resources from TADDM are in the Services tab, they are available for event matching.

When objects imported from TADDM are placed in the SCR, the toolkit tracks which objects will affect the TBSM Services tree, and the toolkit automatically invalidates the upper-most affected object in the Imported Business Service. This invalidation will cause the ESDA to run and to update the services automatically. When the Service Navigation is refreshed, the new resources will be visible.

When TADDM imported resources are not part of a service, these resources are only visible in the Service Component Repository tab of the Service Navigation. The SCR tab is not invalidated automatically. To invalidate the SCR, select the Component Registry and invalidate, and then refresh the Service Navigation.

Define business services in TBSM with resource from TADDM

Physical resources can be added to a TBSM service by selecting the Add from Service Component Repository button on a service's dependents "Edit Service" panel:

Figure 6: TBSM service add SCR panel
Selecting the Add from Service Component Repository button opens a dialog box that contains the Component Registry tree. The tree can be expanded and the required resources selected.

Figure 7: Add from Service Component Registry dialog

The resources selected from the Add from Service Component Registry Dialog are added to the "Selected Services" area of the "Edit Service" dialog box. After the service is saved, the additional resources are displayed in the Service Navigation tree.

Figure 8: Edit Service dialog with selected SCR resources

CDM to templates mapping

The TBSM Discovery Library toolkit installs a set of templates and mappings that will transform the more common collections of objects in TADDM to objects acceptable by TBSM. This includes computer systems, application servers, databases, and clusters to name a few. These templates provide a starting point, but it is expected that they will need to be customized and that additional templates created to meet a customer's unique needs. It also includes a set of event mappings that will map Tivoli Monitoring and z/OS® events to resources that have been loaded into TADDM via the TMS and z/OS DLA's.

The out of the box configuration of the toolkit does not provide a definitive solution for everyone. The verboseness of the CDM and the infinite number of event sources prevents a solution that covers all cases for all customers. The customization in the filtering and the XML transforms allows for the solution to be modified, meeting the specific needs of an organization.

Configuration

Supported Configurations

The TBSM Discovery Library toolkit acts as a bridge between the TADDM server and the TBSM server. The following tables list the supported configurations involving these components.

Table 1: TBSM Server / toolkit compatibility matrix

Table 2 - TADDM Server / toolkit compatibility matrix

If you are currently running with a TBSM 4.1.1 server, it is strongly recommended that you upgrade to the TBSM 4.2 Discovery Library toolkit.

Installing the TBSM 4.2 Discovery Library Toolkit with TBSM 4.1.1

To ease migration, the TBSM 4.2 Discovery Library toolkit can be installed on a TBSM 4.1.1. Server. This toolkit can interact with TADDM 7.1 or later systems.
Before installing the toolkit on a TBSM 4.1.1 Server, back up your TBSM PostgreSQL database. The installation will migrate the database schema used by the toolkit to the 4.2 database schema. The IBM Tivoli Business Service Manager 4.2 Administrator's Guide, Administering IBM Tivoli Business System Manager, discusses how to back up the database.

The TBSM 4.2 Discovery Library Toolkit is a new installation of the toolkit, not an upgrade to the currently installed version. This is due to directory structure changes in the TBSM 4.2 Server. Therefore the 4.2 toolkit will install into a different directory than your current toolkit. Do not instruct the installer to use the same installation directory as your current toolkit.

The toolkit's installer will detect the presence of a TBSM 4.1.1 toolkit and ask if you want to migrate; reply yes. By replying yes, the installer will copy the filter, configuration, and TADDM jar files from your older installation and migrate the database schema. The database schema migration can be lengthy, so be patient during this installation step.

Database Schema Migration

If you replied no when the installer asked if you wanted to migrate from 4.1.1, then you will need to run the ".../XMLtoolkit/bin/migrate_db_schema_to_42" script after the installation. This script will migrate the database. Depending on the size or your database, this process can be lengthy.
Issue "./migrate_db_schema_to_42.sh -?" for syntax. Here's a sample invocation:

./migrate_db_schema_to_42.sh -U postgres -d rad -p 5435 -l $TBSM_HOME/XMLtoolkit

Note: the "migrate_db_schema_to_42" might issue a message referring to the scc_systemconfig table. This message can be ignored; it does not indicate an error.

XML Customization File Migration

After installing the 4.2 toolkit, you will need to manually merge any changes that you have made to the following XML configuration files:

• CDM_TO_TBSM4x_MAP.xml
• CDM_TO_TBSM4x_MAP_Templates.xml
• EventIdentifierRules.xml
• LabelingRules.xml

If you specified yes to migrate from 4.1.1, then the 4.1.1 version of these files will be in $TBSM_HOME/XMLtoolkit/xml. The 4.2 version of these files will be in $TBSM_HOME/XMLtoolkit/xml/install. After you have merged these files, put the updated version in $TBSM_HOME/XMLtoolkit/xml.

TBSM

If the TBSM Discovery Library toolkit was installed with TADDM as the data source, then some of the items below will already be set for you. But it is still good to review each section, as some of these items have caused a few problems in the past.

Note: If you are running TBSM Discovery Library toolkit 4.2 with TADDM 7.1, several additional required configuration steps exist; these steps can be found in the Appendix.

Required Configuration Steps

API JAR Files

The information that follows applies to TADDM 7.1.2 or later. For jar file information for earlier releases of TADDM, please see the Appendix.
The TBSM Discovery Library toolkit uses TADDM's Java API to retrieve data from TADDM. This API requires that the API client jar file used by TBSM be the same as the version used by the TADDM server. Therefore, before starting the toolkit, the file must be copied from the TADDM server to the TBSM server.
The file, taddm-api-client.jar, can be found on the TADDM server in $COLLATION_HOME/sdk/clientlib and should be placed on the TBSM server in $TBSM_HOME/XMLtoolkit/sdk/clientlib.

If the jar files has not been downloaded to the TBSM server, the toolkit will write the following message to the msgGTM_XT.log and terminate the service:
GTMCL5361E: TADDM has been chosen as a data source for the toolkit, but the TADDM SDK jar files were not found. If connecting to a TADDM later than 7.1, please copy taddm-api-client.jar from the TADDM server to $TBSM_HOME/XMLtoolkit/sdk/clientlib. If connecting to TADDM 7.1 or earlier, please copy all of the TADDM SDK jar files to $TBSM_HOME/XMLtoolkit/sdk/lib. The TADDM SDK jar files can be found on the TADDM server under /opt/IBM/cmdb/dist/sdk. After updating the jar files, restart the toolkit.

At the beginning of each import, TBSM will compare the checksum of the TADDM API jar file that it is using against the checksum of the jar file that the TADDM server is using. If the checksum of the TADDM API jar file used by the toolkit is different than the jar file used by the TADDM server, a warning message will be displayed in the msgGTM_XT.log:

GTMCL5355W: The TADDM Java API jar file taddm-api-client.jar, used by TBSM to communicate with the TADDM server, has changed on the TADDM server. To prevent possible interruptions in service it is recommended that you update the file on the TBSM server.

This message is a warning, the toolkit will continue to operate, but the jar file should be resynchronized at the earliest convenient time. After the jar files have been resynchronized, the TBSM toolkit must be restarted to pickup the new jar file.

Not keeping the TADDM API client jar file on the TBSM server in synch with the TADDM server may result in random exceptions when data is copied from TADDM to TBSM. Exceptions include:

• Unmarshalling errors, which in a nutshell indicate that the client side cannot decipher what the server sent.
• RMI exceptions
• Connection failures

These exceptions are written to the $NCHOME/XMLtoolkit/log/msgGTM_XT.log file.

Optional Configuration Steps

Database

Both the TBSM server and the TBSM Discovery Library toolkit use the PostgreSQL database. In TBSM 4.2, the database is configured by default to run optimally for average size databases. Large databases might require configuration changes. This is discussed more thoroughly in the white paper, "Tivoli Business Service Manager 4.1 Tuning Recommendations". The database configuration properties that affect the toolkit are discussed in the following sections.

Note: If using the TBSM 4.2 Discovery Library toolkit with a TBSM 4.1.1 server, the following recommendations must be made to the specified files.

$TBSM_HOME/tbsm/etc/rad_dbconf

This file contains a number of server configuration items. On UNIX platforms, the database properties in this file override the values in $TBSM_HOME/pgsql8/data/postgresql.conf.

PG_BUFFER is the same as shared buffers in the postgresql.conf file and is multiplied by the number of database connections allowed. It represents the number of shared memory buffers used by the database server. Each buffer is 8192 bytes. On UNIX systems, this value is sensitive to the maximum allowed shared memory, therefore the system configuration may need to be modified to allow for additional shared memory. If there is insufficient shared memory, the TBSM server will not start. If this happens, the value should be lowered until the TBSM server starts.

PG_BUFFER is set to 2000 out of the box. This should be reasonable for average size databases. If shared memory allows it, this value should be increased to provide better performance for larger databases. Ideally, if dealing with large TADDM databases or z/OS resources, set this value to a minimum of 3000.

$TBSM_HOME/pgsql8/data/postgresql.conf

This is the primary configuration file for PostgreSQL. The properties listed below are set to the values shown. Depending on the size of your database, these numbers may need to be increased to further optimize database performance.

Table 3 - postgresql.conf customization
Additional sources pertaining to PostgreSQL performance can be found on the web.
After making these database configuration changes, the TBSM Data Server, Console Server, and PostgreSQL database must be stopped and restarted.

UserID and Password

The TBSM Discovery Library toolkit installation will prompt for the TADDM user identifier and password. These values are encrypted and stored on disk. If either value is incorrect, a connection exception will be logged in the message log, $TBSM_HOME/XMLtoolkit/log/msgGTM_XT.log:

2007.08.28 11:39:16.843 GTM ASITADDMConnection getConnection \[main\] XMLTOOLKIT  bsmaix07.tivlab.raleigh.ibm.com
GTMCL5205E: Exception caught. com.collation.proxy.api.client.*ApiLoginException*: java.rmi.ServerException: 
RemoteException occurred in server thread; nested exception is: java.rmi.RemoteException: 
The application is unable to login:com.collation.proxy.api.client.ApiException: !OalApiLogin.E.1!.; 
nested exception is: com.collation.proxy.api.client.ApiException: !OalApiLogin.E.1!.

If the TADDM user identifier and password need to be reset, or entered for the first time if the toolkit was originally installed to read books, the setxmlaccess command is used. The command is documented in the TBSM Administrator Guide, and online help is available by entering: "setxmlaccess -?".

Properties

The TBSM toolkit service is controlled through the property file xmltoolkitsvc.properties. The properties are set during the toolkit installation. These can be changed manually by editing the property file. Changes to these properties require the toolkit to be stopped and restarted. The properties that pertain to the TADDM integration are shown in the following table:

Table 4 - xmltoolkitsvc.properties associated with TADDM

TADDM

There are not many items on the TADDM server that are specific to the TBSM integration. Performance is the main objective with most of these items.

Required Configuration Steps

API JAR Files

Again, simply a reminder that if a TADDM fix-pack is installed, then the jar file in $COLLATION_HOME/sdk/clientlib must be updated on the TBSM server in $TBSM_HOME?XMLtoolkit/sdk/clientlib directory. We cannot stress enough how important this is.

Optional Configuration Steps

Database

The performance of the TADDM database is paramount in the overall performance of the TADDM/TBSM integration.
It is suggested that you review the Architecture, Deployment, Scalability, and Performance Overview paper noted in the references.
There are more performance tuning suggestions listed in TADDM Administrator's guide, chapter 5, "Populating the Database", section "Performance tips for database.

Runtime

The toolkit is designed to run as a background process. In a nutshell, you start it, it waits for a specified interval to expire, at which time it queries TADDM for updates, manipulates the data, and puts the data into the database. This interval can be interrupted via command line if an import is needed immediately.
Once configured, start the process. On Windows, the process is started either from the Windows Services Applet or via the net use command. On UNIX, the process is started using the tbsmrdr_start.sh script.

TBSM will perform two types of imports: bulk and delta.

• A bulk import means that TBSM will request all of the resources of interest from TADDM, and then synchronize the SCR with the current set of resources received from TADDM. As an example, lets say that prior to the bulk TBSM had resources "a", "b", and "c". A bulk import is started and TBSM gets resources "a", "b", and "d". TBSM would then update resources "a" and "b", delete resource "c", and create resource "d".

• A delta import means that TBSM will request all resources of interest in TADDM that changed between the last import and the current time. Changed resources include created, modified, and deleted resources. As an example, lets say that prior to the delta TBSM had resources "a", "b", and "c". A delta import is started and TBSM gets a delete for resource "b" and a create/modify for resources "a" and "d". TBSM would then delete resource "b", update resource "a", and create resource "d".

Note: TBSM processes all delta deletes in a batch, followed by all of the creates/modifies. TBSM currently does not have a means of accurately determining the exact time of the modification. Because of this restriction, if a TADDM operator creates a business application with resources "a" and "b", then removes resource "b" from the business application, and then a TBSM import is run. TBSM will create the service with resources "a" and "b" because it cannot distinguish the order of the delete and create of resource "b". To resolve this inconsistency, a TBSM bulk import will need to be run. If a delta import were run after the initial create of the business application, then TBSM would have created the service with resources "a" and "b". If a second delta import were run after resource "b" was removed from the business application, then TBSM would have deleted "b" from the service. This scenario would have avoided the need to run a bulk import.
The toolkit will check with TADDM for updates as defined by the polling interval (DL_PollIntervalSeconds) specified in the properties file. If updates are detected, then the toolkit will initiate a delta import and pickup the changes, after which it will sleep again until either the polling interval expires or a CLI (cmdbdiscovery) request is made.

The CLI (cmdbdiscovery) provides a means of initiating a bulk or delta import regardless of the polling interval. The complete usage of cmdbdiscovery can be seen by issuing "cmdbdiscovery -?", but we will discuss a couple of the more import flags here:

• -b - start a bulk
• -r - initiate import immediately
• -e - rebuild all explicit relationships

When the polling interval expires, the natural tendency of the toolkit is to run a delta import. By issuing "cmdbdiscovery -b", this tells the toolkit to run a bulk import the next time that the polling interval expires.

If the polling interval is set to one hour, but an import is needed now, then the -r flag should be use. Issuing "cmdbdiscovery -r" will result in a delta import starting. Issuing "cmdbdiscovery -b -r" will result in a bulk import starting. When the -r flag is used, the polling interval is stopped, and an import is started within sixty seconds. When the import is finished, the clock on the polling interval is reset back to zero and restarted.
The -e flag allows for the explicit relationships in the TADDM database to be rebuilt. The explicit relationships are built outside of the normal TADDM discovery process. When an import is requested by TBSM, TADDM will build any new explicit relationships based on resource changes since the last import. If it is suspected that the relationship table in TADDM is inaccurate, then issuing "cmdbdiscovery -b -r -e" will request that a bulk import with a complete rebuild of the relationship table be run. Depending on the size of the TADDM database, rebuilding of the relationship table could be lengthy and it could impact TADDM performance. This should only be used when a problem is suspected, and the TADDM administrator should be notified beforehand.

To stop the process, on Windows the process is stopped either from the Windows Services Applet or via the net use command. On UNIX, the process is stopped using the tbsmrdr_stop.sh script.

Filtering

Out of the box, the TBSM toolkit imports a set of resources from TADDM that includes: computer systems, servers, databases, application servers, clusters, and business applications. This is a subset of what can be discovered by TADDM, and essentially any of the resources in TADDM can be imported into TBSM as long as the associated CDM classes are mapped to templates in TBSM. Exactly which resources in TADDM are of interest to TBSM and the business services that will be built and monitored in TBSM will vary with each implementation. The TBSM toolkit provides a number of filtering mechanisms, some minimize the amount of data that is requested from TADDM, others take the data that has been retrieved and reduces this further before writing it to the SCR database. The filters include:

• TADDM base class filters
• TADDM leaf node class filters
• Attribute global filters
• Attribute class filters
• View attribute filters (database view)

One point should be made here, while any of the objects in TADDM can be imported into TBSM, and it may look nice to have very granular objects in some cases, if an event cannot be posted against an object, it may not make sense to show that object in TBSM. So a little common sense should be used when deciding which classes of objects to import into TBSM.

The graphic below illustrates the point in the processing when a particular filter is applied and the configuration files associated with each of the filters.

Figure 9 - TBSM filtering diagram

The filter files are located in $TBSM_HOME/XMLtoolkit/config/filters. The database is defined in $TBSM_HOME/XMLtoolkit/sql/scc_schema_views.sql.
The original approach taken was to filter very little. As time has passed, and we've seen how this approach has worked in the field, our view on filtering has changed, and we now believe that the initial approach should be to filter out most data initially, and then import additional classes as different types of information are needed in TBSM. The default filters provided with TBSM 4.2 are more restrictive than those in TBSM 4.1.1. There is additional discussion on this topic in the section on base class filters.

TADDM Model

Understanding which classes are in TADDM and what attributes are associated with each class can be a bit overwhelming given the granularity of the CDM. To help with this, the toolkit writes a number of files to the $TBSM_HOME/XMLtoolkit/config/cdmmeta directory:

• BaseClassCMDB.xml - this is simply a list of all of the TADDM base classes. A base class in this case is defined as a class that does not have a parent class defined in the model object returned by the TADDM metadata request. A sample entry in BaseClassCMDB.list is:
  
  

  <baseclass class='com.collation.platform.model.topology.app.db.oracle.OracleServer'/> \\

  
  This entry is the name of the oracle.OracleServer class.
  
  

• BaseClassCompleteCMDB.xml - this file lists all of the classes and their parent class. Each line in the file lists a parent class, followed by the child class associated with that base class. This file looks very similar to the file, classfilters.xml, used for class filtering. A sample line in this file follows (to make the example readable, the class names are shortened):
  
  

  <baseclass class='model.topology.app.j2ee.EJBContainer'> 
        <childclass  class='model.topology.app.j2ee.weblogic.WebLogicEJBContainer'/>
        <childclass class='model.topology.app.j2ee.websphere.WebSphereEJBContainer'/>
                                       </baseclass>

  
  This line indicates that the class WebLogicEJBContainer is a child of the EJBContainer class.
  
  

• <baseclass>.attrlist - there will be one attrlist file for each class listed in BaseClassCMDB.list plus any class that is imported. Each attrlist file lists the attributes available for that class. Because an attribute is listed in this file, this does not mean that an instance of this class will have that attribute. This file is simply a list of the attributes that may appear in an object of this class or its subclasses and should only be used as a reference. The actual lists of attributes on an object is dependent on the data gathered by TADDM and the DLA books imported into TADDM. Each line in an attrlist file consists of the attribute name and the attribute type. An attribute type can be:
  
  
  • a simple type, such as an integer
  • a Java class, such as java.lang.String
  • a TADDM object, such as com.collation.platform.model.topology.sys.Operating System

When TBSM receives an object from TADDM, it will request all attributes for that object. TBSM will process all attributes that are of type: string, integer, float, boolean, GUID, and long. Attributes defined as other types are discarded.

TBSM does not request TADDM extended attributes.

Each of these files is updated each time that the toolkit is started.

Class Filters

All class filtering is maintained in a single file, $TBSM_HOME/config/filters/classfilters.xml. This is a change from the previous release, in which separate files were kept for base class and child class filters.

Before we get into how the file works, the default class filtering provided with the earlier versions of the product was built with the premise that providing more than may be necessary was better than not providing enough. We have found that it is probably better to start with a small set and then add in classes that you find you need. With this in mind, the following classes are no longer imported by default:

Table 5 - classfilters.xml default changes

The classfilters.xml file specifies which classes of resources that TBSM will import from TADDM. This file shows each base class and its children. Filtering can be specified at either the base class level or at the leaf node level. Filter specification of intermediate nodes is ignored; this will be explained as we go.
The example below will be used to describe how the filters work. To make the example more readable, the class names have been shortened for this example.

Figure 10 - Sample classfilter.xml Segment

Each line is either a <baseclass> or a <childclass>, and contains the attributes:

• import - true indicates this is a class of resource that should be imported. False indicates this class of resource should not be imported.
• class - the name of the class
• depth - the depth in the tree, starting with the base class which has a depth of 0. Do not confuse this with the depth flag on the TADDM api.sh script, they are not related.

The classfilters.xml is basically a list of base classes, and contained within each base class is its children. The "<baseclass>" tag defines the base class. In the example above, "topology.sys.FileSystem" is the base class.

The base class "topology.sys.FileSystem" has eight children, each defined by the tag "<childclass>". The leaf nodes are the children at the lowest leg of each branch. In this example there are five leaf nodes, they are:

• topology.sys.openvms.OpenVmsFileSystem
• topology.sys.sun.SolarisFileSystem
• topology.sys.windows.WindowFileSystem
• topology.sys.NFSFileSystem
• topology.sys.SMBFileSystem

Now you might ask, "topology.sys.openvms.OpenVmsFileSystem" and "topology.sys.unix.UnixFileSystem" are at the same level in the tree, why is one a leaf node and the other not? Looking at the tree, "topology.sys.unix.UnixFileSystem" has a child, "topology.sys.sun.SolarisFileSystem", so the leaf node here is "topology.sys.sun.SolarisFileSystem", while "topology.sys.openvms.OpenVmsFileSystem" does not have any children so it is a leaf node. Using the depth attribute and the indentation should help in seeing this.

Now that the concepts are defined, this paper will discuss how the file works. Earlier it was mentioned that filters could be defined at the base class level and the leaf node level.

A child will inherit the import state of its base class. So setting import='false' for "topology.sys.FileSystem" means that it and all of its children have import='false', and therefore none of the objects in this class will be imported. Likewise, setting import='true' on "topology.sys.FileSystem" means that this base class and all of its children are imported.

Now assume that in general you are not interested in FileSystem objects, but you are interested in RemoteFileSystems and you changed the previous example in the following way:

Figure 11 - Sample classfilters.xml leaf node filter

This example tells the system to import resources of type "topology.sys.NFSFileSystem" and "topology.sys.SMBFileSystem", but none of the other file system objects.

This change has two benefits:

• TBSM only imports the objects of interest
• It helps with performance because less information is requested from TADDM and the database only contains objects of interest.

Now you might ask, why could I not leave everything as import='false' and simply change the following line:

<childclass import='true' class='topology.sys.RemoteFileSystem' depth='1'/>

This type of change does not work because "topology.sys.RemoteFileSystem" is not a leaf node and therefore it inherits its import state from its base class.
To switch hats, say that you are interested in FileSystems with the exception of WindowsFileSystem. In this case you change the previous example to:

Figure 12 - Sample classfilter.xml leaf node exclusion

In this case TBSM will request all topology.sys.FileSystem objects, and then remove the topology.sys.windows.WindowsFileSystem objects when they are received. This will not reduce the overhead of pulling data over from TADDM, but it will reduce the number of objects in the TBSM database.

Lastly you might ask, since the toolkit is only looking at the import state for the base classes and the leaf nodes, does it really matter what the import value is for the intermediate child classes? Technically no, the import state of the intermediate child classes is ignored, but to avoid confusion set all of the import values for the child classes to the same value as the base class.

Global Attribute Filters

There is a set of attributes that in general are not of interest and therefore are not worth instantiating when a resource is written to the TBSM database. This set of attributes is defined in the file, $TBSM_HOME/XMLtoolkit/config/filgers/AttributeGlobal.xml. This file is customizable. The attributes specified in this file will be removed from all objects requested from TADDM. The contents of this file is shown in Figure 13:

Figure 13 - Global Attribute filters

This means that you will not see these attributes under the Additional tab in the service editor and these attributes cannot be used in any of the XML configuration files.

Looking in any of the *.attrlist files in the $NCHOME/XMLtoolkit/cdmmeta/attributes directory, you will see:

Figure 14 - Attribute format in attrlist file

Each line in the *.attrlist files has the attribute name and the attribute type. The attribute value in the AttributeGlobal.xml file is simply the name of the attribute taken from the *.attrlist file.

Class Attribute Filters

For each class that is imported, an <classname>.attrlist file is generated. These files can be used to generate attribute filters at the class level. The name of these filters is <classname>.xml. The name of the filter for BindAddress is:

Figure 15 - Class specific attribute filter file

The format of the file is the same as the AttributeGlobal.xml file.

One shortfall here is that the <classname>.attrlist file only lists the attributes at the base class level, it does not contain any additional attributes for any classes that are children of the base class. To see any additional attributes for the child classes, you will need to either look at an object's additional attributes tab in the TBSM UI or look at the details of an object in the TADDM UI.

If a TADDM import has already been run, the following SQL will provide an understanding of the types of attributes that TBSM has received data for.
To see a list of all of the CDM classes that TBSM has received data for, execute the following SQL:

select distinct class from scc_components

To see the attributes that TBSM has received for a particular class, execute the following SQL:

select distinct scc.class, keyword from scc\_componentattributes sa
  join scc\_components as scc on sa.comp\_id=scc.id

where scc.class='<className>'

Where <className> is the class of interest (i.e. cdm:app.AppServer).

To see all of the attributes for a particular class, ordered by the class that they are associated with, execute the following SQL:

select scc.class, scc.keyword from scc\_componentattributes sa
  join scc\_components as scc on sa.comp\_id=scc.id
group by scc.class, sa.keyword

See the section about Analyzing the SQL Tables for an explanation on running SQL.

View Attribute Filter

The view attribute filter is an optional view into the attribute table that limits the data returned by the ESDA to only those attributes that are deemed necessary. The IN() clause on the SQL where statement acts as the filter. The example in Figure 17 limits the attributes to the eight shown:

Figure 16 - view_componentAttributesLimited

The view definition is in the file $TBSM_HOME/XMLtoolkit/sql/scc_schema_views.sql. To change the definition, copy the file and edit the IN() clause to include the required attributes. Using psql or pgadmin, drop the current view

Figure 17 - drop view_componentAttributesLimited using psql
Then run the create view statement to recreate the view. The view definition for view_componentAttributesLimited includes two UNION statements so that the _sourceToken and _sourceContactInfo keywords are included, be sure to include these in your new view definition.

Class and Relationship Mapping

The data imported from TADDM abides by the CDM architecture. The common data model is verbose, defining hundreds of different objects and relationships. Meanwhile, status for these objects is provided by events received by NetCool/OMNIbus and other data sources. These events must be mapped to the objects imported from TADDM.
The TBSM Discovery Library toolkit populates the SCR, which acts as a bridging area between the resources and relationships defined by the CDM and the template-based service model used by TBSM. TBSM includes a default set of CDM objects mapped to TBSM templates. There is also a set of event identifiers that provide the mapping of events to the imported common data model objects.

To extend the default support, the toolkit allows for four areas of customization:

• Mapping - maps CDM classes and relationships to templates

• Composites - defines composites, the combination of several CDM objects into a single class, which is then mapped to a template.

• Event Identifiers - the definition of an identifier that identifies an object for purpose of aligning outside pieces of data (e.g. events, KPI) with the CDM object. The native identifier for a CDM object is the GUID or a naming string, neither of which is likely to appear in an event.
  The term "event identifiers" is a bit of a misnomer. Think of them as resources, identifiers, or aliases used to map to events and other information about a resources provided by data fetchers. These identifiers are visible in the Identifiers Tab in the TBSM Service Editor.

• Labeling - defines the attribute or attributes to be used for the display name.

The graphic below provides an overview of the imported process and shows the files associated with each area of customization. A detailed write-up is in the IBM Tivoli Business Service Manager Administrator's Guide (see the "Discovery Library toolkit" chapter).

The Common Data Model

The common data model defines the data model employed by TADDM. The current model can be broken down into 16 sections. See the IBM Common Data Model [7] in the references for additional information on the CDM. This reference will direct you to the location of the CDM and diagrams and information discussed below.

You can drill down into each section of the overview, yielding the classes and relationships the section is composed of. Selecting Computer System yields the diagram:

Clearly a Microsoft Word document is not the optimal media to describe the CDM. But the preceding graphic highlights the point that the CDM is very detailed, much more detailed than what is required for BSM, and that only a subset of the data defined by the CDM is needed by TBSM.

Selecting any of the classes or relationships in the preceding diagram will display a textual description of the item selected. For a relationship, the information includes: classes using the relationship, directionality, and diagrams including this interface. For a class, the information includes: derivation hierarchy, attributes, interfaces implemented, relationships, naming rules, and diagrams including this class.

An in-depth discussion of the CDM is far beyond the scope of this paper. The points to be made here are that specific objects within the CDM are of interest when monitoring at the business system level. In some cases it may be as simple as a single object, in other cases it may be a collection of combined objects (a composite) that comprise a meaningful entity. These objects and their relationships with other objects can be imported into TBSM and used to build business services.

Class to Template Mapping

The data stored in TADDM is defined by the CDM. To get from the CDM to the template based structure in TBSM, the toolkit must map between the CDM classes that TBSM receives from TADDM, to the templates defined in TBSM, this mapping is defined by the file CDM_TO_TBSM4x_MAP_Templates.xml. This file does not create or define TBSM templates, it simply maps between the template and the CDM instance. The templates that are referenced are already be defined in TBSM.

The table that follows lists each of the CDM classes, the TADDM base class that they are contained in, and the TBSM template that uses this class, as defined by the CDM_TO_TBSM4x_MAP_Templates.xml that is included with TBSM. The CDM_TO_TBSM4x_MAP_Templates.xml file is a living document; refer to the actual file for the latest mappings.

Note: See $TBSM_HOME/XMLtoolkit/sql/scc_collect_db_info.sql for queries that show the class-to-template mappings.

Table 6 - CDM to TADDM class to TBSM template mappings

The syntax of the XML in this file is documented in the IBM Tivoli Business Service Manager Customization Guide. Using this information, additional classes can be mapped to either existing templates, or to newly created templates.

If resources visible in TADDM are not visible in TBSM after an import, the first item to check is which TADDM class the object belongs, and then check the CDM_TO_TBSM4x_MAP_Templates.xml file to see if the class is mapped to a template. If a class is not mapped, then it will not be visible in TBSM. The TADDM user interface displays a "user-friendly" version of the object type rather than the actual class name.

Figure 19 - TADDM UI showing object type

So a little bit of intuition needs to be used to map between the object type in the TADDM UI and the class name. In this case, if you search the file BaseClassCompleteCMDB.list for SPARC, you will see that the class name is "sys.sun.SunSPARCUnitaryComputerSystem", which has base class "sys.ComputerSystem".

Instance-Based Template Mapping

A new function for TBSM 4.2 is instance-based template mapping. The earlier section discussed mapping CDM classes to TBSM templates using the CDM_TO_TBSM4x_MAP_Templates.xml file. This mapping provides a class to template mapping and was available in previous releases of the toolkit. Instance-based template mapping allows conditional mapping of an instance of a CDM classes to a template. So rather than mapping all instances of a particular class to a particular template, you can now specify that only instances of a class with particular attributes should be mapped to a particular template. Examples of when instance-based template mapping might be used include:

• Specifying that a subset, rather than all, of the IBM Tivoli Monitoring collections should be created as business systems.

• Disabling an instance of a particular class from having a template.

Instance-based templates are defined in the CDM_TO_TBSM4x_MAP_Templates.xml file. They are specified outside of the <classmappings> portion of the document and use the same <Policy> and <Mapping> syntax that is used in the CDM_TO_TBSM4x_MAP.xml file to define composites.

Section 6.5 provides an example that includes instance-based template mapping. This example will provide a better understanding of the mechanics of instance-based template mapping.

Composites

In addition to mapping a specific CDM class to a TBSM template, a collection of CDM classes can be combined into a single object, referred to as a composite. This composite can then be mapped to a template. Composites included with TBSM are defined in the CDM_TO_TBSM4x_MAP.xml file.

The CDM_TO_TBSM4x_MAP.xml file contains policies that define the composite, and mappings that associate a particular CDM class to the policy.

Here's an example of a mapping definition:

Figure 20 - Composite CDM class to policy mapping

This says that a TADDM resource of CDM type cdm:sys.zOS.Sysplex should be examined by policy SysplexComposite to see if the resources should be represented by a composite.

The policy definition defines the requirements needed to represent the resource as a composite. The policy definition for SysplexComposite is shown in Figure 21:

Figure 21 - Composite Policy example

The policy definition states that the resource must have a cdm:hostedCollection relationship with a resource of CDM class cdm:core.SystemSpecificCollection. If the original cdm:sys.zOS.Sysplex resource satisfies this, then the attributes and relationships from the two resources are combined, and represented by a single object that started the examination, in this case a sysplex.

Several composite definitions are included with TBSM, as listed in the following table.

The TBSM Composite column first lists the policy name that represents the composite. The CDM Class column for each composite is broken down into two sections. The first section lists the primary CDM class associated with the composite. The second section lists the secondary CDM classes that are pulled into the composite.
The TBSM Class column lists the tbsm namespace objects created to represent this composite. This column is populated only if the composite creates a name space object.

The mappings in CDM_TO_TBSM4x_MAP_Templates.xml will contain a mapping for the classes in the TBSM Class column. If the TBSM Class column is blank, then there will be a mapping for the primary CDM class in the CDM Class column. The primary class is the first class listed. More advanced composite definitions are capable of creating a new object as a result of the policy that is driven by a CDM object. In the following table those policies that have a value in the TBSM class column are generating new objects.

Table 7 - TBSM Composite definitions and associated CDM and TADDM classes

This file is a living document; refer to the CDM_TO_TBSM4x_MAP.xml file for the latest composite definitions.

Relationships

The CDM defines not only the classes that comprise the model, but the relationships between these classes. Each relationship has a defined source and target class. At times, the source and target order in the model does not match the dependency model defined in TBSM. The toolkit allows for this interpretation to be reversed, either globally or specific to certain classes. The toolkit also allows for a relationship to not be treated as a dependency, which essentially causes the relationship to be ignored. These definitions are in the file CDM_TO_TBSM4x_MAP.xml.

The cdm:systemDependency relationship is an example of ignoring a relationship. This relationship often results in the ball of yarn effect on the topology, as everything tends to appear to be dependent on everything else. Therefore you want to ignore these relationships. Looking in CDM_TO_TBSM4x_MAP.xml you will see the following definition, which causes TBSM to ignore all cdm:systemDependency relationships.

Figure 30 - example of ignoring a relationship

The cdm:memberOf relationship is an example of a relationship that needs to be reversed. In TADDM an AppServer is a memberOf a FunctionalGroup. In TADDM a functionalGroup is a logical grouping. Without reversing the memberOf relationship in CDM_TO_TBSM4x_MAP.xml, the functionalGroup would appear under the AppServer, which is the opposite of what we need. The following definition has been added to CDM_TO_TBSM4x_MAP.xml so that TBSM reverses the direction of the cdm:memberOf relationship.

Figure 31 - example of reversing the relation direction

Template Mapping Example

The CDM_TO_TBSM4x_MAP_Templates.xml file contains several instance-based template mappings. As an example, one of the mappings is discussed in this section.
Outside of the <classmappings> portion of the document you will find the mapping policy as shown in Figure 22 and the mapping template as shown in Figure 23:

Figure 22 - Instance based template mapping policy

Figure 23- Instance based template mapping statements

Similar to the definition of a composite, instance-based template mapping uses <Mapping> tags to associate a CDM class with a policy. In this case, the cdm:sys.ComputerSystem and cdm:sys.UnitaryComputerSystem classes are associated with the "NotComputer" policy.

This is a good example because it will pull in both composite and template mappings. In the <classmappings> section of the CDM_TO_TBSM4x_MAP_Templates.xml document, you have the template mapping:

Figure 24 - BSM_Node template mapping

The mapping shown in Figure 24 indicates that both cdm:sys.ComputerSystem and cdm:sys.UnitaryComputerSystem will both be mapped to the BSM_Node template, in addition to the other classes listed in this <template> definition.

In TBSM 4.1.1 this would have been the end of the story, all objects of these classes would be a BSM_Node. This sounds simple enough, but there is a catch if you look in the CDM_TO_TBSM4x_MAP.xml document. This document contains the composite definitions, and in these definitions you will find:

Figure 25 - Networking composite mappings
These are mappings to build composites for some of the networking resources, and it indicates that the networking resources are also received as cdm:sys.ComputerSystem and cdm:sys.UnitaryComputerSystem. Using a router as an example, the policy for a router is:

Figure 26 - Router composite policy

The mapping indicates that a cdm:sys.ComputerSystem and a cdm:sys.UnitaryComputerSystem should be evaluated against the policy "TBSMRouter". This policy checks to see if the object has the attribute "cdm:Type" and whether it has the value "Router". It then checks to see if the object has a "cdm: Provides" relationship to a "cdm:net.Router" object. If these are true, then a composite is built for class "tbsm:net.Router".

If you look back in the CDM_TO_TBSM4x_MAP_Templates.xml document, you see that "tbsm:net.Router" is mapped to the template BSM_Router.

Figure 27 - Router composite template mapping
So what has been illustrated here? If you say that the resource that is being evaluated is a cdm:sys.UnitaryComputerSystem, then you have mapped it to two templates, BSM_Node and BSM_Router, so you end up with two instances of this resource in the SCR. One instance will be under Servers->All, the other instance will be under Network->Routers. In most cases this is not good, and this is where instance based template mapping comes in. If you go back and look in the CDM_TO_TBSM4x_MAP_Templates.xml document, you will see the following mappings:

Figure 28 - Instance based template NotComputer mappings
This document has associated cdm:sys.UnitaryComputerSystem with the template BSM_Node, but before this mapping is finalized, it will apply the policy "NotComputer". This policy shows:

Figure 29 - Instance based template NotComputer policy

The policy has one rule, and this rule checks the attribute "cdm:Type" for several values, one of which is "Router". Because the object in this example has "Router" for the value of "cdm:Type", we have a match and the template definitions at the bottom of the policy are applied, not the templates named for BSM_Node. Since the policy in this example does not have a template definition, the final outcome is that this resource is not assigned to BSM_Node and therefore is only instantiated as BSM_Router.

Functional Groups

TADDM Business applications group resources within a business application by functional groups. When editing a business application, the functional group to which one or more resources belongs to can be seen in the "Include" pane of the Create Business Application Components dialog box.

Figure 32- TADDM Edit Business Application dialog box
But when the topology for a business application is shown in TADDM, the functional groups are not shown.

Figure 33 - TADDM business application not showing functional groups

TBSM on the other hand includes the functional groups when a TADDM Business Application is shown.

Figure 34 - TBSM topology showing functional groups

For every person that likes seeing the functional groups in TBSM, there is one that prefers not to see them. For those that prefer that the TBSM topology not include the functional groups, making a few changes in the XML configuration files can mask the functional groups.

The first change is to the CDM_TO_TBSM4x_MAP.xml file. TBSM cannot simply ignore the functional group, because the relationships associated with the functional group are needed to tie the business application to the underlying resources. Therefore, what you will do is create a composite, combining the business application and its functional groups. To do this you have to create a policy in CDM_TO_TBSM4x_MAP.xml and map cdm:app.Application, the CDM class representing a business application, to this policy. A policy that accomplishes this is shown below.

Figure 35 - Policy to merge functional groups to applications

You then need to map cdm:app.Application to the MergeFunctionalGroup policy.

Figure 36 - Map policy for functional group merge to app.Application class

Both the policy and the mapping need to go within the <CompositeDefinitions> tags. The specific location within these tags is not important, although to help with maintaining your customization, you might want to keep all changes together.

So to restate the changes to CDM_TO_TBSM4x_MAP.xml, the mapping statement says that for each resource of class cdm:app.Application, run policy MergeFunctionalGroup. The MergeFunctionalGroup policy follows any cdm:contains relationships that the resource may have, and if the target is either: cdm:app.FunctionalGroup, cdm:app.AppServerFunctionalGroup, or cdm:app.SoftwareModuleFunctionalGroup, then the resources are merged into a composite. The resulting behavior is that the application will inherit the relationships of the functional group, thus tying the application to all of the children of the functional group.
So thus far you have merged the application and functional group resources into one resource. One more change is needed. You have to remove the template mapping for the functional groups so that they are not also displayed as separate resources.

Edit CDM_TO_TBSM4x_MAP_Templates.xml and change the BSM_AppLogicalGrouping mapping to look like the following:

Figure 37 - Remove functional group template mapping

The difference here is that the functional group classes are commented out.

After changing the CDM_TO_TBSM4x_MAP.xml and CDM_TO_TBSM4x_MAP_Templates.xml files, stop and then restart the toolkit. After the toolkit has finished initializing, run the following command:

utils -e reload\_cdm\_definitions.xml

When the command finishes running, from the TBSM UI invalidate the Imported Business Service and then refresh the Service Navigation tree. You will see that the functional groups are no longer visible in the UI.

Figure 38 - TBSM UI with functional groups removed

The above topology is a bit hard to read, but looking at the Service Navigation tree you can see that the functional groups are no longer in the tree.

Event to Resource Mapping

The previous sections have focused on discovery, importing data from TADDM, and populating the Service tree and SCR in TBSM. One challenge is to take events received by any of the data fetcher sources, such as NetCool/OMNIbus, and associating these events with the resources that have been imported from TADDM. These events can be from an endless number of sources: Tivoli Monitoring 6.1 or later versions, Tivoli Enterprise Console adapters (customer written, third-party written, IBM written), NetCool/OMNIbus probes, or the mainframe, and the contents of each of these events spans the spectrum from extremely rich to the bare minimum.

In order to associate an event with an imported TADDM resource, you must have some piece of data that is common in both the event and the data imported from TADDM. Every resource imported from TADDM will have one or more BSM_Identity fields built, this occurs as part of the import process. This field will be used to associate events with a resource. The EventIdentifierRules.xml file controls the content of a resource's BSM_Identity field. On the event side, the EIF Probe rules file is responsible for building a BSM_Identity field for the event.

The BSM_Identify is simply a convention, or default, that is used. The unique identifier could be another label specified with the field attribute on the rule definition.

The bottom line here is, there isn't a magic bullet that is going to associate any event from any event source with any and all resources discovered by TADDM. A little work will be needed to make this association. Out of the box, TBSM will associate Tivoli Monitoring 6.x events with Tivoli Monitoring resources that are in TADDM and z/OS events with z/OS DLA resources that are in TADDM.

The TBSM Administrator's Guide discusses the EventIdentifierRules.xml file and the syntax of the file. This should be reviewed to understand the basics of this file.

Defining a Resource's BSM_Identity

The EventIdentifierRules.xml provided with the product will build BSM_Identity values for imported TADDM resources for several specific cases, these cases include: Tivoli Monitoring 6.1 or later version event and resource mapping, z/OS DLA resource mapping, and generic generation of hostname and IP address identifiers. This file can be modified to fit the needs of the events received, and is not restricted to Tivoli Monitoring events or the cases discussed below.

IBM Tivoli Monitoring Resources

The EventIdentifierRules.xml file contains a policy that will build a BSM_Identity that will associate all Tivoli Monitoring 6.x events with their appropriate TADDM resources. If you are running a TADDM version earlier than 7.1, in-order for this to work, the TMS DLA must be run and the book imported into TADDM using the ldfxidml.sh script. Do NOT load the book with loadidml.sh. If you are running TADDM 7.1 or later version, please use loadidml.sh to load the book.

Tivoli Monitoring's unique identifier for resources is the managed system name. All Tivoli Monitoring 6.x events will contain this value and the resources in the TMS DLA book will have the managed system name as an attribute of each resource (cdm:ManagedSystemName). TADDM does not natively discover the managed system name if it discovers a resource that is being managed by Tivoli Monitoring 6.x. By loading the TMS DLA into TADDM, TADDM will reconcile the resources in the book with those resources previously discovered, associating the managed system name with the natively discovered resources. When TBSM imports the resources, it will receive the cdm:ManagedSystemName attribute, which contains the Tivoli Monitoring managed system name.

The EventIdentifierRules.xml file contains a policy and a mapping used to generate the BSM_Identify associated with an Tivoli Monitoring resource.

Figure 39 - eventidentifer policy for Tivoli Monitoring 6.x resources

Figure 40 - eventidentify mapping for Tivoli Monitoring 6.x

The mapping says that the policy "ITM" can be applied to any class and the policy says that if the resource contains an attribute named "cdm:ManagedSystemName", then a BSM_Identity will be built for this resource containing the value in the "cdm:ManagedSystemName" attribute.

An important piece, which will be discussed later in the paper, is that the NetCool/OMNIbus event will have a field in it called BSM_Identity. For Tivoli Monitoring events, this field will contain the managed system name.

The result of this is that any Tivoli Monitoring event received by NetCool/OMNIbus will be mapped to the associated TADDM imported resource because the imported TBSM resource will have a BSM_Identity containing the managed system name that matches the BSM_Identity field in the NetCool/OMNIbus event.

Hostname and IP Addresses

A second policy in EventIdentifierRules.xml will build BSM_Identity's containing the hostname and/or the IP address of any operating system resource. The thought here was that events that need to be posted against TBSM resources that represent an operating system contain either the hostname or the IP address of the computer system. So there is a likelihood that the hostname and IP address are valuable for mapping events for operating system resources.

The policy for building the BSM_Identity for this case is a bit more complex than the Tivoli Monitoring 6.1 policy, and it requires some familiarity with the CDM. Within the policy there are two rules: allIPAddresses and allIPFqdn.

*IP Address:*
<Rule name="allIPAddresses" >           
 <Relationship relationship='cdm:runsOn' relationshipTarget='%' >
  <Relationship relationship='cdm:contains' relationshipTarget='cdm:net.IpInterface' required="true">
   <Relationship relationship='cdm:bindsTo' relationshipTarget='cdm:net.
   IpV4Address;cdm:net.IpV6Address;cdm:net.IpAddress' required="true">
     <Token keyword="ATTR" value="cdm: DotNotation">
       <condition  operator='NOT LIKE' value='10.%'>
        <condition booleanOperator='AND' operator='NOT LIKE' value='192.%'>
         <condition booleanOperator='AND' operator='NOT LIKE' value='169.%'/>
         </condition>
        </condition>
       </Token>
     </Relationship>
   </Relationship>
  </Relationship>
</Rule>

Assume that the resource has the class "cdm:sys.windows.WindowsOperatingSystem", this satisfies the mapping, therefore the rule looks to see if this resource has a "runsOn" relationship with the OS as the source, if so it then checks to see if the target of the "runsOn" has a "contains" relationship with an "net.IpInterface", if that is true it then looks for a "bindsTo" relationship from the "net.IpInterface" with either an IpV4Address, an IpV6Address, or an IpAddress object. If all of this is true, it takes the value of the "cdm: DotNotation" attribute, assuming it does not begin with "10.", "192.", or "169.", and creates a BSM_Identity attribute for the resource. If your network uses IP addresses beginning with "10.", "192.", or "169.", possibly behind a firewall, then the rule must be changed accordingly.
Familiarity of the CDM is helpful here in understanding the relationships between the different CDM classes. To follow this example, it is best to open the CDM.htm that is shown in Section 6.1, and select the "Computer System" area of the graphic. This will open a schematic of the Computer System model. Then locate the OperatingSystem class and follow the links discussed below.

*Hostname:*
<Rule name="allIPFqdn">           
  <Relationship relationship='cdm:runsOn' relationshipTarget='%' >
    <Relationship relationship='cdm:contains' relationshipTarget='cdm:net.IpInterface' required="true">
      <Relationship relationship='cdm:bindsTo' relationshipTarget=
       'cdm:net.IpV4Address;cdm:net.IpV6Address;cdm:net.IpAddress' required="true">
        <Relationship relationship='cdm:assignedTo' relationshipSource='cdm:net.Fqdn' >
           <Token keyword="ATTR" value="cdm:Fqdn">
             <condition  operator='!=' value='localhost'/>
           </Token>
         </Relationship>
       </Relationship>
     </Relationship>
   </Relationship>
 </Rule>

The hostname rule is similar to the IP address rule. Assume that the resource has the class "cdm:sys.windows.WindowsOperatingSystem", the rule looks to see if this resource has a "runsOn" relationship with the OS as the source, if so it then checks to see if the target of the "runsOn" has a "contains" relationship with a "net.IpInterface" object, if that is true it then looks for a "bindsTo" relationship from the "net.IpInterface" with either an IpV4Address, an IpV6Address, or an IpAddress object, and if that is true it looks to see if the source of the "bindsTo" is the target of an "assignedTo" relationship which has a "net.Fqdn" as a source. At this point the contents of the "cdm:Fqdn" attribute is used to create a BSM_Identity assuming the value is not "localhost". Most computers have a "localhost" binding, so this is ignored.

There are several mappings that specify this policy is associated with each of the CDM defined operating systems.

z/OS BSM_Identity

There are several policies in the EventIdentifierRules.xml file that are associated with the CDM classes used by the z/OS DLA, which are not discussed in detail here. The process for understanding these mappings is the same as what was described in the previous policies. The point to be made here is that the information in these mappings takes into account information that is available in events and messages generated by the event pump for z/OS, so the mapping of events in the future should be fairly straightforward.

Default BSM_Identity

If the EventIdentifierRules.xml file does not produce a BSM_Identity, then during the process of loading component registry objects into the TBSM service model, TBSM will assign an identity. The default BSM_Identity is comprised of the resource's name, TADDM GUID, and the CDM class. An example of this is included in the following value:

Figure 41 - sample default BSM_Identify value

This value is not expected to ever match any event received by NetCool/OMNIbus. You probably stand a better chance of visiting Mars than seeing the TADDM GUID in an event. The default BSM_Identity ensures that each resource has a BSM_Identity, and it allows you to easily associate the resource with TADDM's instance because it contains the GUID.

If you have an imported resource that only has a BSM_Identity with the preceding format, this means that none of the policies in EventIdentifierRules.xml matched this resource.

Defining an Event's BSM_Identity

This paper has just described how the BSM_Identity is built when a resource is imported; you now need to focus on how this field is built when an event is received by NetCool/OMNIbus. On the event side, the NetCool/OMNIbus EIF Probe rule file, tivoli_eif.rules, contains logic that will set the BSM_Identity for two cases:

• If the event contains an origin slot, then the origin is used.

• If the event contains a situation_name slot, this indicates that this event is from Tivoli Monitoring 6.1 and then the BSM_Identity is set to the situation_origin. The situation_origin is the Tivoli Monitoring managed system name.

The syntax of the NetCool/OMNIbus Probe Rule files is discussed in the IBM Tivoli NetCool/OMNIbus Probe and Gateway Guide, a link to this can be found in the references section below.

If changes are made to the EventIdentifierRules.xml file to build additional BSM_Identity fields, then corresponding updates need to be made to the Tivoli_eif.rules file so that the two match. This field can consist of a single value:

• @BSM_Identity = $situation_origin

or it can be constructed of a combination of values:

• @BSM_Identity = $situation_name + ":" + $situation_origin + ":" + $situation_displayitem + ":" + $ClassName

Which value or values are used to build the BSM_Identity is dependent on what data is available both within the event, and within the attributes of a resource.

From this common data, a field needs to be built that will uniquely identify the resource.

The Tivoli_eif.rules file is located in /opt/IBM/tivoli/netcool/omnibus/probes/<os>.

The import concept to understand here is that for events to be mapped to the correct TBSM resource, the value placed in the BSM_Identity field of the NetCool/OMNIbus events must match what the BSM_Identity value of the resource was set to during the TBSM import from TADDM.

Service Component Repository

As was mentioned in the introduction, all "physical" resources received from TADDM are placed in the Service Component Repository (SCR). The structure of the SCR is defined in the file BSM_Templates.radsh, and the SCR is only visible in the Service Administrator mode.

While it is suggested that you do not change the BSM_Templates.radsh file, creating a file composed of RADShell statements can modify the structure of the SCR. Using the BSM_Templates.radsh file as an example, you can see the "Unix" portion of the tree is built with the following statements:

addServiceInstance(
new String\[\] \{"SCR\_TopLevelAggregateTemplate" \},
"SCR\_Servers\_Unix",
"Unix",
"",
"Standard",
null,
null,
"REGULAR"
);
clearAllInstanceIDFieldValuePairs(
"SCR\_Servers\_Unix"
);
addUserPreferencesForInstance(
"SCR\_Servers\_Unix",
"Order",
""
);
addUserPreferencesForInstance(
"SCR\_Servers\_Unix",
"Longitude",
""
);
addUserPreferencesForInstance(
"SCR\_Servers\_Unix",
"Latitude",
""
);
addUserPreferencesForInstance(
"SCR\_Servers\_Unix",
"UseGIS",
"false"
);
addUserPreferencesForInstance(
"SCR\_Servers\_Unix",
"classnamefilter",
"'cdm:sys.sun.SunSPARCUnitaryComputerSystem','cdm:sys.sun.SunSPARCVirtualComputerSystem', 
'cdm:sys.openvms.OpenVmsUnitaryComputerSystem','cdm:sys.linux.LinuxUnitaryComputerSystem', 
'cdm:sys.ipso.IPSOUnitaryComputerSystem', 'cdm:sys.hpux.HpUnitaryComputerSystem', 
'cdm:sys.aix.AixUnitaryComputerSystem'"
);

The "addServiceInstance" statement defines the "Unix" portion of the tree.

The "addUserPreferencesForInstance" statement defines the attribute "classnamefilter". This attribute is used to determine which CDM classes will be placed under the "Unix" node. The "classnamefilter" is visible in the additional attributes in the Service Viewer pane.

The contents of a node in the SCR can be altered by either modifying the "classnamefilter" in the Service Viewer or by using radshell to alter the "classnamefilter" attribute.

Rather than using a classnamefilter, some elements in the Component Registry tree are controlled by either a primarytemplatefilter or othertemplatefilter. Rather than using a CDM class name, this filter uses a template name. An example of this can be found in the definition of the SCR_SybaseDatabases definitions:

addUserPreferencesForInstance(
"SCR_SybaseDatabases",
"primarytemplatefilter",
" 'BSM_SybaseDatabaseServer','BSM_SybaseDatabase' "
);

This restricts the contents of the Sybase database instances to those using the templates: BSM_SybsaeDatabaseServer or BSM_SybaseDatabase.

An "addServiceInstanceDependency" statement builds the structure of the SCR, for the "Unix" node the following statement indicates that "Unix" is a dependent of SCR_NodesRepository.

addServiceInstanceDependency(
"SCR_NodesRepository",
"SCR_Servers_Windows"
);

The SCR_NodesRepository is the "Servers" node, as shown by the following statement:

addServiceInstance(
new String[] {"SCR_RootTemplate" },
"SCR_NodesRepository",
"Servers",
"",
"Standard",
null,
null,
"REGULAR"
);

Runtime Monitoring

The TBSM Discovery Library toolkit runs as a service/daemon, and therefore does not have a user interface from which it can provide feedback. The state of the service can be monitored through the service's message log. TBSM provides three levels of messaging: Informational, Warning, and Error. Error provides minimal logging and is recommended for normal operation. Warning provides additional feedback when additional information is needed for longer operations as an assurance that some work truly is being done. Informational is used for debugging problems, and is not recommended because of the additional overhead.

TBSM also provides three levels of tracing: Min, Mid, and Max. Tracing is generally only used by IBM Soffware Support to debug problems. Min should be used for normal operation, and Max for problem determination. Max can be very I/O intensive and is only recommended if requested by IBM service personnel.

The message and trace logs are written to the $TBSM_HOME/XMLtoolkit/log directory. The message log is msgGTM_XT.log. The trace log is traceGTM_XT.log.

Error Message Logging

When TBSM begins a TADDM import, the following message will be written to the message log:

GTMCL5292I: Beginning CMDB import. Bulk: <t/f> Hostname: <taddmHostName>

Where:

• <t/f> is "true" if this is a bulk import and false if this is a delta import.

• <taddmHostName> is the TADDM Server that the import is running against.

When all data has been received from TADDM, the following message is displayed. The remaining processing is within the TBSM database.

GTMCL5283I: Data retrieval completed.

When the TADDM import has finished, one of three messages will be displayed:

• GTMCL5306I: CMDB import completed successfully, no additional resource were found.
  • This message is only issued for a delta, and indicates that the delta finished successfully, but there were no new, changed, or deleted resources in TADDM, so no updates were made in TBSM.

• GTMCL5293I: CMDB import completed successfully.
  • This message is issued for both a bulk and a delta import, and indicates that the import finished successfully, and that changes were made in the TBSM database.

• GTMCL5294W: CMDB import did not complete successfully.
  • This message is issued for both a bulk and a delta import, and indicates that an error occurred during the import and the import did not finish successfully. The log should be examined for exception messages prior to this message.

Warning Logging

With respect to TADDM imports, the warning level provides additional feedback as the import runs. Some bulk imports can take an extended period of time, and the time between the GTM5292I and one of the three completion messages mentioned above can leave you wondering whether there really is work being done. When messaging is set to Warning, two additional messages are written to the log:

• GTMCL5282I: Requested data from the database. Issued: <operation> Received <n> instances of the requested data.
  • This message includes the type of request made to TADDM and the number of instances of data that were returned. The type of request can be either a find() or a
    findChanges(). The find() is used for bulk imports and requests all data for a particular class. The findChanges() is used for delta imports and requests any changed objects for a particular class within a given timeframe. This message will be written for each TADDM base class that is of interest to TBSM.

Informational Logging

When the message logging is set to Informational, the messages written to msgGTM_XT.log can be fairly verbose. Generally each step of the import process is recorded. Additional messages include:

• GTMCL5321I: Issue generateExplicitRelationship. Delta Mode <true|false>.

• GTMCL5322I: The generateExplicitRelationship has finished

• GTMCL5317I: Request data from the CMDB database: <classname>

• GTMCL5318I: Begin SQL file execution: <sqlName>

• GTMCL5319I: SQL file execution complete.

• GTMCL5258I: Starting Transform: <transformName>

• GTMCL5259I: Transform complete: <transformName>

Troubleshooting

Known Issues:

The most common issue is that a resource is not displayed in the TBSM UI. There are three general causes for this:

• The templates are not loaded. If this is the case, then run the following command:
  • UNIX: cat $TBSM_HOME/install/BSM_Templates.radsh | $TBSM_HOME/bin/rad_radshell
  • Windows: type $TBSM_HOME/install/BSM_Templates.radsh | $TBSM_HOME/bin/rad_radshell

• A template mapping was recently changed or is missing. If the CDM_TO_TBSM41x_MAP.xml or CDM_TO_TBSM41x_Templates.xml files were recently changed, then validate the change and run with the old copy if resources that were previously visible are no longer visible.
  Verify that the CDM class representing the resource has a mapping in the CDM_TO_TBSM41x_Templates.xml file.

• The dependency counters in the database are incorrect. To correct this, run the "utils -e validate_dependency_counters.xml" command. After running this command, select the Imported Business Service in the UI, invalidate it, and then refresh the Service Navigation tree.

Data Collection

If problems occur, the first place to look is in the msgGTM_XT.log file. This file records all exceptions detected by the toolkit. If the msgGTM_XT.log file does not help to resolve the issue, and IBM service is called, the following files should be saved and sent in:

• The contents of the $TBSM_HOME/XMLtoolkit/sdk/log directory

• Run "utils -e collect_db_info.xml", which writes a file to the XMLtoolkit/log directory

• The contents of the $TBSM_HOME/XMLtoolkit/log directory

• The filter files located in $TBSM_HOME/XMLtoolkit/config/filters

• The customized XML files located in $TBSM_HOME/XMLtoolkit/xml:

• • CDM_TO_TBSM4x_MAP.xml

• • CDM_TO_TBSM4x_MAP_Templates.xml

• • EventIdentifierRules.xml

• • LabelingRules.xml

• The two or three files in $TBSM_HOME/XMLtoolkit/xml/scr/out associated with the bulk or delta import. Each bulk or delta import will generate two or three files. They have the format: taddm.<date>.<time>.refresh.xml.<tag>. The <date>.<time> corresponds to when the import was started. Samples are:

• • taddm.2007-08-09T19-36-17Z.refresh.xml.1.sql

• • taddm.2007-08-09T19-36-17Z.refresh.xml.2.label <may not be generated>

• • taddm.2007-08-09T19-36-17Z.refresh.xml.2.sql

XML File Syntax Errors

If a problem occurs with an XML configuration file after editing the file, simple syntax errors in XML files can be found by attempting to open the XML file in a browser. This will not check whether the file follows a specific schema, but it will verify the basic XML syntax.

Analyzing the SQL Tables

The SCR is comprised of a series of tables and views stored in TBSM's PostgreSQL database. The schema is not published, but a series of SQL statements are provided that give insight as to the type and quantity of data that has been imported from TADDM. The "utils -e collect_db_info.xml" command will run these SQL statements and collect database specific information. An example of the information provided is:

• A list of the CDM classes imported and the number of each

• A list of CDM classes mapped to templates and to which template they are mapped.

• A list of CDM classes that are not mapped to a template.

• A list of CDM classes that are not mapped to a template and also not part of a composite object.

• Types of CDM relationships received and the number of each.

The output from the utils command is written to the $TBSM_HOME/XMLtoolit/log directory.

Depending on the size of the database, some of the SQL queries may take a long time to complete.

Loading DLA Books into TADDM

If problems occur after loading a DLA book into TADDM, the following files are required to diagnose the problem:

• The original DLA book XML file

• The TADDM bulk load results file. This file is located in $COLLATION_HOME/bulk/results. The results file will have the same file name as the originating XML file, but will have a results extension.

• The API server log. This file is: $COLLATION_HOME/log/services/ApiServer.log.

• The topology manager log file. This file is: $COLLATION_HOME /log/services/ToplologyManager.log.

• The bulk loader log file. This file is: $COLLATION_HOME /log/bulkload.log.

In the $COLLATION_HOME /etc directory, the file bulkload.readme contains information on the bulk loader.

Removing All Resources from the SCR

If at some point the data from TADDM needs to be removed from the SCR, this is a fairly simple process. The first step is to remove all of the data from the tables used by the toolkit. To do this:

• Stop the TBSM toolkit
• Run the command, "setdbschema -U <dbuser> -f a"

The setdbschema command will drop and recreate all of the tables associated with the toolkit, so all data previously imported from TADDM will be deleted.
After running the setdbschema command, from the TBSM UI, invalidate the Imported Business Service.

Invalidating will force the ESDA associated with the toolkit to run, because the toolkit's tables are now empty, this will force the deletion of any records associated with the toolkit. When the invalidation is finished, refresh the Service Navigation tree. The invalidate might take some time if there is a large amount of data under the Imported Business Service.

An alternative to invalidating the Imported Business Service is to recycle the TBSM Data Sever. In TBSM 4.1, the process of restarting the TBSM Data Server forces the ESDA to run, but this is no longer true in TBSM 4.2.

Best Practices

This section specifies best practices for TBSM integration with TADDM. It sets a series of recommendations designed to promote more effective integration and a positive user experience. It includes suggestions to keep TBSM-imported TADDM data intact, improve the visual experience across products, utilize the functions provided by both products and more. Each recommendation is discussed in detail with scenario descriptions and solution options.

Impact of Change History Pruning on TBSM Delta Import from TADDM

When TBSM initiates a delta import with TADDM, it relies on the TADDM change history information to determine which objects have been created, modified or deleted in TADDM since the last import. Only the changed objects will be imported into TBSM.

If a database administrator prunes change history information from the TADDM database after the last TBSM import, but before the next delta import, it might affect the next import. Some data changed after the last import and before the change history pruning will not be imported into TBSM through the delta import, because the change history information has been pruned.

TADDM's guideline for database administrator is to prune the change_history_table data that is more than 4-6 weeks old. See TADDM 7.1.2 Administrator's Guide, "Chapter 5. Polulating the database", Section "Maintenance tips for database". If your database administrator has been following this guidance and the TBSM administrator is using the default import interval, which is less than a day, TBSM delta import will not be affected by normal TADDM change_history_table pruning.
If TBSM has not imported data for more than 4 weeks, for example, TBSM has been down for more than 4 weeks or TBSM is being installed more than 4 weeks after TADDM was installed, the solution is to rebuild the TADDM relations table and then run a TBSM bulk import. This process varies depending on the level of TADDM:

• TADDM 7.1 and earlier

• • On the TADDM server, run: "/opt/IBM/cmdb/dist/bin/explicitrel.sh 0" (that is a zero)

• • On the TBSM server, run: "/opt/IBM/tivoli/tbsm/XMLtoolkit/bin/cmdbdiscovery.sh -b -r -e"

• TADDM 7.1.2 and later

• • On the TBSM server, run: "/opt/IBM/tivoli/tbsm/XMLtoolkit/bin/cmdbdiscovery.sh -b -r -e"

Rebuilding the TADDM relations table can be a lengthy process, so plan accordingly.

How to orchestrate Discovery, Bulkload, TADDM Domain to eCMDB Synchronization, and TBSM Import from TADDM

The timing of TADDM discovery, bulkload, and synchronization operations can impact TBSM data imports. This section describes the interaction between these operations and the effect of these operations on TBSM imports of TADDM data.

TBSM data import from a stand-alone TADDM server

Figure 12 shows TBSM configured to import data from a typical TADDM stand-alone server in a non-enterprise environment. Resources may be discovered by the TADDM server, bulkloaded into the TADDM server via IDML books or manually added through TADDM UI or API. TBSM can import data from the TADDM server.
TBSM data import will check to see if a TADDM discovery or bulkload is running before starting the import. If one of these TADDM operations is in progress, TBSM will wait for it to complete before starting an import from TADDM. So a TBSM data import cannot start while a TADDM discovery or bulkload is in progress.

Figure 42 - TBSM configured to import data from a standalone TADDM server

TBSM data import from an enterprise TADDM server

Note: TBSM does not support importing from TADDM 7.1 or earlier eCMDB server. While it can be made to work if care is taken with regard to timing between domain discoveries, eCMBD synchronization, and TBSM import, it is not recommended.

Figure 28 shows TBSM configured to import data from a typical TADDM enterprise **environment, consisting of a TADDM eCMDB (Enterprise Configuration Management Database) and multiple TADDM domains connected to that eCMDB.

Resources can be discovered, bulkloaded, or manually created through the TADDM UI or API at the TADDM domain server. Resources can also be bulkloaded or created through the TADDM UI or API at the eCMDB server. An eCMDB synchronizes information from the TADDM domains.

In the TADDM enterprise environment, TBSM integrates to TADDM by connecting to and import data from TADDM eCMDB server.

Figure 43 - TBSM configured to import from a TADDM eCMDB server

Similar to stand-alone TADDM server environments, TBSM data import checks to see if a bulkload is in progress on the TADDM eCMDB server before it starts the import action. (TADDM eCMDB server does not provide discovery function.) If a bulkload is in progress TBSM will wait until the bulkload completes before it starts the data import from TADDM. So a TADDM eCMDB bulkload and a TBSM data import from an eCMDB server cannot be performed in parallel.

A TBSM delta import of data from TADDM relies on change history data present in the TADDM database. In TBSM-TADDM enterprise integration environments, make sure change history data is synchronized from domains to the eCMDB. **To enable a TADDM domain to synchronize change history data with an eCMDB, on the eCMDB computer, make sure the following line is not listed in $COLLATION_HOME/etc/sync/table.skip:

change_history_table

If TADDM is configured as suggested above, a TBSM delta import can be done at any time, irrespective of TADDM domain-eCMDB synchronization.
Because a TBSM bulk import from TADDM retrieves all CI types needed by TBSM from TADDM, it can be done at any time and does not require the configuration steps discussed above.

If a TADDM domain-eCMDB synchronization is in progress when a TBSM import is started, any updated CIs will be retrieved during the subsequent TBSM delta import. If a TBSM import from TADDM is initiated while a bulkload or discovery is running in TADDM, the TBSM import will wait until that operation completes.

Summary

The important points to remember about performing TBSM data imports from TADDM are the following:

Stand-alone TADDM server environments:

If a TADDM discovery or bulkload is in progress, TBSM will recognize that discovery or bulkload is in progress and wait until it is completed before continue with data import.

TADDM enterprise environments:

If a TADDM discovery or bulkload is in progress, TBSM will recognize that discovery or bulkload is in progress and wait until it is completed before continue with data import.

Make sure the following line is not listed in the eCMDB file $COLLATION_HOME/etc/sync/table.skip to enable TBSM delta data imports from TADDM:
change_history_table

How to Keep TADDM and TBSM Object Display Names Consistent

Components discovered in TADDM usually have generated display names in TADDM. The display names are imported into TBSM during data import, so the same display names are displayed in TBSM.

Both TADDM and TBSM allow you to change the display name of an object. If you want to change an object's display name and see the same name used in both TADDM and TBSM, the display name should be changed in TADDM. TBSM data import will load the changed display name into TBSM and use it as display name on the TBSM UI. If you change the display name in TBSM, TADDM cannot obtain and use the change.

How to change a display name in TADDM

The following instructions illustrate how to change a display name in TADDM.

1. Select an object from the tree view or topology view on the TADDM UI, right-click, and then select Edit from drop-down menu. The screen capture below shows an example of how to edit the object from the TADDM tree view.

Figure 44 - Edit the component from the tree view

2. An Edit Component window will open as shown in the screen capture below. Depending on whether a label has been set for the object before, the label field may be populated with a value or it may be blank.

Figure 45 - Edit Component popup window

3. Edit the Label field in the Edit Component window as shown in he screen capture below and enter the display name for the object you want to see on the TADDM UI. Then click the "OK" button to save.

Figure 46 - Edit the Label field

4. Reload the TADDM UI and go to the same object. You will see its display name has changed to the new value set in step 3, as shown in the screen captures below.

Figure 47 - New display name used by the tree view

Figure 48 - New display name used by the details panel

5. After the next TBSM data import to pick up the TADDM changes, you will see the new display name shown on TBSM UI as well, as shown in the screen captures below below.

Figure 49 - New display name used by the TBSM UI tree view

Figure 50 - New display name used by the TBSM UI edit panel

Where to Define Business Services

TBSM and TADDM both model business services and provide function to allow users to define business services, so is it best to create your business services in TBSM or TADDM?

TADDM models business applications and business services. A business service can include one or more business applications. It can also include other business services. TADDM users can manually create business applications or business services through the UI or API. TADDM also provides application descriptors to automate the creation and maintenance of business applications through discovery. TBSM can import TADDM's business applications and business services. Business applications in TADDM appear as business services in TBSM.

TBSM models business services. TBSM users can define business services manually, automatically through autopop rules, or through an ESDA. Business services defined in TBSM can be bulk loaded into TADDM using a discovery library adaptor via the TADDM loadidml script. Business services defined in TBSM are displayed as business services in TADDM.

This leads to the question, which is the best approach? The answer to this question is not as simple as simply TBSM or TADDM because the answer involves not just these two products, but also the overall system architecture. A basic order of precedence is:

• If TADDM application descriptor files are being implemented and deployed, and TADDM will discover all components of your business system, then TADDM is the location to build your business services.

• If TADDM application descriptor files are being implemented and deployed, but TADDM will only discover pieces of your business system, build the business service in TADDM using the application descriptor files. This business application can then be imported into TBSM and added to the business service built in TBSM that contains the additional components of the business service.

• If the components of the business systems are discovered through a variety of means, one being TADDM, the process will be to manually construct the business services, or an automated approach in TBSM is being used, then TBSM is the location to build your business services.

When to use TADDM

Use TADDM to define and maintain your business services and applications when:

1. Application descriptors can be used to define and maintain your business applications automatically in TADDM.
2. All the components of your business application or business service are stored in TADDM.

Using application descriptors

IBM application descriptors are application tags that TADDM uses to automatically associate components with business applications, eliminating manual creation and maintenance of business applications. When application descriptors are used to define business applications, TADDM can collect the information defined in these application descriptors and create and maintain business applications automatically for you through discovery. During a TBSM data import from TADDM, these TADDM business applications are loaded into TBSM as business services. Any changes to these business applications that are detected by discovery and stored in TADDM will be imported into TBSM.

For more information regarding application descriptors, see the "Application descriptors" chapter in the IBM Tivoli Application Dependency Discovery User's Guide.

Benefit:

TADDM automatically takes care of business application creation and maintenance. Changes that TADDM detects and stores will be loaded into TBSM during data import. The use of business application descriptors eliminates the manual process of creating business applications and keeps your business application information up-to-date.

Manually define business applications and services in TADDM

The TADDM UI provides functions to manually create business applications and business services. Users can easily select and include the components from a list of available resources stored in TADDM. See the following instructions regarding how to define business applications and services using the TADDM UI.

Instructions for defining business applications:

1. Select Create Business Application from the Edit menu as shown in the screen capture below.

Figure 51 - Select "Create Business Application"

2. Input general information in the pop-up window and click Next>> as in the screen capture below.

Figure 52 - Define general information

3. Define application components by selecting the component from available component list on the left side and then click the Add>> button to add them to a functional group. The selected components will be included in the list on the right. When you finish selecting all the included components, click Next>> as shown in the screen capture below.

Figure 53 - Select business application components

4. Define administrative information if applicable, and then click Finish as shown in the screen capture below.

Figure 54 - Define administrative information

Instructions for defining business services

1. Create a business service. Select Create Business Service from the Edit menu as shown in the screen capture below.

Figure 55 - Select "Create Business Service"

2. Input general information in the pop-up window, then click Next>> as shown in The screen capture below.

Figure 56 - Define general information

3. Define business service components by select the component from available component list on the left side, click Add>> button to add them to the included list on the right. When you finish selecting all the included components, click Next>> as shown in the screen capture below.

Figure 57 - Select business service components

4. Define administrative information if applicable, and then click Finish as shown in the screen capture below.

Figure 58 - Define administrative information

When to use TBSM

TBSM can load data from TADDM as well as a variety of other data sources. These other data sources include NetCool/OMNIbus events and external databases. If your business service includes resources from a data source other than TADDM or is a combination of data sources that may include TADDM, you can manually define the business service in TBSM.

In addition to manually creating business services in TBSM, an automated approach can also be used. An automated approach can include using auto-pop rules if the events received from NetCool/OMNIbus are rich enough, or an ESDA can be written if data is kept in an external database.

If events are used for service creation, but they are not rich enough to build a complete service hierarchy, the events can be enriched using information from an external database, and then auto-pop rules can be used to create the business services. The details of this approach will be left for another paper.
TBSM business services can be imported into TADDM via a bulkload of TBSM resources.

Instructions for manually defining business service

1. After logging into the TBSM UI, under the "All tasks" view on the left panel, expand Tivoli Business Service Manager and click Service Administration, as shown in the screen capture below.

Figure 59- Click on the "Service Administration" task

2. The "Service Administration" panel will show up in the UI to the right. Click the Create New Service icon as shown in the screen capture below.

Figure 60 - Click on the "Create New Service" icon

3. A service editor will be displayed on the right panel. Enter the information for your business service, and then click on the disk icon on upper-left corner to save as shown in the screen capture below.

Figure 61 - Enter service information to define the new service

4. After the save completes, the newly created services will be displayed under services as shown in the screen capture below.

Figure 62 - The new created service is listed under "Services"

Appendix

TBSM Configuration with TADDM 7.1

If TBSM 4.2 is importing data from TADDM 7.1, the following additional configuration must be made.

TBSM Configuration

The following sections include information about TBSM configuration

API JAR Files

The TBSM Discovery Library toolkit uses TADDM's Java API to retrieve data from TADDM. This API requires that the API jar files used by TBSM be the same as those used by the TADDM server. Therefore, before starting the toolkit, these files must be copied from the TADDM server to the TBSM server.
The files can be found on the TADDM server in /opt/IBM/cmdb/dist/sdk/lib and replace the files on the TBSM server in $TBSM_HOME/XMLtoolkit/sdk/lib.
Even though TBSM only uses a subset of the jar files, all of the files should be copied. The files that are required can change between releases; therefore it is safer to copy all of the files.

TADDM fix packs can contain changes reflecting changes to the CDM. These types of changes can affect the objects received by the TADDM API. Therefore, these files should be recopied to the TBSM server anytime that a TADDM fix pack is installed. Not updating these files on the TBSM server will result in random exceptions when data is copied from TADDM to TBSM.

These exceptions are written to the $TBSM_HOME/XMLtoolkit/log/msgGTM_XT.log file.

System Clocks

Delta imports rely on timestamps to determine which TADDM classes have updated objects. The timestamp is based on the previous import. If the TADDM system clock is behind the TBSM clock, there can be a window that will allow an object change in TADDM to not be seen by TBSM. The TADDM system clock should either be synchronized with the TBSM server's system clock, or ahead of TBSM's clock. The window occurs only if the TADDM clock is behind TBSM's clock.

TADDM Database Access - Performance

TBSM 4.2 allows the option of directly querying the TADDM database via JDBC for specific high-volume transactions. This can reduce the data import times for large TADDM data models. These transactions are associated with retrieving relationship data. Two configuration steps are required:

• Run the taddmdirect script to enable the JDBC function. Sample invocation: "taddmdirect -enable -t DB2 -h ktaddm2.ibm.com -d cmdb -p 50000 -s db2inst1". Issue "taddmdirect -?" for complete usage information.

• Run the setxmlaccess script for the TADDM database userid and password. Sample invocation: "setxmlaccess -taddmdbid db2inst1 -taddmdbpw dbpw1234". Issue "setxmlaccess -?" for complete usage information.

Enhancements in the TADDM 7.1.2 API negate the need for this function when importing from levels later than TADDM 7.1, but if you are running TADDM 7.1, take advantage of the taddmdirect feature.
Configuring the taddmdirect feature is strongly recommended.

TADDM Configuration

The following sections include information about TADDM configuration.

Properties

The TADDM property generateExplicitRelationships controls whether TADDM generates additional relationships defined in the CDM and used by the TBSM import. If these relationships are not available to TBSM, TBSM will not be able to correctly recognize and display the objects received from TADDM.

Set the TADDM property generateExplicitRelationships=false and the TBSM property DL_TADDM_ExplicitRelationship=true (the default is true for TBSM).

API JAR Files

Again, simply a reminder that if a TADDM fix-pack is installed, then the jar files in .../dist/sdk/lib must be updated on the TBSM server. It cannot be stressed enough about how important this is.

System Clock

Again, simply a reminder to avoid having the TADDM server's system clock fall behind the TBSM server's system clock.

Scheduling Discoveries

The TADDM 7.1 API will not prevent a discovery from starting during critical sections of the TBSM import, to prevent data synchronization issues, a TADDM discovery should not be started while a TBSM import is running.

References

[1] IBM Tivoli Business Service Manager Version 4.2, Service Configuration Guide_,_ SC23-6041-02

[2] IBM Tivoli Business Service Manager Version 4.2, Customization Guide, SC23-6042-02

[3] IBM Tivoli Business Service Manager Version 4.2, Administrator's Guide , SC23-6040-02: For the above TBSM 4.2 publications, use a web browser to access the following URL and then select Business Service Manager in the contents list.:
+http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?toc=/com.ibm.tivoli.itbsm.doc/toc.xml+

[4] Discovery Process in TBSM 4.1 - Mechanism and Customization

[5] TBSM V4.1 and ITCAM for SOA V6.1: Status Event Integration

For the above TBSM Articles in the IBM Tivoli Open Process Automation Library, access:

http://catalog.lotus.com/wps/portal/tbsm

[6] Architecture, Deployment, Scalability, and Performance Overview

For the above TADDM Article in the IBM Tivoli Open Process Automation Library, access:

http://catalog.lotus.com/wps/portal/tccmd

[7] IBM Common Data Model, a description can be found on the TADDM server installation in the .../dist/sdk/docs/CDMWebsite.zip file. Unzipped, this file contains a complete description of the IBM Common Data Model. The misc directory contains CDM.htm, open this file as a starting point.

[8] IBM Tivoli Netcool/OMNIbus V7.1 Probe and Gateway Guide

For the above NetCool/OMNIbus publication, use a web browser to access:
+http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.netcool\_OMNIbus.doc/welcome.htm+

[9] IBM Tivoli Application Dependency Discovery Manager Configuring and Administering Guide

[10] IBM Tivoli Application Dependency Discovery Manager Using
For the above TADDM publications, use a web browser to access:
http://publib.boulder.ibm.com/infocenter/tivihelp/v10r1/index.jsp?topic=/com.ibm.taddm.doc\_7.1.2/cmdb\_welcome.html

[11] IBM Tivoli Application Dependency Discovery Manager Wiki
http://www.ibm.com/developerworks/wikis/display/tivoliaddm/Home

[12] IBM Tivoli Business Service Manager Wiki
http://www.ibm.com/developerworks/wikis/display/tivolibsm/Home