Out-of-the-Box Converters

You can use the following converters (transformers) to convert federated queries and replication jobs to and from database data.

The enum-transformer Converter

This converter uses an XML file that is given as an input parameter.

The XML file maps between hard-coded CMDB values and database values (enums). If one of the values does not exist, you can choose to return the same value, return null, or throw an exception.

The transformer performs a comparison between two strings using a case sensitive, or a case insensitive method. The default behavior is case sensitive. To define it as case insensitive use: case-sensitive="false" in the enum-transformer element.

Use one XML mapping file for each entity attribute.

Input File XSD:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:element name="enum-transformer">
    <xs:complexType>
        <xs:sequence>
           <xs:element ref="value" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="db-type" use="required">
           <xs:simpleType>
               <xs:restriction base="xs:string">
                   <xs:enumeration value="integer"/>
                   <xs:enumeration value="long"/>
                   <xs:enumeration value="float"/>
                   <xs:enumeration value="double"/>
                   <xs:enumeration value="boolean"/>
                   <xs:enumeration value="string"/>
                   <xs:enumeration value="date"/>
                   <xs:enumeration value="xml"/>
                   <xs:enumeration value="bytes"/>
              </xs:restriction>
           </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="cmdb-type" use="required">
           <xs:simpleType>
              <xs:restriction base="xs:string">
                  <xs:enumeration value="integer"/>
                  <xs:enumeration value="long"/>
                  <xs:enumeration value="float"/>
                  <xs:enumeration value="double"/>
                  <xs:enumeration value="boolean"/>
                  <xs:enumeration value="string"/>
                  <xs:enumeration value="date"/>
                  <xs:enumeration value="xml"/>
                  <xs:enumeration value="bytes"/>
               </xs:restriction>
           </xs:simpleType>
         </xs:attribute>
         <xs:attribute name="non-existing-value-action" use="required">
            <xs:simpleType>
		<xs:restriction base="xs:string">
                   <xs:enumeration value="return-null"/>
                   <xs:enumeration value="return-original"/>
                   <xs:enumeration value="throw-exception"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="case-sensitive" use="optional">
            <xs:simpleType>
                <xs:restriction base="xs:boolean">
                </xs:restriction>
            </xs:simpleType>
        </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:element name="value">
    <xs:complexType>
        <xs:attribute name="cmdb-value" type="xs:string" use="required"/>
        <xs:attribute name="external-db-value" type="xs:string" use="required"/>
        <xs:attribute name="is-cmdb-value-null" type="xs:boolean" use="optional"/>
        <xs:attribute name="is-db-value-null" type="xs:boolean" use="optional"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example of Converting 'sys' Value to 'System' Value:

In this example, sys value in the CMDB is transformed into System value in the federated database, and System value in the federated database is transformed into sys value in the CMDB.

If the value does not exist in the XML file (for example, the string demo), the converter returns the same input value it receives.

<enum-transformer CMDB-type="string" DB-type="string" non-existing-value-action="return-original" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../META-CONF/generic-enum-transformer.xsd">
    <value CMDB-value="sys" external-DB-value="System" />
</enum-transformer>

Example of Converting an External or CMDB Value to a Null Value:

In this example, a value of NNN in the remote database is transformed into a null value in the CMDBdatabase.

<value cmdb-value="null" is-cmdb-value-null="true" external-db-value="NNN"/>

In this example, the value OOO in the CMDB is transformed into a null value in the remote database.

<value cmdb-value="OOO" external-db-value="null" is-db-value-null="true"/>

The SuffixTransformer Converter

This converter is used to add or remove suffixes from the CMDB or federated database source value.

There are two implementations:

• com.mercury.topaz.fcmdb.adapters.dbAdapter.dal.transform.impl.AdapterToCmdbAddSuffixTransformer. Adds the suffix (given as input) when converting from federated database value to CMDB value and removes the suffix when converting from CMDB value to federated database value.

• com.mercury.topaz.fcmdb.adapters.dbAdapter.dal.transform.impl.AdapterToCmdbRemoveSuffixTransformer. Removes the suffix (given as input) when converting from federated database value to CMDB value and adds the suffix when converting from CMDB value to federated database value.

The PrefixTransformer Converter

This converter is used to add or remove a prefix from the CMDB or federated database value.

There are two implementations:

• com.mercury.topaz.fcmdb.adapters.dbAdapter.dal.transform.impl.AdapterToCmdbAddPrefixTransformer. Adds the prefix (given as input) when converting from federated database value to CMDB value and removes the prefix when converting from CMDB value to federated database value.

• com.mercury.topaz.fcmdb.adapters.dbAdapter.dal.transform.impl.AdapterToCmdbRemovePrefixTransformer. Removes the prefix (given as input) when converting from federated database value to CMDB value and adds the prefix when converting from CMDB value to federated database value.

The BytesToStringTransformer Converter

This converter is used to convert byte arrays in the CMDB to their string representation in the federated database source.

The converter is: com.mercury.topaz.fcmdb.adapters.dbAdapter.dal.transform.impl.CmdbToAdapterBytesToStringTransformer.

The StringDelimitedListTransformer Converter

This converter is used to transform a single string list to an integer/string list in the CMDB.

The converter is: com.mercury.topaz.fcmdb.adapters.dbAdapter.dal.transform.impl. StringDelimitedListTransformer.

The Custom Converter

It is possible to write your own custom converter (transformer) from scratch. This enables you to create any converter required for your needs.

There are two ways to write a custom converter:

1. Write a compiled Java converter

   1. Create a Java Project in a Java IDE (such as Eclipse, Intellij, or Netbeans).

   2. Add the federation-api.jar and db-interfaces.jar to your class path.

   3. Create a Java class that implements the following interfaces (from db-interfaces.jar):

      • FcmdbDalTransformerFromExternalDB

      • FcmdbDalTransformerValuesToExternalDB

      • FcmdbDalTransformerInit

   4. Compile the project and create a jar file.

   5. Place the jar file in the adapter’s package (under adapterCode\<Adapter ID>)

   6. Deploy the package.

   7. Add the new converter class name to the transformations.txt file.

2. Write a Groovy (script based) converter

   An example is found in the original GDBA package, GroovyExampleTransformer.groovy.

   1. Create a Groovy file in the adapter’s package (under adapterCode\<Adapter ID>). You can do this directly using the Adapter Management menu.

   2. Create a Groovy class that implements the following interfaces (from db-interfaces.jar):

      • FcmdbDalTransformerFromExternalDB

      • FcmdbDalTransformerValuesToExternalDB

      • FcmdbDalTransformerInit

   3. Add the new converter Groovy class name to the transformations.txt file accordingly.

   Note Groovy is a scripting language that extends Java. Regular Java code is valid Groovy code as well.