Mapping Files for Population Flow

• Query – You can use a ServiceNow query to filter replicated CIs.

  ... 
  <source_ci_type name="cmdb_ci_vcenter_datacenter" query="name=prod"> 
  ...  
  

  For details on creating queries, see http://wiki.servicenow.com/index.php?title=Encoded_Query_Strings#Creating_Encoded_Query_Strings.

• Foreign keys – Sometimes CIs in ServiceNow do not have a relationship defined between them, but one CI keeps the sys_id of another CI in one of its attributes. For example, cmdb_ci_network_adapter has the attribute cmdb_ci, which contains the sys_id of the host where this adapter resides. To handle this situation in the mapping file, use the special __Reference type of link, and provide the name of the attribute with the foreign sys_id

  <link source_link_type="__Reference" reference_attribute="cmdb_ci" target_link_type="composition" 
  source_ci_type_end1="cmdb_ci_unix_server" source_ci_type_end2="cmdb_ci_network_adapter">
       <target_ci_type_end1 name="unix"/>
       <target_ci_type_end2 name="interface"/> 
  </link>  

By using the special __Reference link type, you can split one ServiceNow CI into multiple UCMDB CIs. For example, cmdb_ci_esx_server in ServiceNow should be transformed into a pair ESX -> Hypervisor in UCMDB. To do that, create a mapping file like this:

<?xml version="1.0" encoding="UTF-8"?> 
<integration>
     <info>
         <source name="ServiceNow" versions="" vendor="ServiceNow" />
         <target name="UCMDB" versions="10.x" vendor="HP" />
     </info>
     <targetcis>
         <source_ci_type name="cmdb_ci_esx_server">
             <target_ci_type name="vmware_esx_server">
                 <target_attribute name="name">
                     <map type="direct" source_attribute="name" />
                 </target_attribute>
             </target_ci_type>
         </source_ci_type>
         <source_ci_type name="cmdb_ci_esx_server">
             <target_ci_type name="hypervisor">
                 <target_attribute name="name">
                     <map type="direct" source_attribute="name" />
                 </target_attribute>
                 <target_attribute name="product_name">
                     <map type="const" value="vmware_hypervisor" />
                 </target_attribute>
             </target_ci_type>
         </source_ci_type>
     </targetcis>
     <targetrelations>
         <link source_link_type="__Reference" reference_attribute="sys_id" target_link_type="composition" 
source_ci_type_end1="cmdb_ci_esx_server" source_ci_type_end2="cmdb_ci_esx_server">
             <target_ci_type_end1 name="vmware_esx_server"/>
             <target_ci_type_end2 name="hypervisor"/>
         </link>
     </targetrelations> 
</integration>  

Note that cmdb_ci_esx_server is mapped into two UCMDB CIs: vmware_esx_server and hypervisor. There is a relationship definition, that leverages the __Reference link type and sys_id as a foreign key. This means that when using sys_id as a reference attribute, the CI references itself. This allows you to map cmdb_ci_esx_server to two CIs and create a relationship between them.

• Attribute mapping types:

  • direct – Takes the attribute value of a ServiceNow CI and sets it to a UCMDB CI attribute unchanged.

  • const – Sets a UCMDB attribute to some constant value.

    <source_ci_type name="cmdb_ci_esx_server">
         <target_ci_type name="hypervisor">
             <target_attribute name="name">
                 <map type="direct" source_attribute="name" />
             </target_attribute>
             <target_attribute name="product_name">
                 <map type="const" value="vmware_hypervisor" />
             </target_attribute>
         </target_ci_type> 
    </source_ci_type>

• Link failure policy – Sometimes relationships are mandatory and you do not want certain CIs to enter UCMDB unless they have required relationships. To enforce this behavior, use failure_policy to define what to do, such as when a relationship cannot be created between a particular pair of CIs. Possible values are exclude_end1, exclude_end2, exclude_both and ignore (this is the default).

  <link source_link_type="Defines resources for::Gets resources from" target_link_type="composition" 
  source_ci_type_end2="cmdb_ci_vcenter_cluster" source_ci_type_end1="cmdb_ci_esx_resource_pool" 
  failure_policy="exclude_end1" direction="reverse">
       <target_ci_type_end1 name="vmware_resource_pool"/>
       <target_ci_type_end2 name="vmware_cluster"/> 
  </link>

• Link direction – If you need relationship to go into the opposite direction than it is defined in ServiceNow, you can use the direction="reverse" attribute on a link mapping definition. Note that target_ci_type_end1 and target_ci_type_end2 should not be switched when this attribute is applied (see the previous example).

• Validators – Use validators when it is necessary to validate an attribute's values before sending topology to UCMDB. The following example filters out all cmdb_ci_ip_address instances where the attribute name is not actually, a valid IP address.

  <target_attribute name="ip_netmask">
           <map type="direct" source_attribute="netmask" />
               <validators>
                   <validator>validators.mandatory</validator>
                   <validator>netutils.isValidIp</validator>
               </validators>
  </target_attribute> 
  

  A validator's value is actually any Python function that returns a Boolean result. You can either use existing functions for validation, such as netutils.isValidMac, or write your own validation functions to get the most flexibility. The package contains a Jython script called validators.py, where you can add your custom validation functions.