Use > Collecting Topology Data > Topology Discovery Syntax

Topology Discovery Syntax

The XML file that the discovery script creates and to which the mapping rules are applied must use the Operations Connector topology discovery syntax described in this section.

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.

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 ClosedRTSM (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>