Alarm
- Sacha Parisot (Unlicensed)
glp/0/{SID}/ (rq | fb) /alarm/{Handle}/{option} |
The alarm topic allows you to define conditions that will trigger an alarm, as well as an optional action to be triggered by the alarm, such as publishing an alarm notification within IAP, sending an email or SMS notification, or executing a job object.
IAP includes an alarm manager service that monitors IAP for all alarm conditions and, when the alarm conditions are observed, it triggers the event reporting and logging services, as well as any alarm actions that are defined for the alarm.
For Example:
A user could define an alarm to be triggered whenever a particular datapoint reports power consumption that exceeds 750 watts, and to send an email to a technician when the alarm is triggered. When the IAP alarm manager detects the alarm condition to be true, the alarm manager uses the event reporting and logging services to report the event, and also triggers the action defined for the alarm (sending an email to a technician).
The triggered actions can be configured and their messages can be customized using a selection of macros. These macros are described under the message property in the Alarm Properties table below.
The IAP identifies four states for alarms, and whenever an alarm changes state, the alarm manager reports the change through the event and event logging services. The four alarm states are:
| Active | An alarm is triggered because the conditions defined for an alarm have been met. |
| Inactive | An alarm is cancelled because either the conditions to cancel an alarm have been met, or the conditions defined to trigger the alarm are no longer being met. |
| Acknowledged | A human operator responds to an alarm by performing an action through the CMS (such as clearing the alarm). Whether an alarm requires acknowledgment is configurable. An alarm that does not require explicit acknowledgment is always considered acknowledged. |
| Unacknowledged | A triggered alarm that is configured to require acknowledgment, has not been acknowledged by a human operator. |
The alarm’s state (active or inactive, and acknowledged or unacknowledged) is reflected in the events channel for the selected category.
Multiple conditions can be defined for an alarm. An alarm can become active when one condition is met, such as a power reading exceeding 750 W, and can return to an inactive state when another condition is met (such as the power reading dropping back below 500 W). Setting a second condition is optional; if none is provided, the one condition determines when the alarm becomes active and when it returns to inactive. In this case, with one condition set, the alarm would become inactive when the power reading drops below 750 W.
Deactivating an alarm never requires acknowledgment. But for an alarm that requires explicit acknowledgement, the alarm does not clear until it is acknowledged. An alarm that does not require explicit acknowledgment is always considered acknowledged, therefore, it is automatically cleared once the deactivation condition is met.
Alarm Lifecycle Example:
|
Alarm Configuration
The alarm’s current configuration is reported in the following topic with the properties listed in the Alarm Properties table.
| glp/0/{SID}/fb/alarm/{Handle}/cfg |
Alarm Status
The alarm definition status is reported in the following topic:
| glp/0/{SID}/fb/alarm/{Handle}/sts |
With the following property:
Field Name | Type | Description |
state | string | Possible values: “enabled”, “disabled”, or “deleted”. |
Examples
Example of configuration object published on glp/0/lsg/fb/alarm/k/cfg { Example of status object published on glp/0/lsg/fb/alarm/k/sts { |
Alarm Properties
Each alarm supports these properties:
Field Name | Type | Description | ||||||||||
desc | String | (Optional) A description of the alarm. | ||||||||||
enabled | Boolean | (Required) Indicates whether the alarm is enabled. | ||||||||||
cat | String | (Optional) Alarm category to use when the alarm is reported through the event and event logging service. The available categories are alarm and data. You can also define your own category. The default is alarm. | ||||||||||
ackd | Boolean | (Optional) Defaults to True. | ||||||||||
activation | String | (Required) Alarm condition expression to activate the alarm. See Alarm Conditions. | ||||||||||
deactivation | String | (Optional) Alarm condition expression to deactivate the alarm. See Alarm Conditions. | ||||||||||
message | String | (Optional) Alarm message, defaults to the activation alarm condition. The alarm message is used when reporting the alarm to the event and logging service. It is also sent with SMS actions (clipped when necessary) and used for the body of an email action. The message can be configured using a simple template language with placeholders enclosed in braces:
The default value is "alarm". | ||||||||||
urgent | Boolean | (Optional) Alarm urgency, defaults to False. The alarm urgency is reported to the event reporting service. | ||||||||||
actions | Object | (Optional) List of actions. Possible values: "sms", “email”, and “job”. See Alarm Actions. Example: | ||||||||||
severity | String | (Optional) string describing the alarm severity in user-defined categories, such as:
The string can be up to 60 characters. The severity, if available, is included with the Event object that reports the alarm. |