Managed Objects Definition Language (MODL) is an XML-based markup language used to create HierarchyFiles for Operations Center adapters. MODL uses the XML model to assign meaning to events received from management systems. The HierarchyFile reflects both the nature of information received from a management system and the processing logic of the Operations Center system.
The MODL consists of a DTD (Data Type Definition) that follows rules for structuring an XML document.
HINT:To view the most recent DTD file, open the file /OperationsCenter_install_path/database/examples/Hierarchy_2.0.DTD in a text editor.
The HierarchyFile DTD defines the rules, or grammar, for an XML document and it’s tags. It explains how the HierarchyFile interacts with the adapter and the Operations Center software to create the end product: a representation of the event stream from the network management system displayed in the Operations Center console.
Table 9-1 provides an overview of the main HierarchyFile XML tags, that are used to provide a representation of the event stream from the network management system.
Table 9-1 HierarchyFile XML Tags
XML Tag |
Description |
---|---|
<hierarchy> |
The root XML tag. The HierarchyFile must contain a <hierarchy> XML tag that surrounds one or more <group>, <filter>, <generator>, or <test> XML tags. For more information about the hierarchy XML tag, see Section 9.4.1, <hierarchy>. |
<group> |
The <group> XML tag uses filters to create depth within the element hierarchy. Each group displays as an element in Operations Center. Nested generators and groups define a hierarchy of elements and alarms under the group’s element. If there are no filters, all alarms attach to the group. Group tags can contain <filter>, <fref>, <param>, <generator>, or other <groups> tags. For more information about the group XML tag, see Section 9.4.2, <group>. |
<generator> |
The <generator> XML tag dynamically creates Operations Center elements as alarms arrive, based on specific alarm field values. A new element displays when an incoming alarm field value does not match any values of existing Operations Center elements. Generator tags can contain <filter>, <fref>, <param>, <groups>, or other <generator> tags. For more information about the generator XML tag, see Section 9.4.3, The <generator> Tag. |
<filter> |
The <filter> XML tag uses tests and fields to control which events apply to groups and generators.The filter is not a repository for an alarm; an alarm cannot attach to a filter. Filter tags can contain <filter>, <fref>, <field>, <test>, <tref>, or other <filter> tags. Filters must contain at least one child tag of any type. For more information about the filter XML tag, see Section 9.4.4, filter. |
The following sections explain the HierarchyFile XML tags and attributes that constitute the rules used to structure and present information in a useful form:
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.
Table 9-2 group Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Required |
Assigns the group name, which displays in the element’s distinguished name (DName). |
class |
Required |
Assigns the group class, which displays in the element’s distinguished name (DName). Assigning a class can be useful later when assigning an icon to the group, adding pop‑up menu operations, and other class-sensitive features. |
affected |
Optional |
Provides a way to declare that the affected element for this alarm potentially is this group, if a more detailed element does not claim the alarm instead. |
rollup |
Optional |
Specifies a condition roll-up algorithm to call from the algorithms.xml file which replaces the default behavior of highest severity. When an algorithm is set using the roll-up attribute, it cannot be reset to the default algorithm through the Operations Center console, and can only be changed to another named algorithm. |
rollupParameters |
Optional |
An additional parameter depending on the algorithm called by the roll-up attribute. |
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
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.
Table 9-3 generator Attributes
Attribute |
Type |
Description |
---|---|---|
field |
Required |
The name used for the Operations Center element. |
class or class_from_field |
Required |
Assign the group class name or use class_from_field to dynamically derive the element’s class from the value of a specified alarm field.Set either the class or class_from_field attribute, but not both. In Operations Center, class determines the icon used to represent the element and others with the same class. |
hold |
Optional |
The generated element can result in an unlimited number of generated elements over time. This can cause generated elements to “age out” after a period of time specified in the adapter settings. These elements can reappear if a new alarm requires it. Set hold=“yes” to have the elements created by this generator remain in the Operations Center console until the adapter is turned off. |
affected |
Optional |
Indicates the created element is potentially the affected element for an alarm if a more detailed (lower level) element does not claim the alarm instead. |
case |
Optional |
The case attribute establishes the case sensitivity globally for the XML file. Set case=“yes” if the field values are case-sensitive. Set case=“no” if field values are not case-sensitive. If there is no case attribute for the <field> or <generator> attribute, the case attribute in the <hierarchy> XML tag applies. If there is no case attribute for the <hierarchy> XML tag, the default is Yes. <!ELEMENT hierarchy (group|filter|generator|test)+ > <!ATTLIST hierarchy case (yes|no) “yes”> |
rollup |
Optional |
Specifies a condition roll-up algorithm to call from the algorithms.xml file which replaces the default behavior of highest severity. When an algorithm is set using the roll-up attribute, it cannot be reset to the default algorithm through the Operations Center console, and can only be changed to another named algorithm. |
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.
Table 9-4 filter Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Optional |
Assigns a name to the filter. Name a filter to reference it later without having to reenter the entire filter statement, by using the <fref> tag. For more information about the fref XML tag, see Section 9.4.7, fref and tref. |
operator |
Required |
Assigns Boolean logic to two filter conditions. The operator can be either and or or. The default is and. An incoming alarm must pass all filters when using the and operator. An incoming alarm must pass at least one filter when using the or operator. |
invert |
Optional |
Invert the result of the comparison by setting the attribute to false. The default is true, which leaves the comparison unchanged. |
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.
Table 9-5 field Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Required |
Specifies a field to test in the incoming alarm. |
operator |
Required |
Compares the value of the selected alarm field to the value attribute using one of the following operators: (equals|less|less_or_equals|greater|greater_or_equals|contains|starts_with|ends_with) |
value |
Required |
Assigns Boolean logic to two filter conditions. The operator can be either and or or. The default is and. An incoming alarm must pass all filters when using the and operator. An incoming alarm must pass at least one filter when using the or operator. |
case |
Optional |
The case attribute establishes the case sensitivity globally for the XML file. Set case=“yes” if the field values are case-sensitive. Set case=“no” if field values are not case-sensitive. If there is no case attribute for the <field> or <generator> tag, the case attribute for the <hierarchy> XML tag applies. If there is no case attribute for the <hierarchy> XML tag, the default is Yes. <!ELEMENT hierarchy (group|filter|generator|test)+ > <!ATTLIST hierarchy case (yes|no) “yes”> |
invert |
Optional |
Invert the result of the comparison by setting the attribute to false. The default is true, which leaves the comparison unchanged. |
In the following example, the filter uses the field tag to check the
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.
Table 9-6 test Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Optional |
Assigns a name to the test. Name a test to reference it later without having to reenter the entire filter statement, by using the <tref> tag. For more information about the tref XML tag, see Section 9.4.7, fref and tref. |
type |
Required |
Defines whether the test runs directly on the element or if a script runs. |
expr |
Required |
The name of the property to test or script load command. |
invert |
Optional |
Invert the result of the comparison by setting the attribute to false. The default is true, which leaves the comparison unchanged. |
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.
Table 9-7 fref and tref Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Required |
The name of the test or filter to call. |
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.
Table 9-8 param Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Required |
The name of the parameter. |
value |
Required |
The value of the parameter. |
For example, an administrator can change the information displayed for elements in the Operations Center console’s
column. The default information displayed in the 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
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
Table 9-9 properties Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Optional |
Assigns a name that allows a <pref> XML tag to reference the named <properties> XML tag and effectively reuse its definition. |
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 >
Table 9-10 property Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Required |
Name of the property. |
field |
Required |
Alarm field used to compute the value. |
computeOnGet |
Required |
Defines when to compute the custom property. If false (the default), computing the property value occurs at alarm creation, update and deletion time only for the elements to which the alarm is attached. Although the Operations Center console view displays alarms for all child elements as well, the computation does not include child element alarms. If true computes the property value when the value is needed, such as for a property page or a getAttr() call. The computation is for all alarms that can display for an element, including those attached to child elements. |
computeOnNoAlarms |
Optional |
|
computeLastDateTimeStampField |
Optional |
Evaluates date and time stamp values in the specified alarm field to determine which alarm should be considered last, compared to other alarms already received. Use with the LAST function to determine which alarm is the most recent. |
function |
Required |
Type of computation to be performed on the alarm field. Specify one of the following function types:
*Alarm activity refers to all alarm creations, changes or deletions for the element. Where indicated, some functions interpret the value of the alarm field as string data or as numeric data. If alarm field is a string, but the function uses a numeric conversion, it will try to convert it to a numeric value. |
Use the following requirements and best practices when defining properties:
Property names must be unique across custom property pages.
Do not use the same names as a Operations Center properties (such as Element, Condition, and so on).
Do not specify multiple properties computing the same function against the same alarm field.
Any alarm field used to compute a property is a mandatory alarm field.
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
alarm field, but uses a comparison on the field to determine what alarm should be considered the last. If the date value inside the field is not greater than the previously received alarm, then the alarm is skipped and does not determine the value of the 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 >
Table 9-11 value Attributes
Attribute |
Type |
Description |
---|---|---|
name |
Required |
Name of the value. |
field |
Required |
Literal value for a group or generated element. |