Build an Adapter Package

To create a new, MDR-specific push adapter, you should make a copy of the generic adapter and then edit it to customize it as an adapter for a specific push target.

Generic adapters packages can be found in the following location:

C:\UCMDB\UCMDBServer\content\adapters\generic-adapter.zip

To create a new push adapter from the generic push adapter:

1. Extract the content of the selected package zip file to a work folder.

2. Review the following directories in preparation for the rename and replace phase:

   • adapterCode: Contains the directory that is deployed to the C:\UCMDB\UCMDBServer\runtime\fcmdb\CodeBase directory. Jars deployed here do not automatically restart the probe and do not appear automatically in the probe’s CLASSPATH.

   • discoveryConfigFiles: Contains the adapter's mappings definitions and points to the correct Jython script (push.properties)

   • discoveryPatterns: Contains the adapter's XML definition that is deployed on the UCMDB server

   • discoveryScripts: Contains the adapter's Jython scripts via which the connection to the third party data store is made and data is pushed

   • discoveryResources: Contains the UCMDBDataReceiver.jar containing the Java integration classes for the web service.

   Note When you deploy this package, the probe is restarted to include this .jar in the probe’s CLASSPATH. No action is required beyond deploying the package.

3. Make the following changes within the unzipped adapter directory structure:

   1. discoveryConfigFiles\<Your_Push_Adapter_Name>: rename the directory "PushAdapter" or "XMLtoWebService" to the name of the new push adapter (for example, “myPushAdapter”).

   2. discoveryConfigFiles\<Your_Push_Adapter_Name>\push.properties: In the push.properties file, do the following:

      • Update the name of jythonScript.name to the name of the Jython script to be used by the new push adapter (for example, pushToMyService.py).

      • Update the name of the mappings file to be used by the new push adapter (for example, myPushAdapter_mappings). Do no add the .xml extension, this is filled in automatically.

   3. discoveryPatterns\<push adapter name>.xml: Rename this file to the name of the new adapter's definition XML file (for example, my_push_adapter.xml).

   4. discoveryPatterns\<your_push_adapter>.xml: Update this file as follows:

      • For the XML element <pattern>: set the id and description attributes accordingly. For example:

        <pattern id="PushAdapter" xsi:noNamespaceSchemaLocation="../../Patterns.xsd" description="Discovery Pattern Description" schemaVersion="9.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

        is changed to:

        <pattern id="MyPushAdapter" displayLabel="My Push Adapter" xsi:noNamespaceSchemaLocation="../../Patterns.xsd" description="Discovery Pattern Description" schemaVersion="9.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

      • For the XML element <parameters>: update the children elements according to the needs of your adapter. By default, the following children elements are used to define a push adapter. These values are assigned when the integration point is defined in the Integration Studio after the adapter is configured. Update the parameter list so that the list of parameters reflects the required connection attributes. Do not remove the probeName attribute.

        • host: the server name hosting the web service

        • port: port of the listening UCMDB Data Receiver service

        • Web Service Push Adapter: uri - the remainder of the URL to form the service endpoint address of the data receiver.

        • probeName: defines on which data flow probe the push job runs

      • For the XML element <integration>: update the value of the child element <category> to something other than Generic. By default integration adapters belonging to the Generic category are not shown in the Integration Studio. If you are integrating with a third-party data store, set this value to "Third Party". If you are integrating with an Micro Focus BTO product, set this value to "HPE BTO Products".

   5. adapterCode\PushAdapter: rename this folder with the adapter ID used in the previous step (for example, adapterCode\MyPushAdapter).

   6. discoveryScripts\<your_Jython_push_script>.py: create a file with the same name as the one defined in the push.properties jythonScript.name property. In the discoveryScript file, there is a script that inserts the CIs and links to an external Oracle database. Replace discoveryScripts\pushScript.py with the script you wrote (for details, see Write Jython Scripts). If you rename the script, the jythonScript.name property in adapterCode\<adapter ID>\push.properties should be updated accordingly.

      • XML Push Adapter: pushScript.py

      • Web Service Push Adapter: XMLtoWebService.py

   7. tql\<your_integration_TQLs>: like a regular package, place the TQL XML definition of your integration TQLs in this directory. All TQLs in this folder are deployed when the adapter package is deployed.
   8. discoveryConfigFiles\<Your_Push_Adapter_Name>\mappings: create an XML mapping file per TQL that you want to use in your integration. Note that the push adapter applies the transformations in the mapping file to the results of the integration TQLs and then sends that data in three parameters (addResult, updateResult, and deleteResult) of an ad hoc task to the data flow probe.

   9. adapterCode\<adapter ID>\mappings: replace the mappings.xml file with the mapping files you prepared (for details, see Create Mappings).

      XML Push Adapter: This mapping example corresponds to the example of the tables created in ORACLE in the sql_queries file.

      To use a mapping file for each TQL method, assign the name of the corresponding TQL to each XML file, followed by .xml. In this case, the mappings.xml file is used as by default, if no specific mapping file is found for the current TQL name. The name of the default mapping file can be modified by changing the mappingFile.default property in adapterCode\<adapter ID>\push.properties.

4. After making all the above changes, create a .zip file by selecting the folders and files specified in step 3 above (for example, my_Push_Adapter.zip).
5. Deploy the newly created .zip file on the UCMDB server via the Package Manager (go to Administration > Package Manager).
6. Create an integration point in Data Flow Management > Integration Studio and define the integration TQLs that the integration point uses. Set a schedule for automatic data push.

Troubleshooting

The procedure for building a new push adapter requires complete and correct re-naming and replacing. Any error will likely affect the adapter. The package must be unzipped and re-zipped correctly to act as a UCMDB package. Refer to the out-of-the-box packages as examples. Common errors include:

• Including another directory on top of the package directories in the ZIP file.

  Solution: ZIP the package in the same directory as the package directories such as discoveryResources, adapterCode, etc. Do not include another directory level on top of this in the ZIP file.

• Omitting a critical re-name of a directory, a file, or a string in a file.

  Solution: Following the instructions in this section very carefully.

• Misspelling a critical re-name of a directory, a file, or string in a file.

  Solution: Do not change your naming convention in mid-stream once you begin the re-naming procedure. If you realize that you need to change the name, start over completely rather than trying to retroactively correcting the name, as there is a high risk of error. Also, use search and replace rather than manually replacing strings to reduce risk of errors.

• Deploying adapters with the same file names as other adapters, especially in the discoveryResources and adapterCode directories.

  Solution: You may be using a UCMDB version with a known issue that prevents mappings files from having the same name as any other adapter in the same UCMDB environment. If you attempt to deploy a package with duplicates names, the package deployment will fail. This problem may occur even if these files are in different directories. Further, this problem can occur regardless of whether the duplicates are within the package or with other previously deployed packages.

At this point you can create a new push adapter job in the Integration Studio using the new adapter you just deployed.

TQL Best Practices for Push Adapters

1. Create a folder structure in the TQL and View trees, and keep all new TQLs and views there. Use a naming convention.
2. Unless the TQL is small, first copy the most similar TQL.
3. Make one change at a time. Save, test, and preview after each change. Repeat until the results comply with your requirements.