Add an Adapter for a New External Data Source

This task explains how to define an adapter to support a new external data source.

1. Prerequisites

   Model-supported adapter classes for CIs and relationships in the UCMDB Data Model. As an adapter developer, you should:

   • have knowledge of the hierarchy of the UCMDB CI types to understand how external CITs are related to the UCMDB CITs

   • model the external CITs in the UCMDB class model

   • add the definitions for new CI types and their relationships

   • define valid relationships in the UCMDB class model for the valid relationships between adapter inner classes. (The CITs can be placed at any level of the UCMDB class model tree.)

   Modeling should be the same regardless of federation type (on the fly or replication). For details on adding new CIT definitions to the UCMDB class model, see Working with the CI Selector.

   For the adapter to support federated attributes on CITs, add this CIT to the supported classes with supported attributes and the reconciliation rule for this CIT.

2. Define Valid Relationships for Virtual Relationships

   Note This section is only relevant for federation.

   To retrieve federated CITs that are connected to local CMDB CITs, a valid link definition must exist between the two CITs in the CMDB.

   1. Create a valid links XML file that contains these links (if they do not already exist).

   2. Add the links XML file to the adapter package in the \validlinks folder. For details, see Package Manager.

   Example of Valid Relationship Definition:

   In the following example, the relation of type containment between instances of type node to instances of type myclass1 is a valid relationship definition.

   <Valid-Links>
       <Valid-Link>
           <Class-Ref class-name="containment">
           <End1 class-name="node">
           <End2 class-name="myclass1">
           <Valid-Link-Qualifiers>
       </Valid-Link>
   </Valid-Links>
   

3. Define an Adapter Configuration

   1. Navigate to Adapter Management.

   2. Click the Create new resource button and select New Adapter.

   3. In the New adapter dialog box, select Integration and Java Adapter.

   4. Right-click the adapter that you created and select Edit Adapter Source from the shortcut menu.

   5. Edit the following XML tags:

      <pattern xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="newAdapterIdName" xsi:noNamespaceSchemaLocation="../../Patterns.xsd" description="Adapter Description" schemaVersion="9.0" displayName="New Adapter Display Name">

      <deletable>true</deletable>

      <discoveredClasses>

      <discoveredClass>link</discoveredClass>

      <discoveredClass>object</discoveredClass>

      </discoveredClasses>

      <taskInfo className="com.hp.ucmdb.discovery.probe.services.dynamic.core.
      AdapterService">

      <params className="com.hp.ucmdb.discovery.probe.services.dynamic.core.
      AdapterServiceParams" enableAging="true" enableDebugging="false" enableRecording=
      "false" autoDeleteOnErrors="success" recordResult="false" maxThreads="1" patternType="java_adapter" maxThreadRuntime="25200000">

      <className>com.yourCompany.adapter.MyAdapter.MyAdapterClass
      </className>

      </params>

      <destinationInfo className="com.hp.ucmdb.discovery.probe.tasks.BaseDestinationData">

      <!-- check -->

      <destinationData name="adapterId" description="">${ADAPTER.adapter_id}</destinationData>

      <destinationData name="attributeValues" description="">${SOURCE.attribute_values}</destinationData>

      <destinationData name="credentialsId" description="">${SOURCE.credentials_id}</destinationData>

      <destinationData name="destinationId" description="">${SOURCE.destination_id}</destinationData>

      </destinationInfo>

      <resultMechanism isEnabled="true">

      <autoDeleteCITs isEnabled="true">

      <CIT>link</CIT>

      <CIT>object</CIT>

      </autoDeleteCITs>

      </resultMechanism>

      </taskInfo>

      <adapterInfo>

      <adapter-capabilities>

      <support-federated-query>

      <!--<supported-classes/> <!—see the section about supported classes-->

      <topology>

      <pattern-topology /> <!—or <one-node-topology> -->

      </topology>

      </support-federated-query>

      <!--<support-replicatioin-data>

      <source>

      <changes-source/>

      </source>

      <target/>

      </adapter-capabilities>

      <default-mapping-engine />

      <queries />

      <removedAttributes />

      <full-population-days-interval>-1</full-population-days-interval>

      </adapterInfo>

      <inputClass>destination_config</inputClass>

      <protocols />

      <parameters>

      <!--The description attribute may be written in simple text or HTML.-->

      <!--The host attribute is treated as a special case by UCMDB-->

      <!--and will automatically select the probe name (if possible)-->

      <!--according to this attribute’s value.-->

      <parameter name="credentialsId" description="Special type of property, handled by UCMDB for credentials menu" type="integer" display-name="Credentials ID" mandatory="true" order-index="12" />

      <parameter name="host" description="The host name or IP address of the remote machine" type="string" display-name="Hostname/IP" mandatory="false" order-index="10" />

      <parameter name="port" description="The remote machine's connection port" type="integer" display-name="Port" mandatory="false" order-index="11" />

      </parameters>

      <parameter name="myatt" description="is my att true?" type="string" display-name="My Att" mandatory="false" order-index="15" valid-values=”True;False”/>True</parameters>

      <collectDiscoveredByInfo>true</collectDiscoveredByInfo>

      <integration isEnabled="true">

      <category >My Category</category>

      </integration>

      <overrideDomain>${SOURCE.probe_name}</overrideDomain>

      <inputTQL>

      <resource:XmlResourceWrapper xmlns:resource="http://www.hp.com/ucmdb/1-0-0/ResourceDefinition" xmlns:ns4="http://www.hp.com/ucmdb/1-0-0/ViewDefinition" xmlns:tql="http://www.hp.com/ucmdb/1-0-0/TopologyQueryLanguage">

      <resource xsi:type="tql:Query" group-id="2" priority="low" is-live="true" owner="Input TQL" name="Input TQL">

      <tql:node class="adapter_config" id="-11" name="ADAPTER" />

      <tql:node class="destination_config" id="-10" name="SOURCE" />

      <tql:link to="ADAPTER" from="SOURCE" class="fcmdb_conf_aggregation" id="-12" name="fcmdb_conf_aggregation" />

      </resource>

      </resource:XmlResourceWrapper>

      </inputTQL>

      <permissions />

      </pattern>

   For details about the XML tags, see XML Configuration Tags and Properties.

4. Define Supported Classes

   Define supported classes either in the adapter code by implementing the getSupportedClasses() method, or by using the pattern XML file.

   <supported-classes>
       <supported-class name="HistoryChange" is-derived="false" is-reconciliation-supported="false" federation-not-supported="false" is-id-reconciliation-supported="false">
       <supported-conditions>
           <attribute-operators attribute-name="change_create_time">
               <operator>GREATER</operator>
               <operator>LESS</operator>
               <operator>GREATER_OR_EQUAL</operator>
               <operator>LESS_OR_EQUAL</operator>
               <operator>CHANGED_DURING</operator>
           </attribute-operators>
       </supported-conditions>
    </supported-class>
   

   name	The name of the CI type
   is-derived	Specifies whether this definition includes all inheriting children
   is-reconciliation-supported	Specifies whether this class is used for reconciliation
   is-id-reconciliation-supported	Specifies whether this class is used for id-reconciliation
   federation-not-supported	Specifies whether this CIT should not be allowed for federation (blocking certain CITs, for example, a CIT defined solely for federation)
   <supported-conditions>	Specifies the supported conditions on each attribute

5. Implement the Adapter

   Select the correct adapter implementation class according to its defined capabilities. The adapter implementation class implements the appropriate interfaces according to defined capabilities.

   If the adapter implements getTopologyWithReconciliationData and adapter capabilities include the ability to be used as a starting point, the adapter should also support requesting topology with reconciliation data without any conditions (only type). In this case the adapter should return full reconciliation data of the found results.

   Adapter reconciliation support can be defined according to global_id, in which case global_id must be defined as part of the reconciliation attributes in the adapter supported classes. If adapter reconciliation support is defined according to global_id, then getTopologyWithReconciliationData() should return the global_id as part of the reconciliation object properties. The UCMDB uses global_id for reconciliation of federation results for a CIT instead of the identification rule.

   Part of the federation API is the DataAdapterEnvironment interface. This interface represents the environment of the data adapter. It contains the environment API needed for the adapter to work. For more information on the DataAdapterEnvironment interface, see The DataAdapterEnvironment Interface.

6. Define Reconciliation Rules or Implement the Mapping Engine

   If your adapter supports federated TQL queries, you have two options for defining your Mapping Engine:

   • Use the default mapping engine, which uses the CMDB's internal reconciliation rules for mapping. To use it, leave the <default-mapping-engine> XML tag empty.

   • Write your own mapping engine by implementing the mapping engine interface and placing the JAR with the rest of the adapter code. To do this, use the following XML tag: <default-mapping-engine>com.yourcompany.map.MyMappingEngine</default-mapping-engine>

7. Add Jars Required for Implementation to the Class Path

   To implement your classes, add the federation_api.jar file to your code editor class path.

8. Deploy the Adapter

   Deploy the adapter package. For general details on deploying a package, see Package Manager.

   The package should contain the following entities:

   • New CIT definition (optional):

   • Used only if the adapter supports new CI types that do not yet exist in UCMDB.

   • The new CIT definitions are located in the class folder in the package.

   • New data type definition (optional):

   • Used only if the new CITs require new data types.

   • The new data type definitions are located in the typedef folder in the package.

   • New valid relationships definition (optional):

   • Used only if the adapter supports the federated TQL.

   • The new valid relationships definitions are located in the validlinks folder in the package.

   • The pattern configuration XML file should be located in the discoveryPatterns folder in the package.

   • Descriptor. Defines the package definitions.

   • Place your compiled classes (normally a jar file) in the package under the adapterCode\<adapter id> folder.

     Note The adapter id folder name has the same value as in the adapter configuration.

   • If you create your own configuration file, you should place the file in the package under the adapterCode\<adapter id> folder.

9. Update the Adapter

   Changes to any of the adapter's non-binary files may be made in the Adapter Management module. Making changes to configuration files in the Adapter management module causes the adapter to reload with the new configurations.

   Updates may also be made by editing the files in the package (both binary and non-binary files), and then redeploying the package by using the Package Manager. For details, see How to Deploy a Package.