Alarm Monitor Configuration

Alarm Monitor Configuration

Previous Top Next

Alarm Monitors scan a data item for a certain condition. Once the condition is met the alarm fires and executes one or many actions. The trigger condition as well as the actions are defined in a Alarm Monitor section of a GSEOS configuration file.

The format is similar to XML but not well-formed XML. Typically the trigger condition contains special characters like (<, >, etc.). For easy configuration these characters can be embedded in the configuration file in clear text and therefore violate the XML definition. If you prefer you can escape these characters yourself and therefore generate well-formed XML. So for example to specify the trigger condition: Value < 20 you would write:

<Trigger Condition="Value < 20"/>

This way you can run your configuration file through an XML checker and it will be parsed successfully given your other XML definitions are correct.

If you want to check out your config file in Internet Explorer or some other XML display tool you will have to make sure you escape any special characters you use in conditions or other text items. For example:

<Trigger Condition="Value < 20"/>

has to be converted to

<Trigger Condition="Value < 20"/>

in order to display your config file in an XML display tool.

You don't have to escape if you use the config file with GSEOS, this conversion happens automatically.

Please use the sample file as a template and documentation of the various elements.

<AlarmMonitor>
An alarm monitor is defined in an <AlarmMonitor> element within a GSEOS configuration file. There can be any number of <AlarmMonitor> elements in any given configuration file.
The <AlarmMonitor> element has the following attributes:

Name:

The unique name of the alarm monitor. If the name exists already and this file gets loaded the old monitor will be replace with the new one.

Subelements of the <AlarmMonitor> node are <DataItem>, <Trigger>, and <Actions>.

<DataItem>

There must be exactly one <DataItem> element per <AlarmMonitor> element. This element specifies the GSEOS data item to monitor. This node takes two attributes: Name and Conversion.

Name:

The name of the GSEOS data item to monitor. If the item is an array item you have to specify the element of the array you wish to monitor. Currently you can only monitor scalar items or individual elements of an array item.

Conversion:

If the data item has a conversion function associated you can specify the conversion function to apply before evaluating the trigger condition. Note that the conversion function does not need to be loaded at the time when you load the alarm monitor configuration, however. As soon as the monitor is installed and gets evaluated the proper formula file (*.qlf) has to be available, otherwise an exception will be raised. This behavior allows you to specify the *.qlf and *.cfg files in any order in the gseos.ini file without creating dependencies.

<Trigger>

There must be exactly one <Trigger> element per <AlarmMonitor> element. This element specifies the trigger condition that will determine when the alarm monitor fires.GSEOS data item to monitor. This node takes three attributes: Condition, Count, and Timeout. The condition is evaluated every time the data item specified in the <DataItem> element arrives. Once the outcome is positive the timeout conditions are applied to determine if the alarm fires or not. The Count and Timeout attributes control the dynamic behavior.

Condition:

This element contains the actual trigger condition that gets evaluated every time the monitored data block arrives. As mentioned above you don't need to escape special characters when defining your condition. The special variable 'Value' represents the current value of you data item under investigation. You should use this variable to refer to the data item value and use it in your condition. Another special variable name is 'Delta'. Delta represents the difference from the previous value to the current value. E.g. if the previous value was 27 and the current value is 11 Delta would be -16. You can use Delta to check for differentials. You can use both Value and Delta in the same expression if required. The condition statement should evaluate to a boolean value. Keep in mind that the data item element defines if a conversion function should be applied to the data item. If so you want to compare against the engineering units instead of the raw count.

Conversion:

Count:

The value for count has to be numeric. If not specified it defaults to 1. The Count determines how often the condition has to evaluate to True before the alarm fires. The condition has to evaluate to True consecutively, that is once it evaluates to False the count will be reset. Also not the Timeout attribute that applies a timing condition to the count.

Timeout:

Specifies the timeout in seconds. If not specified or 0 no timeout is applied. The timeout determines the interval in seconds in which the condition has to evaluate to True Count number of times. The timeout is implemented as a sliding window. Every time the Count condition is met the timeout is evaluated from the first item that made the Count condition successful.

<Actions>
The <Actions> element configures the actions that can be executed when the alarm fires. You can configure one or more actions within the one and only <Actions> element.

Message:

This element configures the text that gets written to the Message window. The text you specify between the sub-elements <Text> </Text> is prepended with some Alarm information.

      <Message>
        <Text>
          A red high
          alarm has occurred.
        </Text>
      </Message>

LogFile:

This element configures the text that gets written to a log file. The file name is specified with the attribute FileName. The log text is configured as in the Message element.

      <LogFile FileName="MIMIAlarmLog.log">
        <Text>
          A red high alarm has occurred.
        </Text>
      </LogFile>

Command:

The <Command> element issues a command. This is it generates a CMDSTRING block with the contents you specify here. The attribute Name is the command string that gets executed.

Python:

This element allows you to call an arbitrary Python function. The function is specified with the Function attribute.

Email:

The <Email> element configures the email action. This action can send out an email to one or more recipients. The SMTPHost attribute of the Email element specifies the SMTP host you are sending your email from. The sub-element <From> specifies the sender name and email address. The sub-element <To> specifies one recipient, there can be multiple <To> tags within one <Email> node. The <Subject> and <Body> nodes set the subject line and the email body respectively.

The attributes Quota and QuotaPeriod control the number of emails that can get send out. The value of Quota has to be an integer value. It represents the maximum number of emails that can get send out during the time period QuotaPeriod. QuotaPeriod specifies the time the Quota applies to. After the period expires another Quota emails can be sent within the next period. The value of QuotaPeriod has to be a number (floating point is fine) that ends in either m (minutes), h (hours), or d (days) to indicate the dimension. It is usually recommented to set a quota since an ill-behaved alarm monitor could possibly generate emails on a basis of a fraction of a second.

      <Email SMTPHost = "smtp.jhuapl.edu" Quota="5" QuotaPeriod="2h">
        <From>SOPC@jhuapl.edu</From>
        <To>hauck@gseos.com</To>
        <To>Joe.User@jhuapl.edu</To>
        <Subject>MIMI Alarm</Subject>
        <Body>
          This is the message body. In addition this text will be prefixed by
          some general information about the alarm.
        </Body>
      </Email>