Business Service Management

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

Integrating TBSM 4.1 with Tivoli Application Dependency Discovery Manager

This topic focuses on the integration between IBM® Tivoli® Business Service Manager (TBSM) and IBM Tivoli Application Dependency Discovery Manager (TADDM). This integration involves the importing of data from TADDM into TBSM. The import includes TADDM Business Applications and Business Services, which will be added to the TBSM list of services, and also the physical TADDM CIs, which will be added to the TBSM 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 are 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 IBM Tivoli Monitoring and ITCAM for SOA. These papers are listed in the references below, and we urge you to also read these papers 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 includes customization, but focus more on the mechanics involved in the TADDM integration and on issues that have come up over the past few months as customers have worked to implement this integration.

The features mentioned in this paper on based on TBSM 4.1 IF7. Earlier levels of the product might not include all of the functionality mentioned in this paper.

Overview

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 primarily focuses on the toolkit's interface with TADDM, although many of the principles discussed here are also applicable to DLA books.

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.

The following image shows the integration flow between TBSM and TADDM:

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 then updates 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 would update objects A and B, object C would be deleted, and object D would be 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 queried. Requests interface with TADDM through the TADDMs Java API. This API is provided by a series of JAR files that are maintained on both the TADDM server and the TBSM server.

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.

The data stored in the SCR is pulled into the TBSM server through an ESDA. This ESDA populates the Service Component Repository tab in the TBSM UI. All "physical" resources received from TADDM are placed in the Service Component Repository. The following example shows the Apache Web Servers displayed in TADDM that can be found in the TBSM Service Component Repository under the Application Servers, HTTP Servers.

The following image shows the TBSM view of imported Web Servers.

The following image shows a TADDM business application.

Business Applications and Business Services defined in TADDM will also populate the TBSM service tree. In the example below, the HR_Business_Application in TADDM is placed in the TBSM Service tree under the Imported Business Services.

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 by way of relationships provided by TADDM are also added to the service. Relationships are followed, pulling in dependent objects until additional relationships 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 effected object in the Imported Business Service. This invalidation causes the ESDA to run and to populate the services automatically. When the Service Navigation is refreshed, the new resources are displayed.

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, then refresh the Service Navigation.

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.

Selecting the Add from Service Component Repository button opens a window that contains the Component Registry tree. The tree can be expanded and the required resources selected.

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

The TBSM Discovery Library toolkit installs a set of templates and mappings that transforms 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 launch 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 ITM and z/OS events to resources that have been loaded into TADDM by way of the TMS and z/OS DLAs.

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

As provided, the TBSM Discovery Library toolkit collects and displays information that is stored in TADDM, but there are configuration tasks that can be made to make this integration run more smoothly.

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 are items have caused a few problems in the past.

Database

The PostgreSQL database is used by both the TBSM server and the TBSM Discovery Library toolkit and requires configuration changes in-order to run optimally. This is discussed more thoroughly in the white paper, "Tivoli Business Service Manager 4.1 Tuning Recommendations". The primary changes required for the toolkit are:

$NCHOME/etc/rad/rad_dbconf

This file contains a number of server configuration items. On Unix platforms, the database properties in this file override the values in $NCHOME/platform/<os>/pgsql8/data/postgresql.conf. The required change is:

PG_BUFFER=4000

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 might 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.

$NCHOME/platform/<os>/pgsql8/data/postgresql.conf

This is the primary configuration file for PostgreSQL. The following table shows the values that should be changed.

API JAR Files

The TBSM Discovery Library toolkit uses the TADDM 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 $NCHOME/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 fixpacks 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 any time that a TADDM fixpack is installed. Not updating these files on the TBSM server results in random exceptions when data is copied from TADDM to TBSM. There are exceptions:

• Unmarshalling errors, which indicates 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.

User ID and Password

The TBSM Discovery Library toolkit installation prompts for the TADDM user ID and password. These values are encrypted and stored on disk. If either value is incorrect, a connection exception is logged in the $NCHOME/XMLtoolkit/log/msgGTM_XT.log message 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 ID and password values 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 syntax for this command is:

setxmlaccess -U dbID:tbsmID:taddmID -P dbPW:tbsmPW:taddmPW

The command requires that all three (PostgreSQL, TBSM, and TADDM) user ID and password values be supplied when changing any pair. The command is documented in the TBSM Administrator Guide, and online help is available by entering the following command

setxmlaccess -?

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 only occurs if the TADDM clock is behind TBSM's clock.

Properties

The TBSM toolkit service is controlled through the property file xmltoolkitsvc.properties. 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:

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.

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. There are two options for the generation of these relationships:

• Set the above TADDM property generateExplicitRelationships to true, and TADDM will generate the relationships as a part of the TADDM discovery process. If this property is set to true, it can increase the TADDM discovery performance by up to thirty percent.

• Set the above property to false, and let TBSM request generation of the relationships each time that TBSM begins an import. If the TBSM property file $NCHOME/XMLtoolkit/bin/xmltoolkitsvc.properties specifies
  DL_TADDM_ExplicitRelationship=false, then the TADDM property file collation.properties must have generateExplicitRelationships=true or the explicitrel.sh must be manually run on the TADDM server before the TBSM import is run.

It is recommended setting the TADDM property generateExplicitRelationships=false and
the TBSM property DL_TADDM_ExplicitRelationship=true (the default is true for TBSM).
This requires TADDM 5.1.1.3 IF2 and TBSM 4.1 IF7.

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. We cannot stress 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.

Database

The performance of the TADDM database is paramount in the overall performance of the TADDM/TBSM integration. If using DB2, the following items are suggested:

• Database configuration update
  
  

  UPDATE DATABASE CONFIG FOR <dbname> USING
  DBHEAP 1800
  DFT_DEGREE ANY
  LOGBUFSZ 1024
  LOCKLIST 1500
  NUM_IOCLEANERS 9
  NUM_IOSERVERS 17
  LOGFILSIZ 8192
  LOGPRIMARY 6
  NEWLOGPATH /mnt/dblogs/<dbname>
  APP_CTL_HEAP_SZ 1024
  SORTHEAP 32768;

• Bufferpool Updates
  
  

  ALTER BUFFERPOOL IBMDEFAULTBP
  SIZE 200000;
  ALTER BUFFERPOOL BUF8K
  SIZE 6000;
  ALTER BUFFERPOOL BUF32K
  SIZE 5000;

It is also suggested that you review the Architecture, Deployment, Scalability, and Performance Overview paper noted in the references.

Loading DLA Books

This is not specifically a configuration item, but an item to be aware of. TADDM can consume Discovery Library Adapter (DLA) books. Books exist for ITM, zOS, and ITCAM for SOA to name a few. Two scripts are available for loading DLA books into TADDM:

ldfxidml.sh and loadidml.sh.

If you are loading a book that contains data where by looking up the IP address in a computer system might help to reconcile data with a natively discovered resource, then the ldfxidml.sh script should be used.

If you are loading an ITM book into TADDM, then ldfxidml.sh should always be used. Not using the ldfxidml.sh script for ITM books can result in duplicate resources and natively discovered resources that are not associated with the ITM managed system name.

See Loading DLA Books into TADDM and Known Issues for additional information.

Note: TADDM 7.1 merged the ldfxidml.sh and loadidml.sh scripts, only the loadidml.sh script is available in TADDM 7.1.

Runtime

The toolkit is designed to run as a background process. 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 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 in TADDM that changed between the last import and the current time. This is why it is important that the system clocks be somewhat in synch. 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 irregardless of the polling interval. To request a bulk, specify the command "cmdbdiscovery -b -r". To request a delta, specify the command "cmdbdiscovery -r". The requested operation will start within sixty seconds.

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 BaseClass filters
• TADDM SubClass filters
• Attribute Global filters
• Attribute Class filters

One point should be made here, while any of the objects in TADDM can potentially 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 when a particular filter is applied and the files associated with each of the filters.

The filter files are located in $NCHOME/XMLtoolkit/config. These files are filters, the classes and attributes specified in them will be excluded from the TADDM data that is imported into TBSM. Entries in these files beginning with "//" are considered comments and are ignored.

As mentioned earlier, the out of the box the filters block only a limited amount of data. The 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 most data initially, and then remove filters as different types of information are needed in TBSM. In the future we will probably provide more filtering. There is additional discussion on this 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 $NCHOME/XMLtoolkit/config directory:

• BaseClassCMDB.list - 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. This is a bit misleading because while the metadata may indicate that the class does not have a parent, the same class may later show-up as a child of another class. This doesn't provide an issue with respect to the base class filtering, but it is information that will be needed when filtering by child classes. This is where the BaseClassCompleteCMDB.list helps. A sample entry in BaseClassCMDB.list is:
  
  

  com.collation.platform.model.topology.app.AppServer

  
  
  This entry is the name of the app.AppServer class.

• BaseClassCompleteCMDB.list - 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. When filtering a child class, you should check to ensure that the filtering is applied to the upper most class by checking to see if the parent is later specified as a child. A sample line in this file is:
  
  

  com.collation.platform.model.topology.sys.unix.Unix
  com.collation.platform.model.topology.sys.aix.Aix

  
  
  This line indicates that the class sys.aix.AIX is a child of the sys.unix.Unix class. If you search the file further, you will see that sys.unix.Unix is a child of om.collation.platform.model.topology.sys.OperatingSystem.

• <baseclass>.attrlist - there will be one attrlist file for each class listed in BaseClassCMDB.list. Each attrlist file lists the attributes available for that base 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 are 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.

Base Class Filters

The base class filter is defined in the file BaseClass.filter. A default file is provided. The purpose of the file is to reduce the amount of data that is imported from TADDM. All classes listed in this file that do not begin with "//" will not be imported from TADDM. This means that the toolkit will only retrieve instances of classes that are not in this file or are in this file and begin with "//". If that makes your head hurt at first, we apologize, it is a bit of a double negative, but think about this as a filter file, and anything in it that is not a comment ("//") is filtered.

When a base class is filtered, the base class and all of its subclasses are filtered.

The BaseClass.filter provided with the product was built with the idea that providing more than may be necessary is 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, we recommend that the "//" be removed from the following lines:

SubClass Filters

The subclass filters are defined in the file BaseClassChild.filter . A default file is not provided. The purposes of this file is take the data that TBSM received from TADDM, and further reduce it before writing it to the SCR database. The format of each line of the file is:

"baseclass childclass"

As an example, if you wanted to get all operating system except AIX, then you would either remove com.collation.platform.model.topology.sys.OperatingSystem from BaseClass.filter, or have the following line in BaseClass.filter:

//com.collation.platform.model.topology.sys.OperatingSystem

You would have the following line in BaseClassChild.filter:

com.collation.platform.model.topology.sys.OperatingSystem com.collation.platform.model.topology.sys.aix.Aix

Looking in BaseClassCompleteCMDB.list, the Aix class has a base class of com.collation.platform.model.topology.sys.unix.Unix. But searching the file, you find that sys.unix.Unix is a child of com.collation.platform.model.topology.sys.OperatingSystem. This is why com.collation.platform.model.topology.sys.unix.Unix is not specified as the parent of sys.aix.AIX in BaseClassChild.filter.

The result of this is, the line in (or removed from) BaseClass.filter indicates that all instances of the OperatingSystem class will be retrieved from TADDM because it is not filtered. The line in BaseClassChild.filter will then cause all operating system objects of type sys.aix.AIX to be discarded.

Note: Specifying com.collation.platform.model.topology.sys.unix.Unix in a subclass filter would not imply that com.collation.platform.model.topology.sys.aix.Aix would be filtered. The subclass filters only apply to the specific class in the filter, they do not include any subclasses of the specified class.

Attribute Global Filters

A default AttributeGlobal.filter file is provided in $NCHOME/XMLtoolkit/config. The attributes specified in this file will be filtered from all objects requested from TADDM. The contents of this file is:

bidiFlag
bidiFormat

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

bidiFlag int
bidiFormat java.lang.String

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

Attribute Class Filters

For each class listed in the BaseClassCMDB.list file, an <baseclass>.attrlist file is generated. These files can be used to generate attribute filters at the base class level. The name of these filters is <baseclass>.filter. The name of the filter for operating systems is:

com.collation.platform.model.topology.sys.OperatingSystem.filter

The format of the file is the same as the AttributeGlobal.filter file, simply the name of each attribute, one attribute per line.

One shortfall here is that the <baseclass>.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 distinct scc.class, keyword from scc_componentattributes sa
join scc_components as scc on sa.comp_id=scc.id
group by scc.class, sa.keyword

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

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 Omnibus. 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 ships with a default set of CDM objects mapped to TBSM templates. There is also a set of event identifier that provides the mapping of events to the imported common data model objects.

To map every combination of common data model objects to templates, and associate any event from any event source to any combination of CDM discovery objects would be a daunting task, if not impossible. To extend the out of the box 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.

• 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 TBSM 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 sixteen sections. More information about the CDM can be found in the .../dist/sdk/docs/CDMWebsite.zip file.

Each section of the overview can be drilled into, yielding the classes and relationships that the section is composed of. Selecting Computer System yields the diagram:

Clearly a word document is not the optimal media to describe the CDM. But the above graphic does highlight 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 above 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 means 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 objects combined (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. 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 shipped with TBSM.

The syntax of the XML in this file is documented in the TBSM Administrators Guide. Using the 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 is to check is to see which TADDM class the object belongs, and then check the file CDM_TO_TBSM4x_MAP_Templates.xml 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 UI displays a "user friendly" version of the object type rather than the actual class name.

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".

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 shipped with TBSM are defined in the file CDM_TO_TBSM4x_MAP.xml.

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

An example of a mapping definition is:

<Mapping policy='SysplexComposite' class='cdm:sys.zOS.Sysplex'/>

This is 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:

<Policy name='SysplexComposite'>
<Rule name="hostedcollection">
<Relationship relationship='cdm:hostedCollection'
relationshipTarget='cdm:core.SystemSpecificCollection'>
<Component/>
</Relationship>
</Rule>
</Policy>

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 from the two resources are combined, and represented by a single SysplexComposite.

Several composite definitions are shipped with TBSM. The following table lists these.

The TBSM Composite column first lists the policy name that represents the composite. For composites that also create a tbsm namespace object, this is also listed in this column. The tbsm namespace objects are then mapped to a template in the CDM_TO_TBSM4x_MAP_Templates.xml file.

The CDM Class column for each composite is broken up into two sections. The first section lists the primary CDM class associated with the composite. This is the class that has the mapping definition. The second section lists the secondary CDM classes that are pulled into the composite.

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. This definition is in the file CDM_TO_TBSM4x_MAP.xml.

For example, there is a provides relationship in: cdm:sys.sun.SunSPARCUnitaryComputerSystem
cdm:provides cdm:sys.DNSService. Looking in CDM_TO_TBSM4x_MAP.xml you will see that the direction for the "provides" relationship is reversed. Without this setting, it would imply that the computer system is dependent on an application that it provides.

Another example is, 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.

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 Omnibus and associating these events with the resources that have been imported from TADDM. These events could be from an endless number of sources: ITM 6.1, TEC adapters (customer written, third-party written, IBM written), 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 Omnibus event with an imported TADDM resource, there needs to be 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 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 ITM 6.1 events with ITM 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: ITM 6.1 event and resource mapping, zOS 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 ITM 6.1 events or the cases discussed below.

ITM Resources

The EventIdentifierRules.xml file contains a policy that will build a BSM_Identity that will associate all ITM 6.1 events with their appropriate TADDM resources. 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. ITM's unique identifier for resources is the managed system name. All ITM 6.1 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 ITM 6.1. By loading the TMS DLA into TADDM with the ldfxidml.sh script, 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 ITM 6.1 managed system name.

The EventIdentifierRules.xml file contains the following policy:

<Policy name="ITM6.x">
<Rule name="ManagedSystemName">
<Token keyword="ATTR" value="cdm:ManagedSystemName"/>
</Rule>
</Policy>

It contains the following mapping:

<Mapping policy="ITM6.x" class="%" />

The mapping says that the policy "ITM6.x" 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 Omnibus event will have a field in it called BSM_Identity. For ITM 6.1 events, this field will contain the managed system name.

The result of this is that any ITM 6.1 event received by 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 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 will contain either the hostname or the IP address of the computer system. So there is a likely hood that the hostname and IP address would be 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 ITM 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>

Let's say 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 would need to be changed accordingly.

Familiarity of the CDM is helpful here in understanding the relationships between the different CDM classes. To follow this example, it would be 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. Lets say 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.

zOS BSM_Identity

There are several policies in the EventIdentifierRules.xml that are associated with the CDM classes used by the zOS DLA. We will not discuss these in detail here. The process for understanding these mappings is the same at was described in the above 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 these zOS applications, so the mapping of events in the future should be fairly straightforward.

Default BSM_Identity

Every resource imported from TADDM will have at least one BSM_Identity. The default BSM_Identity is comprised of the resource's name, TADDM GUID, and the CDM class. An example of this is:

mcormick.ibm.com(CF74C1450A33333CA2B14148A8871DCA)-AixUnitaryComputerSystem

We do not expect this value to ever match any event received by Omnibus, the odds, well lets just say you probably stand a better chance of walking on the moon than seeing the TADDM GUID in an event. The default BSM_Identity ensures that each resource has a BSM_Identity, and it allows us to easily associate the resource with TADDM's instance since it contains the GUID.

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

Defining an Event's BSM_Identity

We have just discussed how the BSM_Identity is built when a resource is imported; we now need to turn our focus to how this field is built when an event is received by Omnibus. On the event side, the 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 ITM 6.1 and then the BSM_Identity is set to the situation_origin. The situation_origin is the ITM managed system name.

The syntax of the Omnibus Probe Rule files is discussed in the 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

What 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 $NCHOME/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 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 we do not recommend changing 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, we 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.LinuxUnitaryComputerSyste
m', '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.

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, or 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 service 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 service.

The message and trace logs are written to the $NCHOME/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 completed 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.
• GTMCL5322I: The generateExplicitRelationship has finished
• GTMCL5317I: Request data from the CMDB database.
• GTMCL5318I: Begin SQL file execution: <sqlName>
• GTMCL5319I: SQL file execution complete.
• GTMCL5258I: Starting Transform: <transformName>
• GTMCL5259I: Transform complete: <transformName>

Troubleshooting

This section includes important troubleshooting information.

Known Issues

1. TADDM native discovery does not include the ITM managed system name for resources managed by ITM 6.1. The TMS DLA includes the managed system name in the information for each resource. The managed system name can be
   added to the natively discovered resources in TADDM by loading the TMS DLA book into TADDM. To load this book, the script ldfxidml.sh must be used. If loadidml.sh is used, then the resources will not be reconciled with the TADDM resources, and duplicate resources will be created. If loadidml.sh was used, the first course of action is to remove the resources created by loadidml.sh from TADDM. Reloading the book with ldfxidml.sh should cleanup the duplicate resources. If this does not work, then contact TADDM support.
   
   
2. The following exception in the msgGTM_XT.log:
   
   

   2007.10.02 01:22:20.585 GTM ASITADDMRelationshipObject process [Thread-3] XMLTOO
   LKIT cvtwin07.tivlab.raleigh.ibm.com
   GTMCL5205E: Exception caught. Relationship(): null.

   
   This exception can be ignored. This exception is caused by an invalid relationship object and the message is presented only for informational purposes; processing continues.
   
   

3. There have been cases reported where resources under an imported business service are not visible in the TBSM UI. One cause of this is a change to the template mapping. Another cause of this is that the dependency counters in the database are incorrect. We are still investigating this. A temporary fix for this is to run the two following SQL statements:
   

   UPDATE scc_serviceId_to_component_id SET cntDepends=0 WHERE
   cntDepends <> 0 ;

   
   
   

   UPDATE scc_serviceId_to_component_id SET cntDepends= cnters.cnt FROM
   ( SELECT srcradinstanceid as radinstanceid, count(srcradinstanceid) as cnt FROM
   ( SELECT DISTINCT srcradinstanceid, tgtradinstanceid, srcclass, tgtclass from
   view_dependencyRelations as vr
   WHERE vr.srcclass in (select class from scc_cdm_totemplatemap) and vr.tgtclass
   in (select class from scc_cdm_totemplatemap) ) as totals
   GROUP BY srcradinstanceid ) as cnters
   WHERE scc_serviceId_to_component_id.radinstanceid = cnters.radinstanceid AND
   scc_serviceId_to_component_id.cntDepends <> cnters.cnt ;

   
   
   The file $NCHOME/XMLtoolkit/sql/ ComponentRegistryQueries.sql contains the above statements.
   
   After running these, 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 $NCHOME/XMLtoolkit/log directory
   • The contents of the $NCHOME/XMLtoolkit/sdk/log directory
   • The filter files located in $NCHOME/XMLtoolkit/config/*.filter
   • The customized XML files located in $NCHOME/XMLtoolkit/xml:

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 $NCHOME/XMLtoolkit/log directory
• The contents of the $NCHOME/XMLtoolkit/sdk/log directory
• The filter files located in $NCHOME/XMLtoolkit/config/*.filter
• The customized XML files located in $NCHOME/XMLtoolkit/xml:
  • CDM_TO_TBSM4x_MAP.xml
  • CDM_TO_TBSM4x_MAP_Templates.xml
  • EventIdentifierRules.xml
  • LabelingRules.xml
• The two or three files in $NCHOME/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

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 to provide insight as to the type and quantity of data that has been imported from TADDM. The file $NCHOME/XMLtoolkit/sql/ ComponentRegistryQueries.sql contains these SQL statements. Each statement is preceded by a comment explaining its purpose. 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.

If pgAdmin is available, then these SQL statements can be run from the query tools dialog. See http://www.pgadmin.org for additional information on pgAdmin.

If pgAdmin is not available, then extract out the SQL statements that you want to run into a separate file. Then execute these using the psql command. The psql command is part of PostgreSQL and can be found in $NCHOME/platform/<os>/pgsql8/bin. The syntax of the command is:

psql -d rad -p 5435 -U <dbUserID> -f "<fullyQualifiedPathofSqlFile>"

Note: On UNIX, you may have to include $NCHOME/platform/<os>/pgsql8/lib in LD_LIBRARY_PATH before executing psql.

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 XML file
• The TADDM bulk load results file. This file is located in <CMDB_installdir>/dist/bulk/results. The results file will have the same filename as the originating XML file, but will have a results extension.
• The API server log. This file is: <CMDB_installdir>/dist/log/services/ApiServer.log.
• The topology manager log file. This file is: <CMDB_installdir>/dist/log/services/ToplologyManager.log.
• The bulk loader log file. This file is: <CMDB_installdir>//dist/log/bulkload.log. In the <CMDB_installdir>/dist/etc directory, the file bulkload.readme contains information on the bulk loader.

Please read the copyright and notices statement for this information.