Nimsoft Monitor. cmdbgtw Guide. v1.0 series

Transcription

1 Nimsoft Monitor cmdbgtw Guide v1.0 series

2 Legal Notices Copyright 2011, CA. All rights reserved. Warranty The material contained in this document is provided "as is," and is subject to being changed, without notice, in future editions. Further, to the maximum extent permitted by applicable law, Nimsoft LLC disclaims all warranties, either express or implied, with regard to this manual and any information contained herein, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Nimsoft LLC shall not be liable for errors or for incidental or consequential damages in connection with the furnishing, use, or performance of this document or of any information contained herein. Should Nimsoft LLC and the user have a separate written agreement with warranty terms covering the material in this document that conflict with these terms, the warranty terms in the separate agreement shall control. Technology Licenses The hardware and/or software described in this document are furnished under a license and may be used or copied only in accordance with the terms of such license. No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from Nimsoft LLC as governed by United States and international copyright laws. Restricted Rights Legend If software is for use in the performance of a U.S. Government prime contract or subcontract, Software is delivered and licensed as "Commercial computer software" as defined in DFAR (June 1995), or as a "commercial item" as defined in FAR 2.101(a) or as "Restricted computer software" as defined in FAR (June 1987) or any equivalent agency regulation or contract clause. Use, duplication or disclosure of Software is subject to Nimsoft LLC s standard commercial license terms, and non-dod Departments and Agencies of the U.S. Government will receive no greater than Restricted Rights as defined in FAR (c)(1-2) (June 1987). U.S. Government users will receive no greater than Limited Rights as defined in FAR (June 1987) or DFAR (b)(2) (November 1995), as applicable in any technical data. Trademarks Nimsoft is a trademark of CA. Adobe, Acrobat, Acrobat Reader, and Acrobat Exchange are registered trademarks of Adobe Systems Incorporated. Intel and Pentium are U.S. registered trademarks of Intel Corporation. Java(TM) is a U.S. trademark of Sun Microsystems, Inc. Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation. Netscape(TM) is a U.S. trademark of Netscape Communications Corporation. Oracle is a U.S. registered trademark of Oracle Corporation, Redwood City, California. UNIX is a registered trademark of the Open Group. ITIL is a Registered Trade Mark of the Office of Government Commerce in the United Kingdom and other countries. All other trademarks, trade names, service marks and logos referenced herein belong to their respective companies. For information on licensed and public domain software, see the Nimsoft Monitor Third-Party Licenses and Terms of Use document at:

3 Contact CA Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At you can access the following resources: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentation Send comments or questions about CA Technologies Nimsoft product documentation to To provide feedback about general CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at

4

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

6

7 Chapter 1: cmdbgtw 1.0 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. This section contains the following topics: Documentation Changes (see page 8) Prerequisites (see page 8) Chapter 1: cmdbgtw 1.0 7

8 Prerequisites Documentation Changes This table describes the version history for this document. Version Date What's New? 1.0 May 2011 Added ability to periodically schedule individual exports. Added a new output file parameter to exports. Added user-definable properties to exports that get passed to finished programs. Related Documentation Documentation for other versions of the cmdbgtw probe The Release Notes for the cmdbgtw probe Monitor Metrics Reference Information for CA Nimsoft Probes ( Prerequisites The cmdbgtw probe requires Java or later. Note: If there are multiple instances of Java on the host, the JAVA_HOME environment variable must be set to a Java version that meets the above criterion. 8 cmdbgtw Guide

9 Chapter 2: Probe Installation Chapter 2: Probe Installation 9

10 Prerequisites 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: If you need to manually modify your robot's environment you must restart your computer to make the changes visible to your robot. More Information Configuration GUI Installation Understanding and Configuring Probe Operation Creating and Configuring Database Connection Objects 10 cmdbgtw Guide

11 Configuration GUI Installation Database Connection Setup Information Creating and Configuring Exports Configuring Export Options Configuring Export Data Mapping Mapping Notes This section contains the following topics: Configuration GUI Installation (see page 11) Understanding and Configuring Probe Operation (see page 11) Creating and Configuring Database Connection Objects (see page 12) Database Connection Setup Information (see page 12) Creating and Configuring Exports (see page 13) Configuring Export Options (see page 14) Configuring Export Data Mapping (see page 15) Mapping Notes (see page 17) 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. Understanding and Configuring Probe Operation There are two primary aspects to configuring the DB Gateway 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. Chapter 2: Probe Installation 11

12 Creating and Configuring Database Connection Objects 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. Database Connection Setup Information Please enter the following information to configure your database connection: Field Name Description Enter a name for the connection. 12 cmdbgtw Guide

13 Creating and Configuring Exports User Password Driver Class SQL Dialect Connection URL 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. 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 Description Export Name Enter a unique descriptive Export Name. Chapter 2: Probe Installation 13

14 Configuring Export Options Root Entity Database 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. Select a database connection. Configuring Export Options 14 cmdbgtw Guide

15 Configuring Export Data Mapping 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. 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 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. Chapter 2: Probe Installation 15

16 Configuring Export Data Mapping Field XML Parent XML Name Filter Description 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: The root entity type always has a parent XML element named <items> 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. 16 cmdbgtw Guide

17 Mapping Notes Field Properties Description A table showing the properties (aka database columns) that comprise the entity type: Name Column XML Name Formula Enter the property 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> 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. Chapter 2: Probe Installation 17

18

19 Chapter 3: 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. This section contains the following topics: Test (see page 19) Run (see page 20) 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: Chapter 3: Testing and Running Exports 19

20 Run 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 cmdbgtw Guide

21 Chapter 4: Tree Context (right-click) Menu A context sensitive popup-menu is available by right-clicking on a tree node: Field New Export Delete Export Description Create a new export for monitoring. Delete the selected export. New Database Connection Create a new database connection Delete Database Connection Delete the selected database connection Chapter 4: Tree Context (right-click) Menu 21

22

23 Chapter 5: 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. Chapter 5: Configuring Logging 23

24

25 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. Deactivate the probe using the Infrastructure Manager. Edit the cmdbgtw's runprobe.bat (or runprobe.sh file on LINUX). Add your jdbc driver jar(s) to the CLASSPATH environment variable. Activate the probe. 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 A: Using an alternate JDBC driver 25

26

27 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. This section contains the following topics: Specifying Entity Filters (see page 28) Specifying Property Formulas (see page 28) Changing the Base Mapping (see page 29) Implementing Custom Property Types (see page 32) Appendix B: Advanced Data Mapping Customization 27

28 Specifying Entity Filters 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. 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 28 cmdbgtw Guide

29 Changing the Base Mapping 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. See the custom mapping example: Appendix B: Advanced Data Mapping Customization 29

30 Changing the Base Mapping 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" " <!-- Generated Aug 26, :58:25 AM by Hibernate Tools GA --> <hibernate-mapping> <!-- note how we use entity-name and not class-name --> <class entity-name="computeranomaly" node="anomaly" table="computeranomaly"> <id name="id" type="int"> <column name="id" /> </id> <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: 30 cmdbgtw Guide

31 Changing the Base Mapping <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> Appendix B: Advanced Data Mapping Customization 31

32 Implementing Custom Property Types 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" not-null="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 1. Always use the entity-name property on a <class> and not a class-name 2. 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 entity-name=computerchanges that just includes the id and change_time. 32 cmdbgtw Guide

33 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 Result: Name msg outfile nentitiesgenerated 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. 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. Appendix C: Nimsoft Callback Interface 33