How to Create and Configure Mapping Files Using the Visual Mapping Tool

1. Navigate to Data Flow Management > Adapter Management.

2. In the Resources pane, expand the Packages > <package name> > Configuration Files folder.

3. Do one of the following:

   • Click a mapping file and click Yes in the popup window that asks if you want to open the configuration file with the new mapping tool editor.

   • Right-click a mapping file and select Open Mapping Tool from the context menu
   • Click a mapping file and click the Open Mapping Tool icon at the top of the script pane, or
   • In the Configuration Files pane, double click a mapping file and click Yes in the popup window that asks if you want to open the configuration file with the new mapping tool editor.

   The new mapping tool editor window opens, with tree representation of local and external class models loaded and displayed.

   Note  

   • In case the integration point provides a null external class model, you can still open the Visual Mapping tool. An empty default class model will be displayed in the External Class Model pane instead.
   • If you open an old Enhanced Generic Push Adapter mapping file using the Visual Mapping tool, you will be asked if you want to convert the file to the new schema and that if you want to use the visual mapping tool as the default editor.
4. To view the entities and attributes of the UCMDB TQL or the external class model, expand the relationship type hierarchical tree in the Local Query pane or the External Class Model pane.

1. Navigate to Data Flow Management > Adapter Management.

2. In the Resources pane, expand the Packages > <package name> > Configuration Files folder.

   <package name> indicates the adapter package in where you want to create the new mapping file.

3. Click the Create new resource icon at the top of the Resource pane, and select New Configuration File.

4. In the Enter a Name dialog that pops up, provide values as described in the table below.

   Field	Description
   Name	Enter a name for the new mapping file. Naming convention for new mapping files: <adapter_name>/mappings/push/<filename>.xml For example, <adapter_name>/mappings/population/customDataPopulation.xml. Note: You must specify the adapter name and include push or population in the name.
   Package	Click for the Package field, then in the Select Package dialog that pops up, select a package and click OK.

   The new mapping file is created.

5. Open the new empty mapping file in the mapping tool editor, and edit the attribute mappings as necessary.

   For details, see How to Edit and Update a Mapping File Using the Visual Mapping Tool.

   Note  

   • For push scenario, you can add multiple roots, and you can select which one to use.

   • You can have duplicated source_instance nodes as long as the root-element is different.

6. Click Validate Mapping File to validate the mapping file you just created.

7. Click Save .

You can use one of the following methods:

• Quick action. Locate a corresponding entity in the External Class Model pane, and then select a desired attribute value in the External Class Model Attributes pane, and then click the green arrow button ( or ) to add the value to the mapping in the Visual Mapping pane.

• Drag and drop. After selecting a desired attribute value in the External Class Model Attributes pane, simply drag and drop the value to the Visual Mapping pane to update the selected mapping.

• Auto-complete. Directly type in the target attribute value field and select a desired value to update the mapping. The auto-complete suggestions are generated based on valid existing relationships between entities from the external class model or from the local TQL query.

  When you type a character, the first level suggestions will appear. Usually these are all first level CITs from the external class model that match the string or items from the local TQL query.

  After you type or select a valid CIT entity:

  • If you enter the "." character, you obtain suggestions for linked CITs based on existing relationships from the external class model or from the local TQL query.

    For example, you have a Computer to Node relationship,

    • if you type Computer, Node will appear in the suggestions list.

    • if you type Node, Computer will not appear unless you have another relationship from Node to Computer.

  • If you enter the "[" character, you obtain attribute suggestions for the current CIT:

    • For local TQL query, attributes are filtered with the Element Layout feature.

    • For external class model, all attributes are displayed.

  The Visual Mapping tool can also provide auto-complete suggestions on possible methods from imported Groovy scripts. For example, you have a mapping file that imports the mappings.scripts.AMPushFunctions Groovy script, if you write an attribute value like AMPushFunctions, you should receive a list of possible method names; If you write an attribute value like AMPushFunctions.get, you should receive a list of possible method names that start with get.

  

• Edit the mapping value in the XML Editor directly. You can directly edit the XML mapping value in the XML Editor pane below the Visual Mapping pane to update the mapping.

1. In the Local Query pane, select a UCMDB entity.

2. To add a UCMDB attribute to the Visual Mapping pane, in the Local Query Attribute pane, select a desired attribute and click the green arrow button ( or , depending on the push, population, or federation scenario).

   To add a source attribute from a different UCMDB TQL query,

   1. From the Query drop-down list, select a different UCMDB TQL query.

      If the desired TQL is not in the drop-down list, click Add TQL Queries . In the Add Queries dialog box, select and add an available integration TQL query from the Available items pane to the Selected items pane, then click OK.

   2. Expand the TQL query representation.
   3. Select a UCMDB entity that corresponds to the parent target_entity tag in the Visual Mapping pane where you want to add the new UCMDB attribute.
   4. In the Local Query Attributes pane, select an attribute and click the green arrow button ( or , depending on the push, population, or federation scenario) to move the attribute to the Visual Mapping pane.

3. Add a mapping attribute value from the External Class Model entity to the Visual Mapping pane.

   To do so, follow one of the following methods:

   • Quick action. Locate a corresponding entity in the External Class Model pane, and then select a desired attribute value in the External Class Model Attributes pane, and then click the green arrow button ( or ) to add the value to the mapping in the Visual Mapping pane.

   • Drag and drop. After selecting a desired attribute value in the External Class Model Attributes pane, simply drag and drop the value to the Visual Mapping pane to update the selected mapping.
   • Auto-complete. Directly type in the target attribute value field and select a desired value to update the mapping. The auto-complete suggestions are generated based on valid existing relationships between entities from the external class model or from the local TQL query.
   • Edit the mapping value in the XML Editor directly. You can directly edit the XML mapping value in the XML Editor pane below the Visual Mapping pane to update the mapping.

Do one of the following:

• Update Info Tag. Clicking this button opens the Update Info Tag dialog box, enabling you to modify and update the information about the data repositories being integrated, including Name, Version, and Vendor for both source and target data repositories.
• Update Import Tag. Click this button opens the Update Import Tag dialog box, enabling you to select and add available items and import new groovy scripts. You can also move up or down the sequence of a script to decide the order of scripts to be imported.

• Update Optional Tags. Clicking this button opens the Update Optional Tags dialog box, enabling you to update optional tags by defining values for the Type, Is Valid, and Is Delected fields. You can also select the Show Warning check box to display warning messages.

  Note: This button is not available for the source_entity tag.

Select the parent source_instance or target_entity element of your interest, and do the following to add the source element:

• Add For Each Tag. Clicking this button opens the Add For Each Tag dialog box, enabling you to define the source and the index for the tag that you want to add for each child mappings under the current parent entity:

  • Source Entities. Defines the source entities for the tag.
  • Count Index. Defines the iteration loop index ("i") that can be used to reference the currently iterated element. For example, pc.ip[i].
  • Var Name. (Optional) Specifies the variable name for the tag.

  Each time you edit a field you will see a notification of what attribute will be edited.

• Add Variable Tag. Clicking this button opens the Add Variable Tag dialog box, enabling you to define and add variable tags to the selected variable element:

  • Name. Specifies name for the variable.
  • Type. Select a value from the drop-down list as type of the variable in database.
  • Value. Specifies a value for the variable.
  Note: This button is not available for the source_instance tag.

• Add Custom Section. Enables you to add an empty section in the Visual Mapping pane, allowing you to manually define a new mapping element that may not fall into any of the existing mapping categories, including customized XML tags.

  After adding an empty section in the Visual Mapping pane by clicking the Add Custom Section button, you can edit the empty section in the XML Editor pane. Clicking Save in the XML Editor saves the code.

  Note: To save the entire mapping file, click Save for the entire Visual Mapping tool window.

When creating attribute mappings such as the one below, you may have a use case to ignore certain attribute mappings within a target entity based on some custom logic:

This can be done via the newly added is-valid XML attribute on the target_mapping XML tag.

If you change the mapping line for the description attribute to use the new XML attribute, you get something like this:

<target_mapping name="description" is-valid="CustomFunctions.isSupportedType(Computer['name'])" datatype="STRING" value="Computer['name']"/>

where CustomFunctions.isSupportedType(Computer['name']) represents a Groovy expression that will result in a boolean value (true means the attribute is valid, false means the attribute will be ignored).

For a quick check you can use any simple expression like "1 == 1" or "true".

Relevant log lines are also available. For example, if the expression is invalid, you will see the following log statements in the fcmdb.push.all.log or fcmdb.push.mapping.log:

2014-08-14 14:07:56,974 [JobExecuterWorker-0:DS_ga_test] TRACE - >> Execution of is-valid expression [1 == 2] = [false]
                    
2014-08-14 14:07:56,974 [JobExecuterWorker-0:DS_ga_test] DEBUG - >> Ignoring invalid property [description] from target entity [Root]

And, if the expression is valid you will simply see:

2014-08-14 14:06:39,660 [JobExecuterWorker-0:DS_ga_test] TRACE - >> Execution of is-valid expression [1 == 1] = [true]

1. Open the icon-related mapping file for the adapter.

   For example, for AM Generic Adapter, open the am-entity-config.xml file.

   For Service Manager adapter, open the icon.properties file.

2. Locate the icon type tag for the CIT of your interest in the mapping file.

   For example, for AM Generic Adapter, it is icon-type.

3. Modify the value for icon type tag with a UCMDB icon value as needed.

   For available UCMDB icons, check Modeling > CI Type Manager > Icon tab.

4. Click Save.

5. Open a desired mapping file, click the Refresh External Class Model button, the icons should be updated.

To do so,

1. Go to Administration > Infrastructure Settings Manager.
2. In the Categories pane, select GUI Settings.
3. In the Name column, locate the Switch between external and local tree panels in the integration mapping tool setting.

4. In the Value column, click the value for the setting you selected, and then choose a value from the drop-down list.

   The default value for this setting is False.

5. Click Save .

   The change takes effect immediately.

You can search for a CI type or an attribute in both of the Local Query, External Class Model, and their Attributes panes the same way as you do in the Script pane.

You can use * as a wildcard character to search inside the text.

To remove a target_entity or target_mapping tag from the mapping file, select the desired mapping element, and click Remove Node .

To remove the entire mapping, select any tag in the Visual Mapping pane and click Clear Entire Mapping .

To revert to the last saved change, click Revert Changes .

Click Validate Mapping File to validate the changes you just made to the mapping file.

1. Open an existing mapping file using the Visual Mapping tool.

   The external tree is populated with a class model.

2. In the External Class Model pane, select a node.

3. Create and synchronize a CI type.

   1. Click Add New CI Type to External Class Model in the toolbar for the External Class Model pane.

      The Add New CI Type to External Class Model dialog box opens, comprising of general section and metadata section.

      The fields in the metadata section are populated dynamically as specified in the external system (passed through the adapter).

      Note: If you already selected a CIT before you click Add New CI Type to External Class Model , the new CIT is created as a child CIT of the selected node; If no CIT is selected, the new CIT is created as a root CIT.

   2. Define the following standard properties for the new CI type:

      • Name. Specify the name for the new CI type.
      • Description. (Optional) Detailed description of the CI type.

   3. Click OK.

      The new CIT synchronization is triggered and the save operation runs as a background task.

      Until the status of the save operation is confirmed, the newly created CIT appears as greyed out in the external tree.

      After the save is successful, the CIT turns into a selectable tree node, and the node can be further used in mappings and drag and drop scenarios.

      In case the save operation failed, the CIT will not appear in the external tree anymore, and an error notification appears at the top of the Visual Mapping pane.

4. Create and synchronize an attribute.

   You can similarly create new attributes for a selected CIT and synchronize the change to the external system. To do so,

   1. In the External Class Model Attributes pane, click Add New Attribute to Selected External Node on the toolbar.

      The Add New Attribute dialog box that opens.

      There is no metadata section in this dialog box.

   2. Define the following properties for the new attribute:

      • Name. Specify the name for an attribute property.
      • Display Name. Specify the display name for an attribute property.
      • Description. (Optional) Detailed description of the attribute property.
      • Type. Select a value from the drop-down list as type of the attribute property in database.

   3. Click OK.

      The new attribute synchronization is triggered and the save operation runs as a background task.

      Until the status of the save operation is confirmed, the newly created attribute appears as grayed out in the external attributes table.

      After the save is successful, the attribute turns into a selectable attribute entry, and the attribute can be further used in mappings and drag and drop scenarios.

      In case the save operation failed, the attribute will not appear in the external attributes table anymore, and an error notification appears at the top of the Visual Mapping pane.