Implement a Plug-in

This task describes how to implement and deploy a Generic DB Adapter with plug-ins.

1. Option 1 – Write a Java based plug-in

   1. Copy the following jar files from the UCMDB server installation directory to your development class path:

      • Copy the db-interfaces.jar file and db-interfaces-javadoc.jar file from the tools\adapter-dev-kit\db-adapter-framework folder.

      • Copy the federation-api.jar file and federation-api-javadoc.jar file from the \tools\adapter-dev-kit\SampleAdapters\production-lib folder.

        Note More information about developing a plug-in can be found in the db-interfaces-javadoc.jar and federation-api-javadoc.jar files and in the online documentation at:

        • C:\UCMDB\UCMDBServer\deploy\ucmdb-docs\docs\eng\APIs\DBAdapterFramework_JavaAPI\index.html

        • C:\UCMDB\UCMDBServer\deploy\ucmdb-docs\docs\eng\APIs\Federation_JavaAPI\index.html

   2. Write a Java class implementing the plug-in's Java interface. The interfaces are defined in the db-interfaces.jar file. The table below specifies the interface that must be implemented for each plug-in:

      Plug-in Type	Interface Name	Method
      Synchronize Full Topology	FcmdbPluginForSyncGetFullTopology	getFullTopology
      Synchronize Changes	FcmdbPluginForSyncGetChangesTopology	getChangesTopology
      Synchronize Layout	FcmdbPluginForSyncGetLayout	getLayout
      Retrieve Supported Queries	FcmdbPluginForSyncGetSupportedQueries	getSupportedQueries
      Alter TQL query definition and results	FcmdbPluginGetTopologyCmdbFormat	getTopologyCmdbFormat
      Alter layout request for CIs	FcmdbPluginGetCIsLayout	getCisLayout
      Alter layout request for links	FcmdbPluginGetRelationsLayout	getRelationsLayout
      Push Back IDs	FcmdbPluginPushBackIds	getPushBackIdsSQL

      The plug-in's class must have a public default constructor. Also, all of the interfaces expose a method called initPlugin. This method is guaranteed to be called before any other method and is used to initialize the adapter with the containing adapter's environment object.

      If FcmdbPluginForSyncGetChangesTopology is implemented, there are two different ways to report the changes:

      • Report the entire root topology at all times. According to this topology, the auto-delete function finds which CIs should be removed. In this case, the auto-delete function should be enabled by using the following:

      <autoDeleteCITs isEnabled="true">
                      <CIT>link</CIT>
                      <CIT>object</CIT>
                  </autoDeleteCITs>
      

      • Report each CI instance that was removed/updated. In this case the auto-delete mechanism should be disabled by using the following:

       <autoDeleteCITs isEnabled="false">
                      <CIT>link</CIT>
                      <CIT>object</CIT>
                  </autoDeleteCITs>
      

   3. Make sure you have the Federation SDK JAR and the Generic DB Adapter JARs in your class path before compiling your Java code. The Federation SDK is the federation_api.jar file, which can be found in the C:\UCMDB\UCMDBServer\lib directory.

   4. Pack your class into a jar file and put it under the adapterCode\<Your Adapter Name> folder in the adapter package, prior to deploying it.

2. Option 2 – Write a Groovy based plug-in

   1. Create a Groovy code file (MyPlugin.groovy) in the Adapter Management Menu, under the adapter package configuration files.

   2. In the Groovy class, implement the appropriate interfaces. The interfaces are defined in the db-interfaces.jar file, see the table above.

3. The plug-ins are configured using the plugins.txt file, located in the \META-INF folder of the adapter.

   The following is an example of the file from the DDMi adapter:

   # mandatory plugin to sync full topology
   [getFullTopology]
   com.hp.ucmdb.adapters.ed.plugins.replication.EDReplicationPlugin
   # mandatory plugin to sync changes in topology
   [getChangesTopology]
   com.hp.ucmdb.adapters.ed.plugins.replication.EDReplicationPlugin
   # mandatory plugin to sync layout
   [getLayout]
   com.hp.ucmdb.adapters.ed.plugins.replication.EDReplicationPlugin
   # plugin to get supported queries in sync. If not defined return all tqls names
   [getSupportedQueries]
   # internal not mandatory plugin to change tql definition and tql result
   [getTopologyCmdbFormat]
   # internal not mandatory plugin to change layout request and CIs result
   [getCisLayout]
   # internal not mandatory plugin to change layout request and relations result
   [getRelationsLayout] 
   # internal not mandatory plugin to change action on pushBackIds 
   [pushBackIds]
   

   Legend:

   # - A comment line.

   [<Adapter Type>] – Start of the definition section for a specific adapter type.

   There can be an empty line under each [<Adapter Type>], meaning that there is no plug-in class associated, or the fully qualified name of your plug-in class can be listed.

4. Pack your adapter with the new jar file and the updated plugins.xml file. The remainder of the files in the package should be the same as in any adapter based on the Generic DB adapter.