Integrate with the CA Cloud Service Management CMDB

The CA UIM CMDB Gateway probe and CA Cloud Service Management Adapter automatically discover and record the attributes and relationships of devices monitored by CA UIM into the CA Cloud Service Management CMDB. This allows CA Cloud Service Management tickets to provide additional information about relationships and processes, including incidents, problems, known errors, changes, and releases, and to apply automatic workflow rules.
uim902-9-0-2
The CA UIM CMDB Gateway probe and CA Cloud Service Management Adapter automatically discover and record the attributes and relationships of devices monitored by CA UIM into the CA Cloud Service Management CMDB. This allows CA Cloud Service Management tickets to provide additional information about relationships and processes, including incidents, problems, known errors, changes, and releases, and to apply automatic workflow rules.
The information in the CA Cloud Service Management CMDB is synchronized with CA UIM data; when information about a device is updated in CA UIM or a new monitored device is discovered, the CA Cloud Service Management CMDB is automatically updated
 
Contents
 
 
 
Install and Configure the CMDB Gateway and Service Desk Adapter
The CA Cloud Service Management synchronization adapter is a UIM installable package that consists of a command line application and an XSL transform.
It has the following requirements:
  •  
    Platform
    The 
    nsdsync
     package can be installed on any platform the supports Java.
  •  
    Software
    java_jre version 1.6.0 or above
    UIM CMDB Gateway Probe (cmdbgtw) version 1.03 or above
 
Follow these steps:
 
  1. Download the 
    nsdsync
     package from the UIM internet archive or Downloads section of the UIM support site (http://support.nimsoft.com/).
  2. Using the Infrastructure Manager, drag the package to the target robot and drop it there.
     If the CMDB Gateway probe (
    cmdbgtw
    ) is not already present on the target robot, the 
    nsdsync
     installation process installs it for you. In either case, the installation also creates a database connection named "NIS Database connection", and an export named "Service Desk export" if they are not already present.
Next you must configure the CMDB Gateway probe to make use of the CA Cloud Service Management synchronization adapter.
Configure the CMDB Gateway to use the CA Cloud Service Management Adapter
The steps below configure the CMDB Gateway probe to make use of the CA Cloud Service Management Adapter.
 
To configure the CMDB Gateway probe for the CA Cloud Service Management adapter
 
  1. Double-click the 
    cmdbgtw 
    probe in Infrastructure Manager to launch the probe's configuration interface.
  2. Select the database named "NIS Database connection". Verify the connection parameters, and modify them if necessary to connect to your specific UIM database instance.
  3. Select the export named "Service Desk export".
  4. The 
    Finished Program
     field is pre-filled for you with 
    sdsync\Import.bat
     or 
    sdsync\Import.bin
    , depending on your platform. Below this are three custom properties, or parameters, for the Finished Program. They specify CA Cloud Service Management connection information, as follows:
    •  
      URL
      The CA Cloud Service Management Web Services URL that will be used for the import.
    •  
      User
      The user name of the CA Cloud Service Management account that will be used.
    •  
      Pass
      The password for the CA Cloud Service Management account that will be used.
    The user you specify must have a web services account in CA Cloud Service Management.
Additional Information Regarding CMDB Gateway Probe Deployment
This section describes how to install and configure the CMDB Gateway probe. Note that this probe is not restricted for use with the Service Desk Adapter, and this section does not call out the specific configuration required for that purpose.
Prerequisites
The cmdbgtw probe requires Java 1.6.0.14 or later.
If there are multiple instances of Java on the host, add the JRE_HOME environment variable and set it to a Java version that meets the above criterion.
Deployment Using Infrastructure Manager
There are two methods within Infrastructure Manager to distribute an archive package: drag and drop or right-click on a package name.
 The package must have a green box icon before you can distribute it to a machine. If the box icon is not green, you must download the package to the archive and have a valid license before distributing to a machine.
 
Right-click Method:
 
  1. Select a package name in the archive.
  2. Right-click and select 
    Distribute 
    from the menu.
    A Distribute dialog box appears.
  3. Select the domain/hub/robot where you want to distribute the package, and click the 
    Add
     button. The domain/hub/robot name appears in the right column.
  4. Click 
    OK
    . A View Distribution Progress dialog box appears with detailed information about the distribution.
     You can minimize this dialog box and continue working in Infrastructure Manager without interfering with the distribution.
  5. Click the 
    Close Dialog
     button after distribution is finished.
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.
Probe Configuration
There are two primary aspects to configure the cmdbgtw probe. One must first define one or 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.
Database Connection Setup Information
Please enter the following information to configure your database connection:
Field
Description
Name
Enter a name for the connection.
User
Database login user name
Password
Database password.
Driver Class
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.
SQL Dialect
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.
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 with 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...
 
Enter/choose values for:
Field
Description
Export Name
Enter a unique descriptive Export Name.
Root Entity
Select the type of data to export.
 
Note:
 The cmdbgtw probe ships with support for the UIM SLM database schema. It is possible to add support for missing entity types.
Database
Select a database connection.
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
Description
Name
Enter a descriptive name.
Root Entity
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.
Output Directory
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.
Database
Select the database connection to use
XSLT Transform
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>
Output Format
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
Description
Include Type
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.
XML Parent
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>
XML Name
The read-only XML element name for entities of this type.
Filter
A query where clause expressed in the Hibernate Query Language. 
Properties
A table showing the properties (aka database columns) that comprise the entity type:
  • Name - Enter the property name
  • Column - Enter the database column name.
  • XML 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. 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 http://www.w3.org/TR/NOTE-datetime.
Testing and Running Exports
Select an export in the tree and you can see both a 
Test 
and a 
Run 
button on the right hand display. Test and Run are similar operations where they take the current export configuration, submit it to the probe and have the probe perform the export. The difference is in the output.
 
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.
Tree Context (right-click) Menu
A context sensitive popup-menu is available by right-clicking on a tree node:
Field
Description
New Export
Create a new export for monitoring.
Delete Export
Delete the selected export.
New Database Connection
Create a new database connection
Delete 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
 
CA recommends that when you first use the probe or are actively troubleshooting a problem, 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.
Advanced Data Mapping Customization
The cmdbgtw probe uses the Hibernate (see http://www.hibernate.org/) 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 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 '10.0.1.%'
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
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.
 
Custom Example 1 Custom table
You have a custom table added to your 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"
"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
<!-- Generated Aug 26, 2010 10:58:25 AM by Hibernate Tools 3.3.0.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:
<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>
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.
 
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.
UIM Callback Interface
The cmdbgtw probe includes a custom callback called 
runExport
. Other CA UIM message bus participants can send this message to the cmdbgtw probe to cause it to run the named export.
 
Callback Name: runExport
 
 
Parameters: 
 
Name
Value
exportName
The text name of the export you assigned when creating the export in the GUI
entityCountLimit
0 = unlimited, any other positive integer to limit the number of entities returned.
 
Result:
 
Name
Value
msg
On success, will display "ok"; on failure, will display the error message text
outfile
The path to the exported data file
nEntitiesGenerated
The number of root entities generated.