Create Mappings

The raw TQL result data is in the form of the UCMDB class model schema. It is likely that the consumer uses a different data model. The push adapter provides a mapping mechanism to transform the data into a format more suitable for consumption. Mappings perform both direct and complex transformations, from direct, naming-type conversion, to parent/child aggregation and referencing functions.

The mapping specification can be found in the section Mapping File Reference. Use the reference to create a mapping file.

Build a Mapping File

1. Start with a default mapping file.
2. Deploy the adapter and run it once.
3. Observe the results.

4. Identify and note what should be changed.

5. Make the changes identified in the previous step. The following list can help serve as a guide for the order of the changes.

   1. Start with the top, non-transformative section. Make sure the adapter runs after each change.

   2. Change the source CIs section to the UCMDB names in the TQL result.

   3. First map the keys.

   4. Then add all the direct mappings.

   5. Add the complex mappings.

   6. Add the link mappings.

Repeat steps 2-5 until the mapped data is suitable for consumption. Select the appropriate Generic adapter package from which to create the new push adapter.

The mapping files work the same way for all types of push adapters. The Generic XML push adapter writes the mapped results to a file. The Generic Web Service Push Adapter sends the XML results to a data receiver. For more details, see Generic Web Service Push Adapter.

Prepare the Mapping Files

There are two different ways to prepare mapping files:

• You can prepare a single, global mapping file.

  All mappings are placed in a single file named mappings.xml.

• You can prepare a separate file for each push query.

  Each mapping file is called <query name>.xml.

For details, see Mapping File Schema.

This task includes the following steps:

1. Create a mappings.xml File

   The mapping file structure is created as follows (use an existing file as a template):

   <?xml version="1.0" encoding="UTF-8"?>
   <integration>
       <info>
           <source name="UCMDB"  versions="9.x" vendor="HP" >
           <!-- for example: -->
           <target name="Oracle" versions="11g" vendor="Oracle" >
       </info>
       <targetcis>
           <!--- CI Mappings --->
       </targetcis>
       <targetrelations>
           <!--- Link Mappings --->
       </ targetrelations>
   </integration>
   

2. Map CIs

   There are two ways to map CMDB CI types:

   • Map a CI type so that CIs of that type and all inherited types are mapped in the same way:

     <source_ci_type_tree name="node" mode="update_else_insert">
         <apioutputseq>1</apioutputseq>
         <target_ci_type  name="host">
             <targetprimarykey>
                 <pkey>name</pkey>
             </targetprimarykey
             <target_attribute name=" name" datatype="STRING">
                 <map type="direct" source_attribute="name" >
             </target_attribute>
             <!-- more target attributes --->
         </target_ci_type>
     </source_ci_type_tree>
     

   • Map a CI type so that only CIs of that type are processed. CIs of inherited types are not processed unless their type is also mapped (in one of the two ways):

     <source_ci_type name="node" mode="update_else_insert">
         <apioutputseq>1</apioutputseq>
         <target_ci_type  name="host">
             <targetprimarykey>
                 <pkey>name</pkey>
             </targetprimarykey
             <target_attribute name=" name" datatype="STRING">
                 <map type="direct" source_attribute="name" >
             </target_attribute>
             <!-- more target attributes --->
         </target_ci_type>
     </source_ci_type>
     

   A CI type which is mapped indirectly (one of its ancestors is mapped using source_ci_type_tree), can also override its parent's map by having it appear in its own source_ci_type_tree or source_ci_type.

   It is recommended to use source_ci_type_tree wherever possible. Otherwise, resulting CIs of a CI type that do not appear in the mapping files will not be transferred to the Jython script.

3. Map Links

   There are two ways to map links:

   • Map a link so that links of that type and all inherited links are mapped in the same way:

     <source_link_type_tree name="dependency" target_link_type="dependency" mode="update_else_insert" source_ci_type_end1="webservice" source_ci_type_end2="sap_gateway">
         <target_ci_type_end1 name="webservice" >
         <target_ci_type_end2 name="sap_gateway" >
             <target_attribute name="name" datatype="STRING">
                 <map type="direct" source_attribute="name" >
             </target_attribute>
     </source_link_type_tree>
     

   • Map a link so that only links of that type are processed. Links of inherited types are not processed unless their type is also mapped (in one of the two ways):

     <link source_link_type="dependency" target_link_type="dependency" mode="update_else_insert" source_ci_type_end1="webservice" source_ci_type_end2="sap_gateway">
             <target_ci_type_end1 name="webservice" >
             <target_ci_type_end2 name="sap_gateway" >
             <target_attribute name="name" datatype="STRING">
                 <map type="direct" source_attribute="name" >
         </target_attribute>
     </link>