9.4 HierarchyFile DTD Reference

The HierarchyFile must contain a <hierarchy> root XML tag that surrounds one or more groups, generators or filters. This XML tag contains the entire hierarchy intended for the information received from a management system.

The hierarchy declaration is:

<!ELEMENT hierarchy (group|filter|generator|test)+ >
<!ATTLIST hierarchy
   case (yes|no) "yes">

A <hierarchy> XML tag can have <group>, <filter>, <generator>, or <test> XML tags as children. The plus character (+) indicates that the incoming data must have a <hierarchy> XML tag containing one or more of the children XML tags, in the order listed. The <hierarchy> tag has no attributes.

An anonymous <filter> XML tag (one without a name attribute), defined immediately after the <hierarchy> XML tag, globally controls all events that any contained <group> or <generator> XML tags can process. If a candidate event does not match the criteria defined in the top-level filter, the event does not display in Operations Center.

For details on usage, see Section 9.4.4, filter.

A <group> is a named tag that uses filters to create depth within the element hierarchy. Each group displays as an element in Operations Center. Groups can contain other groups, but the contained groups only receive the subset of alarms that passed their parent group’s filters. If there are no filters, all alarms attach to the group.

The group tag declaration is:

<!ELEMENT group (filter|fref|group|generator|param|properties|pref)* >
<!ATTLIST group
  name CDATA #REQUIRED
  class CDATA #REQUIRED
  affected (yes|no) "no"
  rollup CDATA #IMPLIED
  rollupParameters CDATA #IMPLIED>

Group tags can contain <filter>, <fref>, <generator>, <param>, <properties>, or other <groups> tags.

Table 9-2 describes <group> attributes.

In the following example, the Consoles group applies a filter and a generator. The filter only accepts alarms whose affected element is console-capable. The generator creates a Operations Center element for each unique ems field in the incoming alarms.

<group name="Consoles" class="Consoles">
   <filter>
     <test type="element" expr="console" compare="true" />
   </filter>
   <generator field="ems" class_from_field="class" hold="yes" />
</group>

The <generator> XML tag dynamically creates new Operations Center elements as alarms arrive, based on specific alarm field values.

For <generator> tags, the process of attaching an alarm creates a new Operations Center element only if the incoming field value is unique (does not match any existing element).

New elements created by a generator are not necessarily the affected element. Each alarm can have only one affected element. As an alarm moves through the hierarchy, many Operations Center elements might become potential affected elements. The affected element is the one to which the alarm finally attaches and the affected attribute equals yes.

The generator declaration is:

<!ELEMENT generator (filter|fref|generator|group|param|properties|pref)* >
<!ATTLiIST generator
  field CDATA #REQUIRED
  class CDATA #IMPLIED
  class_from_field CDATA #IMPLIED
  hold (yes|no) "no"
  affected (yes|no) "yes"
  case (yes|no) "yes"
  rollup CDATA #IMPLIED
  rollupParameters CDATA #IMPLIED>

Generator tags can contain <filter>, <fref>, <group>, <param>, <properties>, <pref>, or other <generator> XML tags.

Table 9-3 describes <generator> attributes.

<!ELEMENT hierarchy (group|filter|generator|test)+ >
<!ATTLIST hierarchy
   case (yes|no) "yes">

The following example creates a Operations Center element for every unique value in the group alarm field. New elements have a class equal to the value of the groups field.

<generator field="group" class_from_field="group" case="yes|no" hold="yes"    rollup="average" rollupParameters="average" />

<filter> and <fref>) definitions used in generator statements perform exactly as they do in a <group> statement, controlling the events that pass down a branch of the hierarchy.

The following example shows nested generator statements. Each <generator> statement creates child elements for the elements created by the parent <generator> statement.

<generator field="class" class_from_field="class" hold="yes">
    <generator field="ems" class_from_field="class" hold="yes" />
    <group name="servers" class="server" />
    <group name="hosts" class="host" />
</generator>

Operations Center selects as the actual affected element the lowest-level and most specific of all potential affected elements. In the following example of nested <generator> statements, alarms attach to only those elements created by the inner statement, <generator field="sub_source">.

<generator field="source" class="source" affected="yes">
    <generator field="sub_source" class="sub_source" affected="yes"/>
</generator>

A <filter> controls which alarms can attach to group or generator elements. The filter is not a repository for an alarm; an alarm cannot attach to a filter. Specify one or more filters. A filter can test an alarm’s fields, or it can test other information known when new alarms arrive.

The filter tag declaration is:

<!ELEMENT filter (filter|fref|field|test|tref)+ >
<!ATTLIST filter
name ID #IMPLIED
operator (and|or) "and">
invert (true|false) "false">

Filter tags can contain <filter>, <fref>, <field>, <test>, <tref>, or other <filter> tags. Use nested filters or <fref> tags for more conditional filtering. Filters must contain at least one child tag of any type.

Table 9-4 describes <filter> attributes.

In the following example, an incoming alarm must satisfy only one of the two conditions named within, as the operator is set to or. An incoming alarm with a class equal to MEGAT or ORN200 attaches to the group, which is the parent element of the filter. Use filters in a similar way with <generator> tags.

<filter name="nps" operator="or">
    <field name="class" operator="equals" value="MEGAT" />
    <field name="class" operator="equals" value="ORN200" />
</filter>

Since filters can contain other filters or <fref> filter references, it is possible to build complex, multipart tests for inclusion or exclusion. They can act as gatekeepers at the top of different branches of a hierarchy. In complex HierarchyFiles, cap long branches of the hierarchy with filters to control the alarms pass on to their child elements. The appropriate parts of the hierarchy parse alarms, as shown in the example in Section 9.4.2, <group>.

A <field> XML tag tests specific fields in an incoming alarm against a target value. A field cannot contain any other XML tags.

The field declaration is:

<!ELEMENT field EMPTY>
<!ATTLIST field
  name CDATA #REQUIRED
  operator (equals|less|less_or_equals|greater|greater_or_equals|
    contains|starts_with|ends_with) "equals"
  value CDATA #REQUIRED
  case (yes|no) "yes"
  invert (true|false) "false">

<filter>

Table 9-5 describes <field> attributes.

(equals|less|less_or_equals|greater|greater_or_equals|contains|starts_with|ends_with)

<!ELEMENT hierarchy (group|filter|generator|test)+ >
<!ATTLIST hierarchy
   case (yes|no) "yes">

In the following example, the filter uses the field tag to check the Severity field of incoming alarms for a severity value that is less than 3:

<filter name="ccfilter">
    <field name="severity" operator="less_than" value="3" />
</filter>

The following example shows how nested filters can be used and is a snippet from a HierarchyFile.

<filter name="sch" operator="and">
   <filter operator="or">
      <field name="text" operator="contains" value="FT002204" />
   </filter>
   <filter operator="and">
      <field compare="false" name="rule" value="Citicorp" />
      <field compare="false" name="text" operator="contains" value="IM" />
   </filter>
</filter>

The <test> XML tag checks the properties of an alarm’s affected element. A test can determine whether an element has a specific capacity, such as console, or it can run a script that returns a Boolean result.

The test declaration is:

<!ELEMENT test EMPTY>
<!ATTLIST test
  name ID #IMPLIED
  type (element|script) #REQUIRED
  expr CDATA #REQUIRED
  invert (true|false) "false">

Table 9-6 describes the <test> attributes.

In the following example, a filter uses the <test> tag to check if an alarm’s affected element has the console capability. The type attribute is set to element and the expr attribute identifies the value console. The filter selects all affected elements that have console capability.

<filter>
  <test type="element" expr="console" compare="true" />
</filter>

Set the compare attribute to false to return all affected elements that do not have console capability.

<fref> and <tref> XML tags are references that call previously defined filters or tests. This avoids the inconvenience of redefining the same filter or test more than once in the body of the XML.

The fref declaration to call a named filter is:

<!ELEMENT fref EMPTY>
<!ATTLIST fref
  name IDREF #REQUIRED>

The tref declaration to call a named test is:

<!ELEMENT tref EMPTY>
<!ATTLIST tref
  name IDREF #REQUIRED>

Table 9-7 describes <fref> and <tref> attributes.

In the following example, the <fref> calls the filter named ccfilter, as previously defined in the example shown in Section 9.4.4, filter.

<fref name=ccfilter />

A <pref> is a properties reference. It references a <properties> XML tag by name which contains a definition of one or more element properties. Referencing a <properties> XML tag with <pref> effectively reuses the <properties> definition at the point of the <pref>.

<!ELEMENT pref EMPTY >
<!ATTLIST pref
    name CDATA #IMPLIED >

A <page> allows grouping the <property> and <value> XML tags that it contains for a specific named page displayed in the browser. If there is no name, the default page applies.

<!ELEMENT page (property|value)+ >
<!ATTLIST page
    name CDATA #IMPLIED >

A <param> XML tag is an arbitrary parameter which can be assigned to elements. Use params to support adapter-specific behavior. Specify a <param> tag within a <group> or <generator> tag.

The param declaration is:

<!ELEMENT param EMPTY>
<!ATTLIST param
  name CDATA #REQUIRED
  value CDATA #REQUIRED>

Table 9-7 describes <param> attributes.

For example, an administrator can change the information displayed for elements in the Operations Center console’s Notes column. The default information displayed in the Notes column is a summary of active alarm counts for a specific element or a text message if there is only one alarm associated with the element.

In the following example, the Notes field for each generated element displays the text message of the most recently received or changed alarms:

<generator field="hostname">
  <param name="lastMessageAsNotes" value="true" />
</generator>

For information about available parameters, see Section 9.5, Parameter Reference.

For examples using parameters, see Section 9.8, Example: Mining Performance Data and Section 9.9, Example: SCM Matching.

<properties> is a container for a group of page tags. It can be optionally name, which allows a <pref> tag to reference the named <properties> tag and effectively reuse its definition.

The properties declaration is:

<!ELEMENT properties (page)+ >
<!ATTLIST properties
   name CDATA #IMPLIED

A <property> defines an element property with a value that is computed from an alarm field for a group or generated element.

The property declaration is:

<!ELEMENT property EMPTY >
<!ATTLIST property
    name CDATA #REQUIRED
    field CDATA #REQUIRED
    function (LAST|FIRST|AVG|SUM|LOWEST|HIGHEST|MIN|MAX|ROLLINGAVG|PSEUDOAVG|LASTWITHVALUE) #REQUIRED
    parameter CDATA #IMPLIED
    computeOnGet (true|false) "false"
    computeOnNoAlarms CDATA #IMPLIED
    computeLastDateTimeStampField CDATA #IMPLIED
>

Use the following requirements and best practices when defining properties:

The following code computes custom property values from the alarm field after alarm creation, change, or deletion:

<properties> 
   <page> 
      <property field="q1" function="SUM" name="q1:SUM" computeOnGet="true" /> 
      <property field="q1" function="AVG" name="q1:AVG" computeOnGet="false" /> 
      <property field="q1" function="MIN" name="q1:MIN" computeOnGet="true" /> 
      <property field="q1" function="MAX" name="q1:MAX" computeOnGet="false" /> 
    </page> 
</properties>

The following statement looks for the most recent value of the OSISeverity alarm field, but uses a comparison on the creationTimestamp field to determine what alarm should be considered the last. If the date value inside the creationTimestamp field is not greater than the previously received alarm, then the alarm is skipped and does not determine the value of the LastSeverity property.

<property field="OSISeverity" function="LAST" computeLastDateTimeStampField="creationTimestamp" name="LastSeverity"/> 

For an example using properties, see Section 9.7, Example: Custom Properties from Alarm Fields.

A <value> defines an element property created with a literal value for a group or generated element. The declaration is:

<!ELEMENT value EMPTY >
<!ATTLIST value
    name CDATA #REQUIRED
    value CDATA #REQUIRED >