15.5 Algorithm XML Tags Reference

An algorithm consists of a series of statement to execute and calculate the state of objects. This section describes the basic XML tags used in defining algorithms.

15.5.1 Understanding the Algorithms.xml File

The Algorithms.xml file is formatted in XML which executes from the top down through a set of elements, the state calculation passes from statement to statement until there are no more statements, or a statement terminates the calculation.

Within an algorithm definition, many types of actions can be performed including:

  • Gather elements: Determines which group of element children to look at when calculating condition.

    For more information, see <gather> in Table 15-2.

  • Eliminate some elements: Filters out any elements that should not affect the calculation.

    For more information see <conditionreduce>, <matchreduce>, and <scriptreduce> in Table 15-2.

  • Simple calculations: Performs basic arithmetic operations, such as highest, average, or lowest.

    For more information, see <average>, <highest>, and <lowest> in Table 15-2.

  • Fire a script: Initiates a script that calculates the condition.

    For more information, see <script> in Table 15-2.

  • Banding Thresholds: Compares the results of arithmetic operations to a defined threshold or a set up to 10 high and low limits to calculate the element’s condition.

    For more information, see <band> and <elementpropertyband> in Table 15-2.

  • Split command: Allows the original condition value to be passed to various branches of the algorithm to be modified as necessary without affecting other algorithm calculations.

    For more information, see <split> and <timebasedsplit> in Table 15-2.

The usual sequence of an algorithm definition is to gather, reduce, then perform a condition calculation, often by highest or by count. A skip tag can be used break from current calculations and continue using a different algorithm sequence if certain conditions are met.

The following excerpt from the Algorithms.xml file shows the file header and the bandPercent algorithm definition. Excluding any children with the state of UNKNOWN or UNMANAGED, it uses a series of thresholds to set condition based on a percentage of children having a specified condition. For example, if 75% or more children are MAJOR, the resulting calculation is CRITICAL.

<?xml version="1.0"?>
<!DOCTYPE algorithms PUBLIC
 "‑//Managed Object Solutions, Inc.//DTD algorithms 1.0//EN"
  "http://www.ManagedObjects.com/dtds/Algorithms.dtd>

<algorithms>
   <algorithm name="_bandPercent">
      <gather relationship="NAM" />
      <gather relationship="ORG" />
      <conditionreduce testCondition="UNKNOWN" />
      <conditionreduce testCondition="UNMANAGED" />
      <band testCondition="CRITICAL" amount="75%" result="CRITICAL" />
      <band testCondition="MAJOR" amount="75%" result="CRITICAL" />
      <band testCondition="CRITICAL" amount="50%" result="MAJOR" />
      <band testCondition="MAJOR" amount="50%" result="MAJOR" />
      <band testCondition="CRITICAL" amount="25%" result="MINOR" />
      <band testCondition="MAJOR" amount="25%" result="MINOR" />
      <band testCondition="MINOR" amount="50%" result="MINOR" />
      <band testCondition="OK" amount="100%" result="OK" />
      <set result="INFO" />
   </algorithm>
</algorithms>

It is important that the XML be well-formed. Options for an algorithm are specified between the <algorithm></algorithm> tags. For information about using specific tags, continue to Section 15.5.2, Understanding the Top-Level Tags.

15.5.2 Understanding the Top-Level Tags

Each Algorithms.xml file requires one algorithms tag to be declared. Within the algorithms tag, algorithm and defineCommand tags are used to define each algorithm.

Table 15-1 lists the top-level tags for the Algorithms.xml file.

Table 15-1 Top-Level Algorithm Tags

Tag

Description

<algorithms>

Declares a series of named algorithms.Place a series of algorithm tags inside to define different algorithm definitions, or use a series of defineCommand tags to define the algorithm calculations.

<algorithm>

Defines a new algorithm. Specify the following attributes as required:

  • name: Identifier for the algorithm. Displays when selecting an alternate algorithm for an element.

Can contain any number of <exec> and <split> declarations.

<defineCommand>

Used in lieu of the algorithm tag, declares a new command using exec tags. A Java class must be available that adheres to the com.mosol.util.algo.Algorithm interface. Specify the following attributes as required:

  • name: Name of the algorithm.

  • class: Class of the algorithm. The engine executes Class.forName on the class specified and creates new instances with a no‑argument constructor. The class has its initializeAlgorithm method called when instantiated.

Parameter substitution can be used within definecommand statements.

Inside each algorithm and defineCommand tag, the tags listed in Table 15-2 are used to setup the specific statements and calculations that allow the algorithm to compute condition for an element.

Table 15-2 Algorithm Definition Tags

Tag

Description

<average>

Returns average condition of the elements in the active set. Specify the following attributes as required:

  • defaultCondition: Condition to be set if there are no gathered elements. Specify INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, or OK.

  • reason: Descriptive text explaining why the condition was set.

  • rounding: If lower, rounds the calculation to the more severe condition value. Specify lower or higher. If not specified, the less severe condition level is returned.

<band>

A threshold evaluation used to set the condition based on a percentage of elements which a specific condition. Successive band tags are commonly used to assign declining levels of severity to certain numbers of elements at a condition level. Once a threshold band is matched, the resulting condition is set, and the computation stops. Specify the following attributes as required:

  • testCondition: Condition to be tested. Specify INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, or OK.

  • amount: Matching criteria as a number or a percentage.

  • result: Condition to be set if there is there is a match. Specify INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, or OK.

  • reason: Descriptive text containing the reason why the condition was set. Used for root cause information and element notes.

  • skip: Name of algorithm to skip to if the algorithm passes. If skip is not defined, the next tag statement found is evaluated.

  • invert: If yes, inverts the algorithm’s test criteria.

<branch>

Branches are used within a split tag to apply a switch case or “if then, else” logic.Define branches to reduce a set of objects by class, name or condition; or evaluate condition on a single object or a class of objects. Use this strategy when service model's dependencies are less organized and there are multiple critical dependencies that need to be evaluated. Evaluate the conditions which would cause the focus of the algorithm to be most severe first, and then evaluate for less critical results.

The branch tag can contain any other tags except the algorithms and algorithm tags.

<conditionreduce>

Excludes an element from the gathered elements if it is of a specified condition. Specify the following attributes as required:

  • testCondition: Condition to be tested. Specify INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, or OK.

  • invert: If yes, inverts the algorithm’s test criteria and elements remain as a gathered elements if not the specified condition.

<count>

Looks for a condition with the given number of elements. The count tag can be set to 50% to try to find, in descending order of severity, a triggering number of events. If at least 50% of elements are not of a severity above OK, it does not fire. Specify the following attributes as required:

  • amount: Matching criteria as a number or a percentage.

  • defaultCondition: Condition to be set if there are no gathered elements. Specify INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, or OK.

  • reason: Descriptive text explaining why the condition was set.

<elementpropertyband>

Sets a condition to result if a specified element property has a value within the upper and lower points defined in the algorithm. The intent of this algorithm is to be used with the Experience Manager Suite to set thresholds of integer-based element properties, or namely response times.

If the value of the given element property falls between the upper and lower bound defined, the result condition is set to the element that this algorithm is set to. If not, the conditionState is not modified.

In the case of the Operations Center Experience Manager, the min and max values are used in milliseconds. Specify the following attributes as required:

  • elementProperty: Name of the element property to evaluate.

  • min: Lower bound threshold. Specify a number in ms.

  • max: Upper bound threshold. Specify a number in ms.

  • result: Condition to be set if the elementProperty value fall within the min and max values.

  • reason: Descriptive text containing the reason why the condition was set. Used for root cause information.

  • skip: Name of the algorithm to skip if the algorithm passes.

<exec>

The exec tag has been superseded with separate XML tags. As a result, the other Algorithm tags can be used without the exec tag while providing better XML validation. Use the exec tag only for backwards compatibility for existing algorithms.xml files.

<gather>

Determines the set of elements to perform the calculation against based upon the element’s relationship to the current element. Multiple gather tags can be used to more than one type of relationship. Specify the following attributes as required:

  • relationship: Type of element relationship to gather. Specify ORG for elements in the Service Models hierarchy, or NAM for elements in the Elements tree.

<highest>

Takes the most severe condition of all elements. This corresponds to the default behavior if no algorithm is set for a given element. Specify the following attributes as required:

  • defaultCondition: Condition to be set if there are no gathered elements. Specify INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, or OK.

  • reason: Descriptive text containing the reason why the condition was set. Used for root cause information.

<invoke>

Permits algorithms to be called. This is the equivalent of invoking a subroutine. Specify the following attributes as required:

  • name: Name of algorithm called.

If the invoke tag is used to invoke another algorithm that is parameterized, the parameters must appear with the same name as the parameters in the top-level algorithm. Otherwise, the parameters values cannot be set.

<lowest>

Takes the least severe condition of all elements. Specify the following attributes as required:

  • defaultCondition: Condition to be set if there are no gathered elements. Specify INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, or OK.

  • reason: Descriptive text containing the reason why the condition was set. Used for root cause information.

<matchreduce>

Removes an element from the calculation based on a regular expression match against a property value. Specify the following attributes as required:

  • property: Name of the property to match. For example, for matching against:

    • element dName, use property=dname

    • element name, use property=name

    • element condition, use property=condition

    • an element property, use property=element_property_name

    • an element’s class, use property=class

  • value: Regular expression to match against the property’s value. Use an “i” at the end for case insensitivity.

  • invert: If yes, inverts the meaning of the algorithm’s test criteria.

<parameter>

Modify behavior or values in the algorithm. Parameter values can be edited by the user when the algorithm type is selected for the element. Specify the following attributes as required:

  • name: Parameter name.

  • description: Descriptive text containing the reason why the condition was set. Used for root cause information.

  • type: Type of parameter to identify acceptable values. Specify one of the following:

 

text

Arbitrary text string.

 

condition

INITIAL (Operations Center reports this as UNMANAGED), UNKNOWN, CRITICAL, MAJOR, MINOR, INFORMATIONAL, OK.

 

boolean

YES, NO

 

property

name, dname, className, marker

 

kind

NAM, ORG, TOP, MAP

 

choice

A specific set of pipe-delimited (|) choices. For example, enter:

00%|75%|50%|25%
  • default: Default value based on selected type.

Parameter values are stored in the Configuration Storage database for each associated element. Care should be taken when adding, removing, or changing algorithm parameters for an algorithm that in use.

<script>

Invokes FormulaScript code. The script can examine the context of the condition calculation, extend or reduce the set of elements, set the state of the computation, change the result, or generally update the element’s state in any way. Specify the following attributes as required:

  • script: A FormulaScript to be evaluated. Can be a small amount of code or a direct reference to any file located in the /OperationsCenter_install_path/database/scripts directory.

  • resolveScriptParameters: If true, the script has parameters that need to be resolved. Defaults to false. Parameters allow substitution of text that can differ per element. Be aware that using the braces (“{“ and “}”) in the script might cause conflicts with parameter substitution, because these characters signify substitution.

 

Information that can be passed while using the script tag:

  • subject: The element whose condition is being calculated.

  • server: The Operations Center server.

  • adapter: The adapter from which the element originates.

  • conditionState: The current condition state. Inside the script, these tasks can be performed:

    • Finish the algorithm: conditionState.setState(State.FINISHED)

    • Reduce the elements: conditionState.getElements().remove(elem)

    • Iteratively review the current set of elements:

      for( var enum = conditionState.getElements().elements(); enum.hasMoreElements();

      // Do something with element writeln( enum.nextElement() ) The return value of the script is ignored.

For more information about creating scripts and scripts available in the Script Library, see the Operations Center 5.5 Scripting Guide.

<scriptreduce>

Removes an element passed from the gathered elements based on a script return code of type java.lang.Boolean. True to remove an element and False to leave an element in the gathered set. Specify the following attributes as required:

  • script: Script to be evaluated. Can be a small code snippet or a direct reference to any file located in the /OperationsCenter_install_path/database/scripts directory.

  • resolveScriptParameters: If True, the script has parameters that need to be resolved. Defaults to False. Parameters allow substitution of text that can differ per element. Be aware that using the braces (“{“ and “}”) in the script might cause conflicts with parameter substitution, because those characters signify substitution.

  • invert: If yes, inverts the return code meaning so that True leaves an element and False removes it.

 

Information that can be passed while using the scriptreduce tag:

  • subject: The element whose condition is being calculated.

  • server: The Operations Center server.

  • adapter: The adapter from which the element originates.

  • element: The element to test for removal.

  • state: The current condition.

For more information about creating scripts and scripts available in the Script Library, see the Operations Center 5.5 Scripting Guide.

<set>

Sets an arbitrary condition and finishes the calculation immediately. Specify the following attributes as required:

  • result: Condition to be set.

  • reason: Descriptive text containing the reason why the condition was set. Used for root cause information.

<split>

Creates copies of the original condition and passes it to each branch tag defined within the split tag. This allows each branch to perform calculations with the same state information without affecting each other.

<timebasedbranch>

Enables branching based on calendars and time categories. Uses the calendar and timecategories parameters. When selecting the algorithm, the user specifies a calendar and time categories.

For more information, see Section 15.5.3, Understanding timebasedbranch and timebasedsplit.

<timebasedsplit>

Functions the same as the split tag based on calendars and time categories.

For more information, see Section 15.5.3, Understanding timebasedbranch and timebasedsplit.

15.5.3 Understanding timebasedbranch and timebasedsplit

The <timebasedbranch> and <time-basedsplit> tags enable an algorithm to behave differently, depending on the day and time. One simple application is to set the condition based on a specific time category.

All algorithms are state-driven and algorithm logic fires only when a state change occurs, or when a recalculation occurs. So when using calendar-based algorithms, it is important to remember that this type of algorithm is not reevaluated when a calendar is edited, or when a calendar switches from one time category to another. For example, you might expect the condition to change when the calendar goes from Peak to Off‑peak at 5 PM. However, this change does not fire a recalculation at 5 PM, it is only recalculated when a state change occurs.

The following example sets the highest condition during the Peak and Critical time categories. The algorithm gathers everything on ORG and NAM, then looks for any matches of 2 or 3 for AlgorithmCalendar.  If a match is found, the normal highest state is used. The algorithm sets a MINOR condition for all time periods other than these two time categories.

  <algorithm name="calendarSplitting">
        <exec command="gather" relationship="NAM" />
        <exec command="gather" relationship="ORG" />
            <timebasedsplit>
                <timebasedbranch calendar="AlgorithmCalendar" timecategories="2|3">
                    <exec command="highest" reason="Condition set by 'exec' statement using 'highest' on match of calendar time categories in algorithm." />                
                </timebasedbranch>
                <timebasedbranch>
                    <set result="MINOR" reason="Condition set by 'set' statement for NOT matching calendar time categories in algorithm." />
                </timebasedbranch>
            </timebasedsplit>
    </algorithm>

Where, the AlgorithmCalendar is the name of the calendar in Operations Center.  The timecategories parameter is a pipe-delimited (|) list of time category IDs and uses the following numbers for the timecategories parameter: BLACKOUT = 0, CRITICAL = 1, PEAK = 2, ON = 3, NONPEAK = 4, and OFF = 5.

15.5.4 Understanding Parameter Evaluation

The following information should be considered when using parameters with the tags described in Table 15-2.

  • The initializeAlgorithm() method, invoked when the algorithms.xml file is loaded, stores initial attribute values without converting them to their base types.

  • The text string given as an attribute (such as “{condition},” “MAJOR,” and so on) is not converted to its base type (ElementCondition) until the algorithm statement is evaluated against a specific element after parameter substitution takes place. An invalid value (result="NO") does not log an exception until algorithm evaluation time, not upon initial load of the algorithms.xml file.

  • The actOnState() method, invoked when the algorithm statement is evaluated for a specific element, performs parameter substitution for each attribute value using the resolveParameters() method in the ConditionState class. A code fragment might be:

    String condition = ((com.mosol.Formula.Server.algo.ConditionState)state).resolveParameters(conditionString);
    

    where state is the condition as passed in as a parameter to actOnState(), and conditionString is the attribute value stored in the initializeAlgorithm() method.