The Groovy Traveler

Access the TQL query results in the following manner:

• Root[attr] returns the attribute attr of the Root element.

• Root.Query_Element_Name returns a list of the CI instances named in the TQL Query_Element_Name and that are linked to the current root CI.

• Root.Query_Element_Name[2][attr] returns the attribute attr of the third Query_Element_Name that is linked to the current root CI.

• Root.Query_Element_Name*.getAt(attr) returns a list of the attributes attr of the CI instances named Query_Element_Name in the TQL and that are linked to the current root CI.

There are additional attributes that can be accessed by the groovy traveler:

• cmdb_id – returns the UCMDB ID of the CI or relationship as a string.

• external_cmdb_id – returns the external ID of the CI or relationship as a string.

• Element_type – returns the element type of the CI or relationship as a string.

The import tag:

<import>

<scriptFile path="mappings.scripts.PushFunctions"/>

</import>

This means that we are declaring an import for all the groovy scripts in the mapping file. In this example, PushFunctions is a groovy script file that contains some static functions, and we can access them during the mapping (i.e. value=” PushFunctions.foo()”)

source_instance_type

The mapping is done per TQL, the query-name value is the related TQL of the current mapping. The ‘*’ means that this mapping file is associated with all TQL queries beginning with the prefix: Node Push.

<source_instance_type query-name="Node Push*" root-element-name="Root">

The source_instance_type tag designates the root element we are mapping.

root-element-name should be exactly the same as the name of the root in the TQL.

target_entity

This tag is used for the creation of the RTN.

The name attribute represents the target_entity name: name=Computer

The is-valid attribute is a Boolean value that is calculated during the mapping, and determines if the current target_ci is valid. Invalid target_entities are not added to the RTN. In this example, we do not want to create a target_entity instance for which the root_iscandidatefordeletion attribute in UCMDB is true.

The target_entity can have variables that are calculated during the mapping:

<variable name="vSerialNo" datatype="STRING" value="Root['serial_number']"/>

The variable vSerialNo gets the value of the serial_number of the current root.

The attribute of the RTN is created by the target_mapping tag. The result of the execution of the groovy script in the value field,is assigned to the RTN attribute.

<target_mapping name="SerialNo" datatype="STRING" value="vSerialNo"/>

SerialNo assigns the value of the variable vSerialNo.

It is possible to define a target_entity as child of another target_entity as follows:

<target_entity name="Portfolio">

<variable name="vSerialNo" datatype="STRING" value="Root['global_id']"/>

<target_mapping name="CMDBId" datatype="STRING" value="globalId"/>

<target_entity name=Asset">

<target_mapping name="SerialNo" datatype="STRING" value="vSerialNo"/>

</target_entity>

</target_entity>

The RTN Portfolio will have child RTN named Asset.

for-each-source-entity

This tag lists the specific CIs of the root instance. It has the following fields:

• source-entities=" " – the list of CIs for which a target CI is created. This list is defined by the groovy traveler in the Root.IpAddress field.

• count-index=" " – a variable that holds the index of the CI in the current iteration of the loop.

• var-name=" " – the name of the CI in the current iteration of the loop.

Let’s modify our example mapping file:

The RTN list that will build according to this mapping file will look like this:

dynamic_mapping

This tag adds the ability to create a mapping of data from the target data store during the creation of the RTN structure.

Example: Assume that the target is a database with a table named Computer that has an id column and a name column that is correlated to Node.name in UCMDB. Both columns are unique. The database also has a table named IP that has a referenced key to the parentID in the Computer table. The ‘dynamic_mapping’ can create a map that stores the name and id as <name,id>. Based on this map, the Adapter can match ids with computers and can push the correct value to the parentID attribute in the IP table. You can use this map to assign a value to the parentID attribute while creating the RTN.

The mapping is determined by the map_property. The dynamic_mapping is executed once for each chunk.

<dynamic_mapping name="IdByName " keys-unique="true"> 

The name attribute represents the name of the map. The keys-unique attribute indicates if the keys are unique (each key is mapped to one value, or to a set of values).

The name of the map in this example is IdByName and it has unique keys. In order to access the map in the script, execute the following command:

DynamicMapHolder.getMap(‘IdByName’)

It returns a reference to that map.

The map_property tag creates the property on which the mapping is based.

Example:

<map_property property-name="SQLQuery" datatype="STRING"

property-value="SELECT name, id FROM Computer"/>

In this example the name of the property is SQLQuery and its value is an SQL statement that creates the map. The implementation of the methods retrieveUniqueMapping and retrieveNonUniqueMapping for the PushConnector interface will determine the actual content of the returned map.

Global Variables

The following global variables are accessible to the groovy script in the mapping file:

• Topology – Type: Topology. An instance of the topology of the current chunk.

• QueryDefinition - Type: QueryDefinition. An instance of the query definition of the current TQL.

• OutputCI – Type: ResultTreeNode. The RTN of the root element in the current tree mapping.

• ClassModel – Type: ClassModel. An instance of the class model.

• CustomerInformation – Type: CustomerInformation. Information about the customer running the job.

• Logger – Type: DataAdapterLogger. This logger is available in the adapter for writing logs to the UCMDB logging framework.