Discovery Rules Syntax

This section describes the syntax of discovery rules. Discovery rules are supplied in an XML file. Some examples are presented here, and detailed descriptions explaining the syntax in these examples follow.

Example 1

The following rule sets attribute vendor to hewlett_packard_co for CIs with the discovered_model attribute equal to HP2140.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rules:normalization-rules name="My rules" xmlns:rules="http://www.hp.com/ucmdb/1-0-0/NormalizationRules">

<rules:normalization-rule ci-type="node" id="1">

<rule-input>

<attribute name="discovered_model" value="HP 2140" compare-type="equals"/>

</rule-input>

<rule-output>

<attribute name="vendor">

<value>hewlett_packard_co</value>

</attribute>

</rule-output>

</rules:normalization-rule>

</rules:normalization-rules>

Example 2

The following rule appends desktop to the node_role attribute list when a discovered node CI is connected to interface whose mac_address starts with 0020C0.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rules:normalization-rules name="My rules" xmlns:rules="http://www.hp.com/ucmdb/1-0-0/NormalizationRules">

<rules:normalization-rule ci-type="node" id="3481">

<rule-input>

<connected-ci link-type="composition" direction="forward" end-type="interface">

<connected-ci-attribute name="mac_address" value="0020C0" compare-type="starts-with"/>

</connected-ci>

</rule-input>

<rule-output>

<attribute name="node_role">

<values>

<add>desktop</add>

</values>

</attribute>

</rule-output>

</rules:normalization-rule>

</rules:normalization-rules>

Example 3

The following example sets the values of os_description, os_vendor, os_family attributes and appends desktop and nt to the node_rule attribute when a discovered node CI has the discovered_os_name starting with Windows 2000 Professional.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rules:normalization-rules name="My rules" xmlns:rules="http://www.hp.com/ucmdb/1-0-0/NormalizationRules">

<rules:normalization-rule ci-type="node" id="2">

<rule-input>

<attribute name="discovered_os_name" value="Windows 2000 Professional" compare-type="starts-with"/>

</rule-input>

<rule-output>

<attribute name="os_description">

<value>windows_2000_professional</value>

</attribute>

<attribute name="os_vendor">

<value>microsoft_corp</value>

</attribute>

<attribute name="os_family">

<value>windows</value>

</attribute>

<attribute name="node_role">

<values>

<add>desktop</add>

</values>

</attribute>

<class-type>nt</class-type>

</rule-output>

</rules:normalization-rule>

</rules:normalization-rules>

Example 4 (link rules)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rules:normalization-rules name="My rules" xmlns:rules="http://www.hp.com/ucmdb/1-0-0/NormalizationRules">

<rules:normalization-rule id="2909" ci-type="containment">

    <link-rule-input>

         <attribute name="name" value="MyName" compare-type="starts-with"/>

          <end1 ci-type="node">

             <attribute name="description" value="MyDescription" compare-type="starts-with"/>

          </end1>

         <end2 ci-type="ip_address">

              <attribute name="name" value="1.1.1.1" compare-type="starts-with"/>

         </end2>

    </link-rule-input>

    <rule-output>

         <attribute name="description">

              <value>HP StoreOnce B6000</value>

        </attribute>

     </rule-output>

</rules:normalization-rule>

</rules:normalization-rules>

Explanation of Examples

• Element: <normalization-rules>

  Description: Represents a set of discovery rules. It is the top element in the XML file.

  Attributes:

  • Description (optional)
  • Name (required): a unique name of the rule set in the XML file.

  Inner elements:

  • <normalization-rule>

• Element: <normalization-rule>

  Description: This element represents a single discovery rule.

  Attributes:

  • id (required): This ID must be unique within the scope of the XML file. In the first example above, id=1. In the second example, id=3481.
  • ci-type (required): the type of CI that the rule is applied to. In both examples above, ci-type=node.

  Inner elements:

  • <rule-input>
  • <link-rule-input>
  • <rule-output> (required)

  Note One or the other of the <rule-input> or <link-rule-input> elements must appear in the file, but not both.

• Element: <rule-input>

  Description: Defines conditions on CI attributes and on attributes of connected CI(s), used for matching between a discovered CI and the rule. For example, if you have the following rule input:

  <rule-input>

  <attribute name="discovered_model" value="HP 2140" compare-type="equals"/>

  </rule-input>

  this rule would match a CI with an attribute discovered_model = HP 2140.

  Inner elements:

  • <attribute> (optional)
  • <connected-ci> (optional)

  Note <rule-input> must have one of the inner elements above.

• Element: <attribute>

  Description: Defines a condition on a CI attribute.

  Attributes:

  • name (required): The name of the discovered CI attribute examined by the discovery rules engine.
  • value (required): The value that the discovered CI attribute has to match.

  • compare-type (required): Defines the kind of match comparison applied by the rule. It must be one of the following options:

    1. equals: The value of the discovered attribute is equal to the value in the rule.

    2. starts-with: The value of the discovered attribute starts-with the value in the rule.

    3. ends-with: The value of the discovered attribute ends with the value in the rule.

    4. contains: The value of the discovered attribute contains the value in the rule.

    5. regexp: The value of the discovered attribute matches a given regular expression in the rule.

    6. oid-starts-with: Either the value of the discovered attribute is equal to the value provided in the rule or it starts with the concatenation of the rule value and the dot (.) character.

       For example, if you have the following rule:

       <attribute name="sys_object_id" value=".1.3.6.1.4.1.42" compare-type="oid-starts-with"/>

       It is interpreted as either:

       • value of "sys_object_id" is equal to ".1.3.6.1.4.1.42"

       or

       • value of "sys_object_id" starts with ".1.3.6.1.4.1.42."

       This means that the following values would match this rule:

       • ".1.3.6.1.4.1.42"

       • ".1.3.6.1.4.1.42.1"

       but this value would not match the rule:

       • ".1.3.6.1.4.1.421"

• Element: <connected-ci>

  Description: Defines conditions on a connected CI.

  Attributes:

  • link-type (required): The type of relationship between the discovered CI and the connected CI.
  • direction (required): The relationship direction; which is either "forward" or "backward".
  • end-type (required): The type of the connected CI.

  Inner elements:

  • <connected-ci-attribute>

• Element: <connected-ci-attribute>

  Description: Defines a condition on a connected CI attribute. Similar to the <attribute> element (described above) that defines conditions on the attribute of a CI, the <connected-ci-attribute> refers to an attribute of a connected CI. This element has the same structure as the <attribute> element.

• Element: <link-rule-input>

  Description: Defines conditions on link attributes and on attributes of its ends, used for matching between a discovered link and the rule.

  Inner elements:

  • <attribute> - Zero or more attribute conditions on the link. The same as the previous <attribute> element.

  • <end1> (required)
  • <end2> (required)

• Element: <end1>

  Description: Defines a condition on the first end of the link.

  Attributes:

  • ci-type (required): the type of the end CI

• Element: <end2>

  Description: Defines a condition on the second end of the link.

  Attributes:

  • ci-type (required): the type of the end CI

  Inner elements (for both end1 and end2):

  • <attribute> (optional): Zero or more attribute conditions on the end. The same structure as other<attribute> elements.

• Element: <rule-output>

  Description: Defines the output values set by the rule in the case of a match. It also can set the type of the discovered CI. The rule output contains a list of attributes. Each attribute contains one or more values, and the rule engine sets these values. The following is an example of rule output:

  <rule-output>

  <attribute name="vendor">

  <value>hewlett_packard_co</value>

  </attribute>

  </rule-output>

  In the output above, the attribute “vendor” has one value, and the rule engine sets this value to “hewlett_packard_co”.

  Sometimes, an attribute has a string_list type. In this case, the rule output can add a new value to the list, as shown in the following example:

  <rule-output>

  <attribute name="node_role">

  <values>

  <add>desktop</add>

  </values>

  </attribute>

  </rule-output>

  In the example above, the value desktop is added to the list of node_role values.

  Rule output can also set a CI type, as shown in the following example:

  <rule-output>

  <class-type>nt</class-type>

  </rule-output>

  Inner elements:

  • <class-type> (optional)
  • <attribute> (optional)

  Note <rule-output> must have one of the inner elements above.

• Element: <class-type>

  Description: When used, defines the new type of the discovered CI.

• Element: <attribute>

  Description: Defines the attribute to be set in the case of a match.

  Attributes:

  • name (required): The name of the CI attribute that is set by this rule.

  Inner Elements:

  • <value>
  • <values>

• Element: <value>

  Description: Defines the value of the output attribute.

• Element: <values>

  Description: Defines the values of the output attribute in the case of an attribute list. The given values are appended to the result list.

  Inner Elements:

  • <add>

• Element: <add>

  Description: Defines the value to be appended to the list of CI attribute values.

Related Information