Nimsoft Documentation

Size: px

Start display at page:

Download "Nimsoft Documentation"

Gary Armstrong
6 years ago
Views:

1 Nimsoft Documentation Nimsoft Probes Technical Description cmdbgtw 1.00 Probe Documentation Last Update: 30 September 2010 Copyright , Nimsoft Corporation Nimsoft Documentation: cmdbgtw v1.00 1

2 Contents cmdbgtw... 3 Prerequisites... 3 Probe Installation... 3 Configuration GUI Installation... 4 Understanding and Configuring Probe Operation... 5 Creating and Configuring Database Connection Objects... 5 Database Connection Setup Information... 6 Creating and Configuring Exports... 7 Configuring Export Options... 8 Configuring Export Data Mapping... 9 Mapping Notes Testing and Running Exports Test Run Tree Context (right-click) Menu Configuring Logging Appendix A: Using an alternate JDBC driver Appendix B: Advanced Data Mapping Customization Specifying Entity Filters Specifying Property Formulas Changing the Base Mapping Custom Example 1: Custom table Implementing Custom Property Types Appendix C: Nimsoft Callback Interface Nimsoft Documentation: cmdbgtw v1.00 2

3 cmdbgtw This description applies to cmdbgtw version 1.00 The cmdbgtw probe provides fast and convenient access to data residing in a Nimsoft SLM database. The cmdbgtw probe is capable of exporting data from any table or set of tables. Data can be exported in either XML or CSV interchange formats. Exported data is written to files in a user-chosen location. Prerequisites The cmdbgtw probe requires Java or later. The cmdbgtw probe configuration GUI requires Java or later. Probe Installation The cmdbgtw probe installs via drag-and-drop from the Nimsoft Infrastructure Manager. The probe is run by the robot via the standard runprobe.bat on Windows and runprobe.sh on UNIX. Java 1.6.0_14 or later can be installed either using the standard Java installer available from Sun ( or by dragging the jre/java_jre package from your Nimsoft package archive onto your robot. Please see the java_jre documentation from Nimsoft for details. If you install using Sun's installer, please ensure that java.exe is available on your path environment variable. The probe is launched by the Nimsoft robot and thus inherits its process environment. To examine your robot's environment, launch the Infrastructure Manager, right-click on your robot and choose Properties. Then, click the Robot environment button and you will see: Nimsoft Documentation: cmdbgtw v1.00 3

4 If you need to manually modify your robot's environment you must restart your computer to make the changes visible to your robot. Configuration GUI Installation The cmdbgtw probe configuration GUI is automatically downloaded and installed by the Nimsoft Infrastructure Manager when probe configuration is attempted. The configuration GUI has the same Java requirements as the probe and supports the same Java installation methods on the computer running the Infrastructure Manager. Note: If you choose the java_jre installation method, the configuration GUI may fail to startup if more than one java_jre package is installed and one or more of the java_jre packages is for a version of Java that is earlier than 1.6.0_14. In this situation you must remove obsolete java_jre packages before attempting to launch the configuration GUI. Nimsoft Documentation: cmdbgtw v1.00 4

5 Understanding and Configuring Probe Operation There are two primary aspects to configuring the DB Gatway probe. One must first define one of more Database Connection objects for the databases one wishes to export data from. Once databases are defined, one or more Export objects can be created. Each export defines the type of data to export, the database to export from, data filters and transformations and the output format. The following sections will detail the configuration process. Creating and Configuring Database Connection Objects The first step to configure the cmdbgtw probe is to create one or more database connection objects using the configuration user interface. You may either edit the provided My Database connection or create a new connection by right-clicking on any node in the tree and choosing New Database Connection: The new connection appears in the tree. Select the node with the database name and you will see the database configuration information on the right: Nimsoft Documentation: cmdbgtw v1.00 5

Database Connection Setup Information Please enter the following information to configure your database connection: Field Name User Password Driver Class SQL Dialect Connection URL Description Enter

6 Database Connection Setup Information Please enter the following information to configure your database connection: Field Name User Password Driver Class SQL Dialect Connection URL Description Enter a name for the connection. Database login user name Database password. The Java JDBC driver class to use. Select a class from the supported drop-down list. Note: The probe ships with JDBC drivers for Oracle, MySQL and Microsoft SQL Server. It is possible to run the probe using a driver that is not shipped with the probe. Please see the appendixes for advanced configuration. Select a dialect that matches the vendor/version of your database. Once you choose a dialect, the URL Format field will be populated with a sample JDBC connection URL. Enter the JDBC connection URL. You may test the information you have entered by clicking the Test Connection button. The probe must be running for this feature to work. You will be notified if your connection information is valid. The Use For All Exports button associates the current database connection will all defined exports. This is handy for when your database moves. Nimsoft Documentation: cmdbgtw v1.00 6

7 Creating and Configuring Exports An export is specification for exporting data from a database. It includes the type of data to export, the database to export from and the output directory and format for the exported data. To create an export, right-click on the tree and choose New Export... You will see the following dialog: Enter/choose values for: Field Export Name Root Entity Description Enter a unique descriptive Export Name. Select the type of data to export. Note: The dbcmdbgtw probe ships with support for some of the Nimsoft SLM database schema. It is possible to add support for missing entity types. Please see the appendixes for advanced configuration options. Database Select a database connection. Nimsoft Documentation: cmdbgtw v1.00 7

Configuring Export Options Highlight the new export in the tree and you will see the full export configuration on the right: The Setup section contains the following configuration options: Field Name

8 Configuring Export Options Highlight the new export in the tree and you will see the full export configuration on the right: The Setup section contains the following configuration options: Field Name Root Entity Output Directory Database XSLT Transform Output Format Description Enter a descriptive name. The data type to export. Note that you cannot change the root entity of an existing export. Please create a new export if you wish to use a new root entity. Enter a path, absolute or relative to the probe's installation directory, that specifies where the probe should deposit exported data when an export is run. More on filenames later. Select the database connection to use The path, absolute or relative to the probe's installation directory, that specifies an XSLT transform to run on the exported data. This is an optional feature that works only when the output format is set to XML. Note that the transform is applied after all root entries have been extracted from the database and thus the XML includes the root entity parent element <items> Select XML or CSV (Comma Separated Values). Note that with CSV, only root entities are included in the output as CSV is not capable of structured output of relationships. Nimsoft Documentation: cmdbgtw v1.00 8

9 Configuring Export Data Mapping Below in the Setup section you will find the Mapping section. This section allows you to fine tune the data to export. The entity tree is on the left. It is rooted at your chosen root entity type. It then shows all of the related entity types as sub-nodes in the tree. When you select an entity in the tree you will see the right hand side populate with information/options for that entity type: Field Include Type XML Parent Description If you are not interested in related entities, use this checkbox to turn off export inclusion. You must include the root entity by definition. Note that the tree displays excluded entity types with a red dot icon and grayed-out text. The read-only XML element of the parent node of this entity type. For example, for the CmDevice type the parent will be devices resulting in XML like: <devices> <device>...</device> <device>...</device... </devices> Note that the root entity type always has a parent XML element named <items> XML Name Filter The read-only XML element name for entities of this type. A query where clause expressed in the Hibernate Query Language. Please see the Appendixes for advanced configuration options. Nimsoft Documentation: cmdbgtw v1.00 9

10 Field Properties Description A table showing the properties (aka database columns) that comprise the entity type: Name Enter the property name Column XML Name Enter the database column name. Enter the name of the XML element that will hold this property value. If name starts with the '@' character, the property will be emitted as an XML attribute of the entity s XML Name. Example: CmComputerSystem has property named csid with XML Name of '@id' It also has a property named cstype with XML Name of 'cstype'. The resulting XML is: <computer id="[the id]"> <cstype>[the type]</cstype>... </computer> Formula A valid Hibernate column formula expression. Formulas are used to transform data at export time. Please see the Appendixes for advanced configuration options. To edit the formula, double-click the property row. Mapping Notes All datetime columns in the shipped.hbm.xml files are mapped using a custom type called com.nimsoft.db.mytimestamptype. This causes all dates to be emitted in W3C date/time format as detailed in Please see the appendices for information on implementing your own custom data types. Testing and Running Exports Select an export in the tree and you will see both a Test and a Run button on the right hand display. Test and Run are similar operations in that they both take the current export configuration, submit it to the probe and have the probe perform the export. The difference is in the output. Nimsoft Documentation: cmdbgtw v

11 Test In test mode, the probe will perform the export but will only return the first entity from the database. The configuration GUI displays the test result in the bottom half of the right hand side: Run In run mode, the probe also performs the export but instead of returning the partial results the GUI, it writes the complete export results to a file in the export's configured Output Directory. The file name will be generated according to the following pattern: [export name]_[export date].xml The export date will be expressed in W3C date/time format as detailed in Nimsoft Documentation: cmdbgtw v

12 Tree Context (right-click) Menu A context sensitive popup-menu is available by right-clicking on a tree node: Field New Export Delete Export New Database Connection Delete Database Connection Description Create a new export for monitoring. Delete the selected export. Create a new database connection Delete the selected database connection Configuring Logging The cmdbgtw probe can be configured to log messages during its operation. To configure logging, click the Options button on the top toolbar to display the Probe Options dialog: Log Level Nimsoft recommends that when you first use the probe or are actively troubleshooting a problem that you set the log level to Debug. Once you are confident the probe is functioning properly, change the logging to Normal Operations to save disk space. The Errors/Warnings Only level is intended for rare situations when disk space is at a premium. Max Log Size(MB) The maximum size of a single log file in megabytes. Max Logfiles When a log file reaches the Max Log Size, the probe rolls the old log into a saved file, empties the primary log file, and continues logging. Max Logfiles defines how many saved files are preserved. Nimsoft Documentation: cmdbgtw v

13 Appendix A: Using an alternate JDBC driver If you would like to use a JDBC driver that is not shipped with the cmdbgtw probe, please following these steps. 1. Deactivate the probe using the Infrastructure Manager. 2. Edit the cmdbgtw's runprobe.bat (or runprobe.sh file on LINUX). Add your jdbc driver jar(s) to the CLASSPATH environment variable. 3. Activate the probe. 4. In the probe configuration GUI, type the fully qualified class name of your driver class in an database connection's Driver Class.Use property. Appendix B: Advanced Data Mapping Customization The cmdbgtw probe uses the Hibernate (see open source relational data mapping framework to do much of the heavy lifting. This section assumes a familiarity with Hibernate. The probe installation directory contains a subdirectory named mappings. In mappings you will find a subdirectory called base. Base contains hibernate mapping files for all entity types that the cmdbgtw probe knows about. Note that version 1.00 includes a small subset of the entire Nimsoft SLM database schema. An export is simply the base mapping plus any user configured customizations. Customizations that one can perform using the configuration GUI include excluding related entity types, filtering collections of entities and specifying transform formulas for individual columns. At export run-time, the probe takes the base.hbm.xml files and the customizations and generates export-specific.hbm.xml files in mappings/[mapping-name]. Export-specific.hbm.xml files are only generated when they are out of date relative to the customization time. mappings/[mapping-name]/custom.xml contains the current set of customization along with a version number. If that version number is out of sync with the contents of mappings/[mapping-name]/.version, the.hbm.xml files need to be re-generated. Specifying Entity Filters An entity filter is created by selecting an entity in the mapping tree and typing a Hibernate query language where clause expression in the filter box. Note that you must use database column names in your expression. For example, if your root entity type is CmComputerSystems but you only want to export computer systems on a specific subnet, you would enter a filter like: ip like ' %' The Hibernate reference documentation contains a complete specification of the Hibernate query language. Nimsoft Documentation: cmdbgtw v

14 Specifying Property Formulas Property formulas are applied to individual column values at export time in order to transform the data in the database to a more palatable form. For example, the CmComputerSystem.csType property encodes the type of computer system with a single letter. If you would like to transform that single letter into something human-readable you would use a formula like: case when cs_type = 'A' then 'AType' when cs_type = 'B' then 'BType' else cs_type end Changing the Base Mapping There are customization scenarios that are not currently supported by the probe configuration GUI. Changing the base mapping is accomplished by modifying the.hbm.xml files in mappings/base or by adding new.hbm.xml files to that directory. You must re-start the probe and the configuration GUI after making changes to the base mapping. Here is a custom mapping example: Custom Example 1: Custom table You have a custom table added to your Nimsoft SLM database schema called COMPUTER_ANOMALY that has a foreign key relationship with the CM_COMPUTER_SYSTEM table and would like to export this custom data. Solution: Create a hibernate.hbm.xml file for your custom table and modify the CmComputerSystem.hbm.xml file to have a relationship to this table. MyComputerExtra.hbm.xml: <?xml version="1.0"?> <!DOCTYPE hibernate-mapping PUBLIC "- //Hibernate/Hibernate Mapping DTD 3.0//EN" "  <hibernate-mapping>  <class entity-name="computeranomaly" node="anomaly" table="computeranomaly"> <id name="id" type="int"> </id> <column name="id" /> Nimsoft Documentation: cmdbgtw v

15 <property name="date" type="com.nimsoft.db.mytimestamptype"> /> </class> <column name="date" length="23" /> </property> <property name="description" type="string"> <column name="description" length="128" </property> </hibernate-mapping> Modifications to CmComputerSystem.hbm.xml: Add relationships: <set name="anomalies" node="anomalies" table="computeranomalies" inverse="true" lazy="true" fetch="select"> </set> <key> </key> <column name="computer_id" /> <one-to-many class="computeranomaly" /> Your exported xml will then have the form: <computers> <computer>... <anomalies> <anomaly id="theid"> <date>thedate</date> <description>thedescription</description> </anomaly> <anomalies> </computer> </computers> Nimsoft Documentation: cmdbgtw v

16 Implementing Custom Property Types Hibernate <property> attributes have a type that determines how hibernate maps the database data to xml data. It is possible to implement your own custom types to affect how data is output. The cmdbgtw probes uses this facility to ensure that all dates are output in W3C date/time format. For example, the create_time column in CmComputerSystem is mapped: <property name="createtime" type="com.nimsoft.db.mytimestamptype"> <column name="create_time" length="23" notnull="true" /> </property> MyTimestampType is a custom class that implements org.hibernate.usertype.usertype. It tells Hibernate to, instead of mapping datetime columns to java.sql.timestamp objects to map them to com.nimsoft.db.mytimestamp objects. MyTimestamp then overrides tostring() to return a properly formatted date/time. Example code is available upon request. Custom Mapping Notes Always use the entity-name property on a <class> and not a classname You may map a table more than once as long as you use a unique entity-name For example, you may have an entity-name=computer mapping that includes all properties and one with entityname=computerchanges that just includes the id and change_time. Nimsoft Documentation: cmdbgtw v

17 Appendix C: Nimsoft Callback Interface The cmdbgtw probe includes a custom callback called runexport. Other Nimbus participants can send this message to the cmdbgtw probe to cause it to run the named export. Callback Name: runexport Parameters: Name exportname entitycountlimit Value The text name of the export you assigned when creating the export in the GUI 0 = unlimited, any other positive integer to limit the number of entities returned. Result: Name msg outfile nentitiesgenerated Value on success, will display "ok"; on failure, will display the error message text The path to the exported data file The number of root entities generated. -DOCUMENT END- Nimsoft Documentation: cmdbgtw v

Nimsoft Unified Monitoring Portal

Nimsoft Unified Monitoring Portal Service Desk Integration Guide 2.1.1 Legal Notices Copyright 2011, Nimsoft Corporation Warranty The material contained in this document is provided "as is," and is subject