GRLoader XML

This article contains the following topics:
casm172
This article contains the following topics:
GRLoader requires XML document input that consists of a document header followed by enclosing <GRLoader> XML elements tags with one or more <ci> tags (for CI definitions) or <relation> tags (for relationships).
Specify the XML document header as follows:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
Update the encoding attribute as needed to handle the appropriate character encoding requirements. For example, specify “ISO-8859-1” to handle special Norwegian characters.
Example: Format a GRLoader XML File
The following template presents the format for a GRLoader XML file:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GRLoader> <ci> [define a CI: common and family-specific attributes, versioning, reconciliation, MDR] </ci> [repeat as necessary for each CI] <relation> <type>relationship_type</type> <delete_flag>active_state</delete_flag> <provider> <name>resource name</name> <serial_number>serial number</serial_number> <system_name>host name</system_name> <asset_num>resource tag</asset_num> <mac_address>mac address</mac_address> <dns_name>dns name</dns_name> <id>ci_uuid</id> </provider> <dependent> <name>resource name</name> <serial_number>serial number</serial_number> <system_name>host name</system_name> <asset_num>resource tag</asset_num> <mac_address>mac address</mac_address> <dns_name>dns name</dns_name> <id>ci_uuid</id> </dependent> </relation> [repeat as necessary for each relationship] </GRLoader>
XML Content The CI Tag
GRLoader uses the CI XML definition to load a CIs attribute values and relationships. The CI definition must include a minimum set of required attributes to be created or updated by using
<ci>
XML element tags.
You define the XML for a CI by specifying values for the following attributes:
  • Class identification (required)
  • Reconciliation attributes (required)
  • Common attributes
  • Family-specific attributes
  • MDR identification attributes
  • Versioning attributes
The CI Tag Family and Class Identification
Class identification must be specified for each CI to associate the proper family and class with the CI.
Specify the family and class attributes using the following XML tags:
  • <family>
    (Optional) Specifies a collection of CIs that have similar attributes.
  • <class>
    (Required) Specifies a subset of CIs within a family.
If GRLoader cannot find family or class, the CI is not created or updated.
Example: Identify a CI by Family and Class
The following example shows a CI named ServerCI that is identified by the family
Hardware.Server and class
Windows.
<ci> <name>ServerCI</name> <family>Hardware.Server</family> <class>Windows</class> ... </ci>
The CI Tag Reconciliation Attributes (Required)
One or more reconciliation attributes are required when creating, updating, or referencing a CI. GRLoader uses these attributes to uniquely identify the CI to be created or updated. Reconciliation attributes are also used to identify a provider/dependent relationship between two CIs.
Specify the reconciliation attributes using the following XML element tags:
  • <name> -- The name of the CI or resource (required when creating the CI for first time)
  • <serial_number> -- The manufacture unique identifier
  • <asset_num> -- Alternate resource identifier, for example, an alternate ID located on sticker placed on computer
  • <system_name> -- Computer name (hardware only)
  • <dns_name> -- The name by which this device is known in the domain name server
  • <mac_address> -- MAC address. (hardware only)
  • <id> -- UUID of the CI, used for direct updates when ID is known
The name attribute is required when creating a CI for the first time. If GRLoader cannot resolve the specified reconciliation attributes, an existing CI is not updated. Reconciliation attributes are special purpose Common Attributes that are used for identification purposes.
Example: Identify a CI When Creating or Updating It
In the following example, the CI definition uses name, serial_number, dns_name, mac_address and system_name to uniquely identify the CI when creating or updating it.
<ci> <name>ServerCI</name> <serial_number>HMVV081</serial_number> <dns_name>serverci.myco.com</dns_name> <mac_address>00:12:3F:48:F0:95</mac_address> <system_name>ServerCI</system_name> ... </ci>
The CI Tag Common Attributes
In general, common attributes are attributes that can be used in any CMDB family or class. The XML element tag used for the attribute is the same as the attribute object name. The attribute value depends on its type, which can be a constant or an SREL value that indicates a foreign key reference to another table.
Example: Specify Common Attributes
In the following example, the CI definition named ServerCI specifies the following common attributes: manufacturer, model, and alarm_id (IP Address). The ServerCI name is also a common attribute.
<ci> <name>ServerCI</name> ... <manufacturer>Dell Inc.</manufacturer> <model>OptiPlex GX280</model> <alarm_id>130.200.19.220</alarm_id> ... </ci>
The CI Tag Family-Specific Attributes
Class attributes are unique to a specific CI family or class. The XML element tag used for the class attribute is the same as the attribute object name found in the family/class specific tables.
Example: Specify Family-Specific Attributes
In the following example, the CI definition named ServerCI specifies the attributes specific to the
Hardware.Server family that include bios_ver, cd_rom_type, hard_drive_capacity, and so on.
<ci> <name>ServerCI</name> ... <bios_ver>A04</bios_ver> <cd_rom_type>DVD+-RW DVD8701</cd_rom_type> <hard_drive_capacity>90 MB</hard_drive_capacity> <number_net_card>3</number_net_card> <number_proc_inst>1</number_proc_inst> <phys_mem>2048 MB</phys_mem> <proc_speed>2793 MHz</proc_speed> <swap_size>4959 MB</swap_size> ... </ci>
The CI Tag MDR Identification
A management data repository (MDR) identifies the data provider for a CI and how the CIs maps back to the corresponding MDR.
CA SDM uses MDR information to perform the following tasks:
  • Launch in context from the CI log directly to the MDR data provider.
  • Tracks CI attribute changes back to the source MDR.
  • Detects when more than one MDR updates a CI attribute. This situation occurs when multiple MDRs contribute data independently to a CI definition.
  • Identifies which MDR acts as the authoritative source.
For more information about MDRs, see this topic.
Use the following XML element tags to specify MDR attributes:
  • <mdr_class>
    Specifies the MDR class to group MDRs that CA SDM processed similarly.
  • <mdr_name>
    Specifies the MDR name that an MDR uses to reference itself. Verify that the mdr_name and mdr_class value combination is unique within your enterprise.
  • <federated_asset_id>
    Specifies the Federated asset ID that indicates the unique identifier of an MDR for a CI.
If GRLoader cannot resolve the specified mdr_class and mdr_name to an existing MDR, GRLoader does not import the CI. A CI with no associated federated_asset_id mapping is not federated.
Example: Identify a CI in the MDR
In the following example, the CI definition named ServerCI specifies mdr_class and mdr_name to uniquely identify the MDR and federated asset id, and thus identify the CI in the MDR.
CA SDM uses the mdr_class string value
Cohesion
when federating data from the [assign the value for acm in your book] product.
<ci> <name>ServerCI</name> ... <federated_asset_id>1001118</federated_asset_id> <mdr_class>Cohesion</mdr_class> <mdr_name>CohesionServer</mdr_name> ... </ci>
The CI Tag Versioning Attributes
You can use GRLoader to set versioning attributes for a CI.
For more information about versioning, see the Versioning section.
Specify the Versioning attributes using the following XML element tags:
  • <milestone>
    Specifies the label associated with that milestone that displays in the Versioning tab.
  • <standard_ci>
    Specifies the name of the standard CI to use for baseline comparisons in the Versioning tab.
The CI that you specified for the standard_ci attribute must already exist in the CMDB or be specified before you specify the CI definition in the XML file. The milestone generated records the state of the CI at the time that GRLoader executes.
Example: Specify Baseline Comparisons
In the following example, the CI definition named ServerCI specifies the standard CI named
standard server config for baseline comparisons with ServerCI (the focal CI). This example assumes that the standard CI already exists in CA SDM. In addition, a milestone named Fiscal year end 2008 is also created to preserve the state of the CI at the time that GRLoader imports the XML.
<ci> <name>ServerCI</name> <class>Server</class> <standard_ci>standard server config</standard_ci> <milestone>Fiscal year end 2008</milestone> ... </ci>
XML Content The Relation Tag
GRLoader can create or update relationships between configuration items by using the <relation> XML element tag. Relationships are many-to-many, and the relationship type specifies how two provider/dependent configuration items relate to one another in CMDB.
Specify the relation attributes using the following XML element tags:
  • <type>
    (Optional) Specifies the name of the relationship type.
  • <delete_flag>
    Designates a relationship as inactive or active. Specify 1 (one), yes, or true to make the relationship inactive. Specify 0 (zero), no or false to make the relationship active again. Setting the delete_flag to true leaves the existing relationship intact but marks it as inactive.
  • <provider>
    (Required) Identifies the provider CI for the relationship, which contains one or more of the CI reconciliation attributes.
  • <dependent>
    (Required) Identifies the dependent CI for the relationship, which contains one or more of the CI reconciliation attributes.
If GRLoader cannot find a specified type, provider CI, or dependent CI, the relationship is created or updated.
Example: Define a Relationship Between CIs
The following example defines a relationship between the CIs named ServerCI (provider) and
ServerCI|NetworkAdaptor-0 (dependent). The relationship type is contains. The example assumes that both CIs have already been defined in the CMDB or are specified preceding the relationship definition in an XML file. In addition, both the provider and dependent CIs must match all reconciliation attributes for the relationship to be created.
<relation> <type>contains</type> <provider> <name>ServerCI</name> <serial_number>HMVV081</serial_number> <dns_name>serverci.myco.com</dns_name> <mac_address>00:12:3F:48:F0:95</mac_address> <system_name>ServerCi</system_name> </provider> <dependent> <name>ServerCI|NetworkAdaptor-0</name> </dependent> </relation>
XML Content Special Values
Special-purpose XML attributes can modify how a CI value is set or updated when imported by GRLoader. You can use these attributes to perform special processing or formatting when setting the value; for example, to format a date value or use the result of a lookup.
Examples of special XML values include the following ones:
  • lookup
    Specifies a CI by an attribute other than combo_name (lastname, firstname, middle). Examples include: userid,
  • update_if_null
    Specifies the update_if_null option for GRLoader to use to distinguish between values that are blank and those which are not supplied in the XML. By default, update_if_null is set to "", which means that blank or missing values are ignored by GRLoader.
    The following attribute descriptions for serial number are equivalent:
    <serial_number></serial_number> <serial_number/> <serial_number update_if_null="">
    If you want to remove the serial number from a CI that has one, the previous XML does
    not
    work, because GRLoader ignores blank or missing values. Instead, code xml for the serial number as follows:
    <serial_number update_if_null="true"></serial_number>
    This syntax always updates the attribute, even if the value is blank or missing.
  • dateformat=[utc | localtime]
    Sets the
    dateformat
    attribute for the date field to be either “utc” or “localtime”. Required when the format of the date is in UNIX Time Code (UTC) format. If dateformat is not set, the default is “localtime".
Date Formats
CMDB supports the following localtime date formats:
  • yyyy.mm.dd
  • yyyy.mm.dd hh:mm:ss
If the value does not match either of these formats, the parser tries to resolve the date as a UTC time. If the date format is not UTC, CMDB uses the system locale setting: for US English, the 12-hour format of “mm/dd/yyyy” or “mm/dd/yyyy hh:mm:ss
a
” where
a
specifies either AM or PM).
Contact and Other Lookup Fields
The Contact object combines first name, middle initial, and last name. The object has the following format:
<resource_contact>Lastname, Firstname MiddleInitial</resource_contact>
If you want to use a different field for a lookup field, you can supply a lookup attribute. For example, if you wanted to look up John Q. Doe by userid, use the following entry:
<resource_contact lookup="userid">doejo04</resource_contact>
Fields Validated Against Data in Existing Tables (SREL)
Common attributes accept only a specific set of values that must be defined in related tables in CMDB. These attributes can also have additional restrictions and exceptions that must be met for the assignment to occur. For example, a class attribute specified in XML must match one of the existing class names (CMDB default or user-defined). Otherwise, the CI is not created or updated. In addition, the value cannot be set to null, and the class must be Active for the assignment to occur.
The following fields validate data against data in existing tables:
  • audit_userid
  • bm_rep
  • bm_status
  • class
  • company_bought_for_uuid
  • contact_1
  • contact_2
  • contact_3
  • delete_flag
  • department
  • expense_code
  • family
  • location
  • manufacturer
  • model
  • operating_system
  • org_bought_for_uuid
  • priority
  • repair_org
  • resource_contact
  • resource_owner_uuid
  • service_org
  • service_type
  • status
  • supplier
  • vendor_repair
  • vendor_restore
XML Input
When importing CI data, format the data in a supported format, such as XML or a spreadsheet (XLS or XLSX).
Consider the following XML format example:
XML Document
Notes
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GRLoader>
These headers are required.
<ci>
Include zero or more <ci> nodes to define the CIs.
<name>value</name> <mac_address>value</mac_address> <dns_name>value</dns_name> <asset_num>value</asset_num> <serial_number>value</serial_number> <system_name>value</system_name>
These six characteristics uniquely identify a CI in a CI or Relations definition. At least one must be specified.
<class>value</class> <family>value</family> <manufacturer>value</manufacturer> <model>value</model>
These four values determine the class and family of a CI. You specify either (class) or (manufacturer/model).
<mem_capacity>value</mem_capacity> <number_net_card>value </number_net_card> <phys_mem>value</phys_mem_update> <proc_speed>value</proc_speed> <proc_type>value</proc_type> <server_type>value</server_type> </ci>
Family-specific values. Zero or more family-specific values can be provided when defining a CI.
<relation> <type>relation_type</type>
Include zero or more <relation> nodes to define relationships. Specify the relationship type.
<provider> <name>value</name> <mac_address>value</mac_address> <dns_name>value</dns_name> <asset_num>value</asset_num> <serial_number>value</serial_number> </provider>
Identify the provider CI with at least one attribute.
<dependent> <name>value</name> <mac_address>value</mac_address> <dns_name>value</dns_name> <asset_num>value</asset_num> <serial_number>value</serial_number> </dependent> </relation>
Identify the dependent CI with at least one attribute.
</GRLoader>
 
Example: XML Input
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GRLoader> <ci> <name>Host1</name> <class>Server</class> </ci> <ci> <name>Host2</name> <class>Server</class> </ci> <relation> <type>connects to</type> <provider> <name>host1</name> </provider> <dependent> <name>host2</name> </dependent> </relation> </GRLoader>
MAC Address Normalization
Previous releases of GRLoader normalized the MAC address of CIs by removing the ":" and "-" delimiters from the MAC address. This normalization resulted in a MAC address of: aa:bb:cc:dd:ee storing as aabbccddee.
Consider the following MAC address behavior:
  • The default is no MAC address normalization.
  • CIs created with no normalization in CMDB reconcile with CIs that were created without normalization in CMDB r11.x.
  • Invalid MAC addresses are treated as simple strings and are stored unmodified.
The following GRLoader parameters let you enable or disable MAC normalization:
  • -mn
    Removes the ":" and "-" delimiters from MAC addresses (MAC normalization).
  • -nomn
    Does not remove the ":" and "-" delimiters from MAC addresses.
    Installing an earlier version if CMDB enables MAC address normalization automatically. You can override normalization by using the
    -nomn
    parameter
Because options are processed sequentially on the command line, the order of the options is important in the syntax.