Topology Discovery Syntax

Configuration Item XML Schema Definition (XSD)

Your discovery script must output XML that conforms to the following schema:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Service">
      <xs:complexType>
         <xs:choice maxOccurs="unbounded">
            <xs:element ref="NewInstance" />
            <xs:element ref="NewRelationship" />
         </xs:choice>
      </xs:complexType>
      <xs:key name="InstanceKey">
         <xs:selector xpath="NewInstance">
         </xs:selector>
         <xs:field xpath="Key"></xs:field>
      </xs:key>
      <xs:keyref refer="InstanceKey" name="InstanceKeyRef">
         <xs:selector xpath="NewInstance">
         </xs:selector>
         <xs:field xpath="@ref"></xs:field>
      </xs:keyref>
      <xs:keyref refer="InstanceKey" name="InstanceRef">
         <xs:selector xpath="NewRelationship/*/Instance">
         </xs:selector>
         <xs:field xpath="@ref"></xs:field>
      </xs:keyref>
   </xs:element>
   <xs:element name="NewInstance" type="InstanceType" />
   <xs:complexType name="InstanceType">
      <xs:sequence>
         <xs:element ref="Std" />
         <xs:element ref="Virtual" minOccurs="0" />
         <xs:element ref="Key" />
         <xs:element ref="Attributes" />
      </xs:sequence>
      <xs:attribute name="ref" type="xs:string" use="required" />
   </xs:complexType>
   <xs:element name="NewRelationship" type="RelationType" />
   <xs:complexType name="RelationType">
      <xs:sequence>
         <xs:element ref="Parent" />
         <xs:element ref="GenericRelations" minOccurs="0" />
      </xs:sequence>
   </xs:complexType>
   <xs:element name="Std">
      <xs:simpleType>
         <xs:restriction base="xs:string">
            <xs:enumeration value="DiscoveredElement" />
         </xs:restriction>
      </xs:simpleType>
   </xs:element>
   <xs:element name="Virtual">
      <xs:complexType />
   </xs:element>
   <xs:element name="Key" type="xs:string" />
   <xs:element name="Attributes">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="Attribute" maxOccurs="unbounded" />
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="Attribute">
      <xs:complexType>
         <xs:attribute name="value" type="xs:string" use="required" />
         <xs:attribute name="name" type="xs:string" use="required" />
      </xs:complexType>
   </xs:element>
   <xs:element name="Parent">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="Instance" />
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="GenericRelations" type="RelationsList" />
   <xs:complexType name="RelationsList">
      <xs:sequence>
         <xs:element name="Relations" maxOccurs="unbounded">
            <xs:complexType>
               <xs:attribute name="type" type="xs:string" use="required" />
               <xs:sequence>
                  <xs:element ref="Instance" maxOccurs="unbounded" />
               </xs:sequence>
            </xs:complexType>
         </xs:element>
      </xs:sequence>
   </xs:complexType>
   <xs:element name="Instance">
      <xs:complexType>
         <xs:attribute name="ref" type="xs:string" use="required" />
      </xs:complexType>
   </xs:element>
</xs:schema>

Configuration Item XML Element Description

The following table describes the elements that the XML document can contain.

Element	Description
NewInstance	Represents a discovered CI. You must add a `ref` attribute, which must match the unique CI ID that you specify in the Key element. You can then use this reference in Instance elements in the current XML document if you want to create or delete relationships.
DeleteInstance	Represents a CI that you want to delete immediately. The agent automatically deletes previously discovered CIs from the agent repository if your discovery script runs five times (by default) without including the CI as a NewInstance in the XML document. Note: You can control how often the discovery script must run before a missing CI is automatically deleted by changing the agent parameter `INSTANCE_DELETION_THRESHOLD` in the `agtrep` namespace. However, if you specify this element, the agent deletes the CI immediately and publishes the change to the RTSM (Run-time Service Model).
NewRelationship	Defines a new relationship between CIs. This element must contain exactly one Parent element and can contain one or more GenericRelations elements.
DeleteRelationship	Defines relationships that you want to delete. This element must contain exactly one Parent element and can contain one or more GenericRelations elements.
Std	Must contain the string `DiscoveredElement`.
Virtual	Include this element if the CI is virtual. A virtual CI is abstract and does not exist on any node CI. Omit this element if the CI is hosted on a node CI.
Key	Contains the full CI ID for this CI, which must be unique. You must include this element in all NewInstance elements. You must not specify a NewInstance with the same key in the same XML document.
Attributes	Contains Attribute elements.
Attribute	Each Attribute element has the attributes `name` and `value`. You can also specify a datatype. Attributes with the following names have a special meaning: `hpom_citype` specifies the CI type as stored in the RTSM (for example, `nt`). Attribute names with the prefix `ucmdb_` map directly to CI attributes (for example, `ucmdb_primary_dns_name` maps to the CI attribute `Primary DNS Name`).
Parent	Contains an Instance element, which defines the CI that is the parent of this relationship. The parent instance that you specify must exist in the RTSM and in the agent repository on the Operations Connector server. Therefore, you may need to include a NewInstance element to add the parent to the agent repository, even if the parent already exists in the RTSM.
Instance	Has a `ref` attribute that refers to a NewInstance element in the current XML document.
GenericRelations	Contains one or more Relations elements.
Relations	Has a `type` attribute that refers to the type of relation as stored in the RTSM (for example, `usage`). Contains one or more Instance elements, which refer to the CIs that are related to the specified Parent element. For complex topologies which require a sync package, add the prefix `omrel_`. For example, if the type is `membership` when no sync package is used, it becomes `omrel_membership` with sync packages.

Example Discovery XML

The following example XML creates three CI instances with the IDs myUniqueID1, myUniqueID2, and myUniqueID3. myUniqueID1 is the parent CI, and has a contains relationshipt to myUniqueID2 and myUniqueID3.

Example:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Service>
  <NewInstance ref="myUniqueID1">
    <Key>myUniqueID1</Key>
    <Std>DiscoveredElement</Std>
    <Attributes>
      <Attribute name="myAttribute" value="myAttributeValue" />
      <Attribute name="myAttribute1" value="myAttributeValue1" />
      <Attribute name="myType" value="myTypeValue" />
      <Attribute name="title" value="myTitle1" />
    </Attributes>
  </NewInstance>
  <NewInstance ref="myUniqueID2">
    <Key>myUniqueID2</Key>
    <Std>DiscoveredElement</Std>
    <Attributes>
      <Attribute name="myAttribute" value="myAttributeValue" />
      <Attribute name="myAttribute1" value="myAttributeValuew" />
      <Attribute name="myType" value="myTypeValue1" />
      <Attribute name="title" value="myTitle2" />
    </Attributes>
  </NewInstance>
  <NewInstance ref="myUniqueID3">
    <Key>myUniqueID3</Key>
    <Std>DiscoveredElement</Std>
    <Attributes>
      <Attribute name="myAttribute" value="myAttributeValue" />
      <Attribute name="myAttribute1" value="myAttributeValuey" />
      <Attribute name="myType" value="myTypeValue2" />
      <Attribute name="title" value="myTitle3" />
    </Attributes>
  </NewInstance>
  <NewRelationship>
    <Parent>
      <Instance ref="myUniqueID1"/>
    </Parent>
    <GenericRelations>
      <Relations type="omrel_contains">
        <Instance ref="myUniqueID2"/>
      </Relations>
      <Relations type="omrel_contains">
        <Instance ref="myUniqueID3"/>
      </Relations>
   </GenericRelations>
  </NewRelationship>
</Service>