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.

Note The adapter properties file refers to the name of the mapping file. In adapter configuration files, the adapter implements a folder structure using the name of the adapter. Rename this folder when implementing an adapter to maintain uniqueness as required by the Package Manager.

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

Note You can retrieve all of the CIs and relationships as they are in the CMDB without mapping, by not creating the mappings.xml file. This returns all of the CIs and relationships with all of their attributes.

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: