Customizing SA data sent to the uCMDB server

Mapping file

The SA-uCMDB Connector XML mapping file describes the data being transferred by the SA-uCMDB Connector and enables you to customize the data mappings.

The initial mapping.xml is generated when the connector first runs. After it is generated, you can find the new mapping file at:

/etc/opt/opsware/tell/metadata/mapping.xml

The mapping file allows you to control:

• Data types and attributes that populate uCMDB
• Mappings between the optional SA custom attributes and the uCMDB Data Model Configuration Item (CI) attributes.

Customizing the mapping file

In order to customize how data is mapped, you need to create and modify the mapping_custom.xml file, and then restart the Connector.

To customize the uCMDB Connector mappings:

1. If the uCMDB Connector is running, you must stop and disable the Connector before editing the mapping file.
   
   See Use cases for instructions.
   
   IMPORTANT: Make sure the connector is stopped and disabled. If the connector is not stopped and disabled when you edit the mapping file, you may encounter problems when you try to restart the Connector.
2. Create the custom mapping file:
   1. Go to: /etc/opt/opsware/tell/metadata

   2. Copy the mapping.xml file to the same folder and name the copy mapping_custom.xml.

   
   The mapping_custom.xml file must be in the same specified folder as the mapping.xml file to function properly.
3. Edit the /etc/opt/opsware/tell/metadata/mapping_custom.xml as needed.
   
   See Editing the mapping file for details on how to edit the mapping file for different purposes.
4. Run the enable command to change the configurations of the SA-uCMDB Connector.
   
   The syntax of the enable command varies depending on your environment. See The enable command in this document for an explanation of the enable command syntax and options.
5. Run the start command to restart the SA-uCMDB Connector:
   /etc/init.d/opsware-sas start telldaemon
6. Optionally check the status of the SA-uCMDB Connector with the following command:
   /etc/init.d/opsware-sas status telldaemon

Editing the mapping file

All customized mappings are defined in the mapping_custom.xml configuration file, so administrators can easily view and edit them. The XML mapping file can be modified to change the data being transferred by the SA-uCMDB connector. The mapping file also provides the ability to choose to omit specific CI and attributes. If the mapping_custom.xml does not exist, the connector by default will honor the out of box mapping.xml.

Permissions: In order to view or edit the mapping_custom.xml file, you must first log in to the SA Core as root in order to have read/write privileges.

Illustration of a mapping file

Here is a snippet of the out-of-the-box mapping file:

<Model-Definition model-name='hosts'>
	<CI ucmdb-ci-type-name='node' enable='true' base-class='node'
		<Attribute source='Node/Name' target-attr='name' enable='true'/>
		<Attribute source='Node/Description' target-attr='description'
	enable='true'/>
	</CI>	
</Model-Definition>

where the highlighted text indicates editable fields.

Each Model Definition tag in the mapping file defines a specific model name. In this example, this Model-Definition defines the ‘hosts’ model.

Each model can contain many Configuration Items (CIs). Each CI tag defines the composition of the CI. In this example, ‘node’ is the CI being defined.

For each attribute, source indicates the default attribute name in the source database.

• The target-attr field specifies the uCMDB attribute name that the source is mapping to.
• The enable field defines whether to map the attribute. The default value for enable is ‘true’; which means the attribute will be loaded into the uCMDB. When you set enable to ‘false’, you are choosing not to map the attribute; which means the attribute will not be loaded to uCMDB.

XML attribute values

This section shows the XML attribute values, indicating the editable and non-editable values:

XML attributes

XML attribute tag	Attributes	Sample attribute values and notes	Editable?
Model-Definition	model-name	‘hosts’, ‘sa’, 'software', 'compliance', 'hypervisor', 'vmrelations', 'compliance_status'	NOT editable
	enable	‘true’ to enable this attribute; ‘false’ to disable	Editable
CI	ucmdb-ci- type-name	Specifies the uCMDB CI type. For example: ‘node’, ‘ip_address’	Editable
	enable	‘true’ to enable this attribute; ‘false’ to disable	Editable
Attribute	source	Specifies the SA custom attribute name. For example: 'Node/Name', 'Node/Description', 'Node/BiosAssetTag', 'Node/BiosSerialNumber', 'Node/Facility', 'Node/VirtualizationTypeId' Caution Do not edit the source value. Modifying the source value will damage the mapping and may cause errors.	NOT editable
	target-attr	Specifies the uCMDB attribute name that the source is mapping to. For example: ‘name’, ‘description’ NOTE: target-attr value must be a unique name.	Editable
	enable	‘true’ to enable this attribute; ‘false’ to disable.	Editable
	conversion-name	Only used for conversion functions. See Customizing the data-conversion function for details. For example: 'com.hpe.tell.ConversionMethod$com.hpe.tell. MyConvertVirtualizationType'	Editable
Attribute-Custom	sa-custom- attribute- key-value	Specifies the SA custom attribute name. For example: ‘HW_RACK’, 'DEVICE_RACK' NOTE: See How to work with SA custom attributes .	Editable
	target-attr	Specifies the uCMDB attribute name that the source is mapping to. For example: ‘serial_number’, ‘facility’ NOTE: target-attr value must be a unique name.	Editable
	enable	‘true’ to enable this attribute; ‘false’ to disable.	Editable
CI-Filter	enable	‘true’ to enable this attribute; ‘false’ to disable. NOTE: See Filter support for queries for modifying CDATA block.	Editable
Relation	ucmdb- relation- type-name	Specifies uCMDB relationship between the CIs. For example: 'containment', 'aggregation'	Editable
	ucmdb- relation- from-ci-type-name	Specifies uCMDB relationship between the CIs of the ‘from’ CI. For example, if specifying a containment relationship from node to ip_address, the ‘node’ would be the ‘from’ CI in this relationship.	Editable
	ucmdb- relation- to-ci-type- name	Specifies uCMDB relationship between the CIs of the ‘to’ CI. For example, if specifying a containment relationship from node to ip_address, the ‘ip-address’ would be the ‘to’ CI in this relationship.	Editable
	enable	‘true’ to enable this attribute; ‘false’ to disable.	Editable
	ucmdb- relation-id- link	‘true’ if the relationship contains an ID link. This ‘true’ value requires the ‘from’ CI to exist, ‘false’ if the relationship does not contain an ID link.	Editable

Model definitions

Model definitions shows model definitions. There are 7 models defined in the mapping file that define how data objects are represented in uCMDB. For example, the SA model would represent SA in uCMDB.

Model definitions

Model definition model-name	Description
‘sa’	generates installed_software.xml
‘hosts’	generates node.xml
‘software’	generates installed_software.xml
‘compliance’	generates policy-xml
‘hypervisor’	generates hypervisor.xml
‘vmrelations’	generates hypervisor.Relationxml
‘compliance_status’	generates policyResult.xml

How to work with SA custom attributes

Transferring SA custom attributes to uCMDB

Custom attributes can also be loaded to uCMDB.

In addition to the SA attributes that are synchronized with uCMDB, the mappings in the mapping_custom.xml file enable you to specify any SA Custom Attributes defined with an SA Device or inherited from SA Facilities.

Custom Attributes can be specified in the mapping_custom.xml file as follows:

The following example shows how a user could configure the mapping file to extract the custom attribute, DEVICE_RACK, and load it to the my_location_rack destination in uCMDB. The enable attribute is set to ‘true,’ showing that the user chose to load this attribute to uCMDB.

<CI ucmdb-ci-type-name='node' enable='true' base-class='node'>
	<Attribute-Custom sa-custom-attribute-key-value='DEVICE_RACK' targetattr='
	my_location_rack' enable='true' />
</CI>

where the highlighted text indicates editable fields.

Filter support for queries

The mapping_custom.xml file provides the capability to filter specific criteria.

To filter by specific criteria:

• Embed the filtering clause in the CDATA section under CI-Filter tag.

• Specify whether the filter is enabled by supplying the value for enable attribute (‘true’ to enable, ‘false’ to disable).

  Note The CI-Filter specification is based on the SA database and requires knowledge of the SA schema. You can only supply one CI-Filter per CI type. If multiple filters are needed, you can specify a simple filter expression using AND and OR clauses.

Example of a single filter (out-of-the-box mapping in mapping.xml file):

<CI ucmdb-ci-type-name='node' enable='true' base-class='node'>
	<Attribute source='Node/Name' target-attr='name' enable='true' />
	<CI-Filter enable='true'><![CDATA[(DEVICES.OPSW_LIFECYCLE =
'MANAGED')]]></CI-Filter> 
</CI> 

In the above example, the filter selects SA devices with State: ‘managed’. By default, the SA-uCMDB Connector only synchronizes Managed device objects.

Example of a filter which includes an AND clause (modified mapping in mapping_custom.xml):

<CI-Filter enable='true'><![CDATA[(DEVICES.DVC_MODEL = 'POWEREDGE 2950') and (DEVICES.DVC_ID > 300000000)]]></CI-Filter>

In the above example, the filter selects SA devices with BOTH the Model, ‘POWEREDGE 2950’, and the ID greater than ‘300000000’.

Extended out-of-the-box mappings

The mapping file is provided to enable you to:

• Change names of attributes being populated in uCMDB
• Change how data is populated in uCMDB
• Specify which uCMDB CI type gets populated

Additional out-of-the-box mappings

The Facility and VirtualizationType attributes are disabled by default in the out-of-the-box mapping file. However, they may be enabled, as shown below:

ServerVO.getFacility()

<Attribute source='Node/Facility' target-attr='facility' enable='true'/>

ServerVO.getVirtualizationType()

<Attribute source='Node/VirtualizationTypeId' target-attr='virtualization_type_id' enable='true'/>

Customizing the data-conversion function

If data to be populated in uCMDB needs to be tailored during synchronization, Custom conversion methods can be written and provided to the SA-uCMDB Connector. The SA-uCMDB Connector can, then, apply these functions to transform the data from the SA syntax to the desired uCMDB syntax. For example, you can write custom conversion methods to convert lower case to upper case, or bytes to megabytes, and so on.

Customized conversion functions should be provided to the SA-uCMDB Connector via a jar file named tell_conversions.jar, and placed in /etc/opt/opsware/tell/lib prior to the connector startup. After you restart the connector, the custom conversion java class should extend the ConversionMethod class and import the com.hpe.tell.ConversionMethod package.

To customize data conversion:

1. If the SA-uCMDB Connector is running, you must stop and disable the Connector before editing the mapping file.
   • Run the stop command to stop the SA-uCMDB Connector:
     /etc/init.d/opsware-sas stop telldaemon

   • Run the disable command to disable the SA-uCMDB Connector:
     disable

     Note Make sure the connector is stopped and disabled. If the connector is not stopped and disabled when you edit the mapping file, you may encounter problems when you try to restart the Connector.

2. Write the customized conversation function code in java.
   
   For example, see Sample conversion file – MyConvertVirtualizationType.Java. In this example, the conversion file’s name is MyConvertVirtualizationType.java.

3. Modify the mapping_custom.xml file to utilize the conversion file that you just created.
   
   For example, you would place the following line in the mapping_custom.xml file to point to the java file, MyConvertVirtualizationType.java:

Original text in mapping file

<Attribute source='Node/VirtualizationTypeId' target-attr='virtualization_type_id' enable='false'/> 

Customized text in mapping file

<Attribute source='Node/VirtualizationTypeId' target-attr='device_isVirtual' enable='true' conversion-name='com.hpe.tell.ConversionMethod$com.hpe.tell.MyConvertVirtualizationType'/>

This modified line of XML has the following values:

• ‘device_isVirtual’ is the new attribute value for target-attr. Because this conversion changes the data type, it should be mapped to a different uCMDB attribute. However, if you are not changing the data type, then you should map to the same target-attr value.*
• conversion-name is the XML name for the conversion attribute. This is a verbatim label and cannot be substituted.
• ‘com.hpe.tell.ConversionMethod$com.hpe.tell.MyConvertVirtualizationType' is the attribute value for conversion-name, and MyConvertVirtualizationType.java is the java conversion code file name.

The target-attr value is critical to the success of the conversion operation:

Changing data types

If the conversion is changing an attribute’s data type, make sure that the destination attribute (specified by target-attr) has the same or compatible requirements, such as length and format. In the previous example, we modified the target-attr value because the conversion changes the actual data type. If, for example, you were merely converting the unit of measure (UOM), then you could specify the same target-attr value, because the actual data type did not change.

Unique filename per target-attr

Each target-attr conversion requires a unique java conversion code filename. The java conversion file represents a singular target-attr (output). For example, you can have multiple target-attr conversion scenarios for a single source attribute; however, each target-attr must be stated on an individual attribute tag in the mapping file, as shown in the following example:

 

<Attribute source='Node/VirtualizationTypeId' target-attr='virtualization_type_id1'

enable='true' conversion-name='com.hpe.tell.ConversionMethod$com.hpe.tell.MyConvertVirtualizationType1'/>

<Attribute source='Node/VirtualizationTypeId' target-attr='virtualization_type_id2'

enable='true' conversion-name='com.hpe.tell.ConversionMethod$com.hpe.tell.MyConvertVirtualizationType2'/>

4. Compile the customized conversion file (MyConvertVirtualizationType.java in this example). This generates the executable binaries.

5. Compress all of the conversion binaries into a jar file with the following name: tell_conversions.jar.

   Note You must use this exact jar filename for the SA-uCMDB Connector to recognize it.

6. Place the jar file in the SA Core directory, /etc/opt/opsware/tell/lib, prior to the starting up the uCMDB Connector.

   Note You must use this exact directory path for the SA-uCMDB Connector to recognize it.

7. Start the SA-uCMDB Connector.

The conversion function will convert the data dynamically, at the time the SA-uCMDB Connector is restarted.

Sample conversion file – MyConvertVirtualizationType.Java

This sample conversion file provides sample java code to use as a guideline. This java sample converts an SA VirtualizationType from Type: Numeric into Type: String for uCMDB.

package com.hpe.tell;

import java.math.BigDecimal;

import com.hpe.tell.ConversionMethod;

public class MyConvertVirtualizationType extends ConversionMethod {

	public Object convert(Object value) throws Exception{

		Integer vType = putInteger(value);

		String vValue;

		/*

		 * Function to convert SA VirtualizationType (numeric) to string type For uCMDB.

		 */

		if (vType > 0) {

			vValue = "True";

		} else {

			vValue = "False";

		}

		return vValue;

	}

	private Integer putInteger(Object o) throws Exception {

        if (o instanceof String) {

            return Integer.valueOf((String) o);

        }

        if (o instanceof BigDecimal) {

      	  return ((BigDecimal)o).intValue();

        }

        if (o instanceof Integer) {

      	  return (Integer)o;

        }

        throw new Exception("Invalid conversion in putInteger "+o.getClass().toString());

    }

}