Transcription
Nimsoft DocumentationNimsoft Probes – Technical Descriptioncmdbgtw 1.00 Probe DocumentationLast Update: 30 September 2010Copyright 1998-2010, Nimsoft Corporationwww.nimsoft.comNimsoft Documentation: cmdbgtw v1.001
Contentscmdbgtw . 3Prerequisites . 3Probe Installation . 3Configuration GUI Installation . 4Understanding and Configuring Probe Operation . 5Creating and Configuring Database Connection Objects . 5Database Connection Setup Information . 6Creating and Configuring Exports . 7Configuring Export Options . 8Configuring Export Data Mapping . 9Mapping Notes . 10Testing and Running Exports . 10Test . 11Run . 11Tree Context (right-click) Menu . 12Configuring Logging . 12Appendix A: Using an alternate JDBC driver . 13Appendix B: Advanced Data Mapping Customization . 13Specifying Entity Filters . 13Specifying Property Formulas . 14Changing the Base Mapping . 14Custom Example 1: Custom table . 14Implementing Custom Property Types . 16Appendix C: Nimsoft Callback Interface . 17Nimsoft Documentation: cmdbgtw v1.002
cmdbgtwThis description applies to cmdbgtw version 1.00The cmdbgtw probe provides fast and convenient access to data residing in aNimsoft SLM database. The cmdbgtw probe is capable of exporting datafrom any table or set of tables. Data can be exported in either XML or CSVinterchange formats. Exported data is written to files in a user-chosenlocation.PrerequisitesThe cmdbgtw probe requires Java 1.6.0.14 or later.The cmdbgtw probe configuration GUI requires Java 1.6.0.14 or later.Probe InstallationThe cmdbgtw probe installs via drag-and-drop from the NimsoftInfrastructure Manager. The probe is run by the robot via the standardrunprobe.bat on Windows and runprobe.sh on UNIX.Java 1.6.0 14 or later can be installed either using the standard Java installeravailable from Sun (http://www.java.com/en/download/manual.jsp) or bydragging the jre/java jre package from your Nimsoft package archive ontoyour 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 onyour path environment variable. The probe is launched by the Nimsoft robotand 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 Robotenvironment button and you will see:Nimsoft Documentation: cmdbgtw v1.003
If you need to manually modify your robot's environment you must restartyour computer to make the changes visible to your robot.Configuration GUI InstallationThe cmdbgtw probe configuration GUI is automatically downloaded andinstalled by the Nimsoft Infrastructure Manager when probe configuration isattempted.The configuration GUI has the same Java requirements as the probe andsupports the same Java installation methods on the computer running theInfrastructure Manager.Note: If you choose the java jre installation method, the configuration GUImay fail to startup if more than one java jre package is installed and one ormore of the java jre packages is for a version of Java that is earlier than1.6.0 14. In this situation you must remove obsolete java jre packagesbefore attempting to launch the configuration GUI.Nimsoft Documentation: cmdbgtw v1.004
Understanding and Configuring ProbeOperationThere are two primary aspects to configuring the DB Gatway probe. Onemust first define one of more Database Connection objects for the databasesone wishes to export data from. Once databases are defined, one or moreExport objects can be created. Each export defines the type of data toexport, the database to export from, data filters and transformations and theoutput format. The following sections will detail the configuration process.Creating and Configuring DatabaseConnection ObjectsThe first step to configure the cmdbgtw probe is to create one or moredatabase connection objects using the configuration user interface.You may either edit the provided My Database connection or create a newconnection by right-clicking on any node in the tree and choosing NewDatabase Connection: The new connection appears in the tree.Select the node with the database name and you will see the databaseconfiguration information on the right:Nimsoft Documentation: cmdbgtw v1.005
Database Connection Setup InformationPlease enter the following information to configure your databaseconnection:FieldDescriptionNameEnter a name for the connection.UserDatabase login user namePasswordDatabase password.Driver ClassThe Java JDBC driver class to use. Select a class from thesupported drop-down list. Note: The probe ships withJDBC drivers for Oracle, MySQL and Microsoft SQL Server.It is possible to run the probe using a driver that is notshipped with the probe. Please see the appendixes foradvanced configuration.SQL DialectSelect a dialect that matches the vendor/version of yourdatabase. Once you choose a dialect, the URL Format fieldwill be populated with a sample JDBC connection URL.Connection URLEnter the JDBC connection URL.You may test the information you have entered by clicking the TestConnection 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 connectionwill all defined exports. This is handy for when your database moves.Nimsoft Documentation: cmdbgtw v1.006
Creating and Configuring ExportsAn export is specification for exporting data from a database. It includes thetype of data to export, the database to export from and the output directoryand format for the exported data.To create an export, right-click on the tree and choose New Export. Youwill see the following dialog:Enter/choose values for:FieldDescriptionExport NameEnter a unique descriptive Export Name.Root EntitySelect the type of data to export.Note: The dbcmdbgtw probe ships with support forsome of the Nimsoft SLM database schema. It ispossible to add support for missing entity types. Pleasesee the appendixes for advanced configuration options.DatabaseNimsoft Documentation: cmdbgtw v1.00Select a database connection.7
Configuring Export OptionsHighlight the new export in the tree and you will see the full export configuration onthe right:The Setup section contains the following configuration options:FieldDescriptionNameEnter a descriptive name.Root EntityThe data type to export. Note that you cannot change the rootentity of an existing export. Please create a new export if youwish to use a new root entity.Output DirectoryEnter a path, absolute or relative to the probe's installationdirectory, that specifies where the probe should depositexported data when an export is run. More on filenames later.DatabaseSelect the database connection to useXSLT TransformThe path, absolute or relative to the probe's installationdirectory, that specifies an XSLT transform to run on theexported data. This is an optional feature that works only whenthe output format is set to XML. Note that the transform isapplied after all root entries have been extracted from thedatabase and thus the XML includes the root entity parentelement items Output FormatSelect XML or CSV (Comma Separated Values). Note thatwith CSV, only root entities are included in the output as CSV isnot capable of structured output of relationships.Nimsoft Documentation: cmdbgtw v1.008
Configuring Export Data MappingBelow in the Setup section you will find the Mapping section. This sectionallows you to fine tune the data to export.The entity tree is on the left. It is rooted at your chosen root entity type. Itthen shows all of the related entity types as sub-nodes in the tree. When youselect an entity in the tree you will see the right hand side populate withinformation/options for that entity type:FieldDescriptionInclude TypeIf you are not interested in related entities, use thischeckbox to turn off export inclusion. You must includethe root entity by definition. Note that the tree displaysexcluded entity types with a red dot icon and grayed-outtext.XML ParentThe read-only XML element of the parent node of thisentity type.For example, for the CmDevice type the parent will bedevices resulting in XML like: devices device . /device device . /device. /devices Note that the root entity type always has a parent XMLelement named items XML NameThe read-only XML element name for entities of this type.FilterA query where clause expressed in the Hibernate QueryLanguage. Please see the Appendixes for advancedconfiguration options.Nimsoft Documentation: cmdbgtw v1.009
FieldPropertiesDescriptionA table showing the properties (aka database columns)that comprise the entity type:NameEnter the property nameColumnEnter the database columnname.XML NameEnter the name of the XMLelement that will hold thisproperty value. If name startswith the '@' character, theproperty will be emitted as anXML attribute of the entity’sXML Name. Example:CmComputerSystem hasproperty named csId with XMLName of '@id' It also has aproperty named csType withXML Name of 'csType'.The resulting XML is: computer id "[the id]" csType [thetype] /csType . /computer FormulaA valid Hibernate columnformula expression. Formulasare used to transform data atexport time. Please see theAppendixes for advancedconfiguration options. To editthe formula, double-click theproperty row.Mapping NotesAll datetime columns in the shipped .hbm.xml files are mapped using acustom type called com.nimsoft.db.MyTimestampType. This causes all datesto be emitted in W3C date/time format as detailed inhttp://www.w3.org/TR/NOTE-datetime. Please see the appendices forinformation on implementing your own custom data types.Testing and Running ExportsSelect an export in the tree and you will see both a Test and a Run button onthe right hand display. Test and Run are similar operations in that they bothtake the current export configuration, submit it to the probe and have theprobe perform the export. The difference is in the output.Nimsoft Documentation: cmdbgtw v1.0010
TestIn test mode, the probe will perform the export but will only return the firstentity from the database. The configuration GUI displays the test result inthe bottom half of the right hand side:RunIn run mode, the probe also performs the export but instead of returning thepartial results the GUI, it writes the complete export results to a file in theexport's configured Output Directory.The file name will be generated according to the following pattern:[export name] [export date].xmlThe export date will be expressed in W3C date/time format as detailed inhttp://www.w3.org/TR/NOTE-datetimeNimsoft Documentation: cmdbgtw v1.0011
Tree Context (right-click) MenuA context sensitive popup-menu is available by right-clicking on a tree node:FieldDescriptionNew ExportCreate a new export for monitoring.Delete ExportDelete the selected export.New DatabaseConnectionCreate a new database connectionDelete DatabaseConnectionDelete the selected database connectionConfiguring LoggingThe cmdbgtw probe can be configured to log messages during its operation.To configure logging, click the Options button on the top toolbar to displaythe Probe Options dialog:Log LevelNimsoft recommends that when you first use the probe or are activelytroubleshooting a problem that you set the log level to Debug. Once you areconfident the probe is functioning properly, change the logging to NormalOperations to save disk space. The Errors/Warnings Only level is intendedfor rare situations when disk space is at a premium.Max Log Size(MB)The maximum size of a single log file in megabytes.Max LogfilesWhen a log file reaches the Max Log Size, the probe rolls the old log into asaved file, empties the primary log file, and continues logging. MaxLogfiles defines how many saved files are preserved.Nimsoft Documentation: cmdbgtw v1.0012
Appendix A: Using an alternate JDBC driverIf you would like to use a JDBC driver that is not shipped with the cmdbgtwprobe, please following these steps.1.Deactivate the probe using the Infrastructure Manager.2.Edit the cmdbgtw's runprobe.bat (or runprobe.sh file onLINUX). Add your jdbc driver jar(s) to the CLASSPATHenvironment variable.3.Activate the probe.4.In the probe configuration GUI, type the fully qualified classname of your driver class in an database connection's DriverClass.Use property.Appendix B: Advanced Data Mapping CustomizationThe cmdbgtw probe uses the Hibernate (see http://www.hibernate.org/) opensource 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 containshibernate mapping files for all entity types that the cmdbgtw probe knowsabout.Note that version 1.00 includes a small subset of the entire Nimsoft SLMdatabase schema.An export is simply the base mapping plus any user configuredcustomizations. Customizations that one can perform using theconfiguration GUI include excluding related entity types, filteringcollections of entities and specifying transform formulas for individualcolumns. At export run-time, the probe takes the base .hbm.xml files and thecustomizations and generates export-specific .hbm.xml files inmappings/[mapping-name]. Export-specific .hbm.xml files are onlygenerated when they are out of date relative to the customization time.mappings/[mapping-name]/custom.xml contains the current set ofcustomization along with a version number. If that version number is out ofsync with the contents of mappings/[mapping-name]/.version, the.hbm.xml files need to be re-generated.Specifying Entity FiltersAn entity filter is created by selecting an entity in the mapping tree andtyping a Hibernate query language where clause expression in the filter box.Note that you must use database column names in your expression. Forexample, if your root entity type is CmComputerSystems but you only wantto export computer systems on a specific subnet, you would enter a filterlike:ip like '10.0.1.%'The Hibernate reference documentation contains a complete specification ofthe Hibernate query language.Nimsoft Documentation: cmdbgtw v1.0013
Specifying Property FormulasProperty formulas are applied to individual column values at export time inorder to transform the data in the database to a more palatable form.For example, the CmComputerSystem.csType property encodes the type ofcomputer system with a single letter. If you would like to transform thatsingle letter into something human-readable you would use a formula like:casewhen cs type 'A' then 'AType'when cs type 'B' then 'BType'else cs typeendChanging the Base MappingThere are customization scenarios that are not currently supported by theprobe configuration GUI. Changing the base mapping is accomplished bymodifying the .hbm.xml files in mappings/base or by adding new .hbm.xmlfiles to that directory.You must re-start the probe and the configuration GUI after makingchanges to the base mapping. Here is a custom mapping example:Custom Example 1: Custom tableYou have a custom table added to your Nimsoft SLM database schemacalled COMPUTER ANOMALY that has a foreign key relationship withthe CM COMPUTER SYSTEM table and would like to export this customdata.Solution: Create a hibernate .hbm.xml file for your custom table and modifythe 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 emapping-3.0.dtd" !-- Generated Aug 26, 2010 10:58:25 AM byHibernate Tools 3.3.0.GA -- hibernate-mapping !-- note how we use entity-name and not classname -- class entity-name "ComputerAnomaly"node "anomaly" table "ComputerAnomaly" id name "id" type "int" column name "id" / /id Nimsoft Documentation: cmdbgtw v1.0014
property name "date"type "com.nimsoft.db.MyTimestampType" column name "date" length "23" / /property property name "description" type "string" column name "description" length "128"/ /property /class /hibernate-mapping Modifications to CmComputerSystem.hbm.xml:Add relationships: set name "anomalies" node "anomalies"table "ComputerAnomalies" inverse "true"lazy "true" fetch "select" key column name "computer id" / /key one-to-many class "ComputerAnomaly" / /set 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 v1.0015
Implementing Custom Property TypesHibernate property attributes have a type that determines how hibernatemaps the database data to xml data. It is possible to implement your owncustom types to affect how data is output.The cmdbgtw probes uses this facility to ensure that all dates are output inW3C date/time format. For example, the create time column inCmComputerSystem is mapped: property name "createTime"type "com.nimsoft.db.MyTimestampType" column name "create time" length "23" notnull "true" / /property MyTimest
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 package
