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:
Consider an alarm that activates when a temperature reading exceeds 80° C, deactivates once the temperature falls below 70° C, and is configured to require explicit acknowledgment.

When the temperature exceeds 80° C, the alarm becomes active and in an unacknowledged state, awaiting acknowledgment. The alarm manager begins tracking this alarm and reports the change in alarm state to the event and logging service.
When the temperature drops below 70° C, the alarm becomes inactive, but remains unacknowledged. This new state is reported to the event and logging service.
When the CMS submits explicit acknowledgment of the alarm, it remains inactive, but becomes acknowledged. This new state is reported to the event and logging service. The alarm manager stops tracking the alarm.

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

{
"desc":null,
"enabled":true,
"cat":"test",
"ackd":true,
"activation":"gt(\"glp/0/lsg/fb/dev/lon/0/if/light/0/sp/value/h\", 10)",
"deactivation":"eq(\"glp/0/lsg/fb/dev/lon/0/if/light/0/sp/value/h\", 30)",
"message":null,
"urgent":false,
"actions":null,
"severity":null,
"mru":"2019-03-22 06:29:05.774 UTC"
}

Example of status object published on glp/0/lsg/fb/alarm/k/sts

{
"state":"enabled",
"mru":"2019-03-22 06:29:03.845 UTC"
}

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:

{topic}	for the feedback topic under scrutiny, according to the alarm condition.
{alarm}	for the alarm’s feedback topic.
{condition}	for the condition that triggered the activation.
{date}, {time}	for current date and time.
{sid}	for the segment identifier.

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:
{sms: { … },
email: { … }
…}

severity

String

(Optional) string describing the alarm severity in user-defined categories, such as:

- “minor fault”
- “major fault”
- “critical fault”

The string can be up to 60 characters.

The severity, if available, is included with the Event object that reports the alarm.