Alarm Properties and Event Reference

To set the general properties for alarms

  1. Go to the Config section of the Gateway.

  2. Choose Alarming>General from the menu on the left.
    The General Alarm Settings page is displayed.

  3. Set the general alarm properties shown in the following table:

Alarm Evaluation

Live Event Limit

Default is 5. The number of "live" events (active or unacknowledged) that can exist for a single alarm at a given time. When surpassed, older events will be acknowledged automatically by the system. This means as an alarm cycles on and off, Ignition will keep track of the last 5 times the alarm event happened until the user acknowledges them. This does not store history for those events.

Event Suppression

Continuous Event Detection Window (min)

Default is 10. The amount of time to store events before shutdown to prevent new duplicate events from being created on startup. This setting prevents unacknowledged active events from being generated due to reboot. If set to 0, will not be used.

Notify Initial Events

Default is false. If false, active alarms caused by the "initial state" (that is, the first value checked after being created, or after the enabled state changes) won't be sent to the notification system. This means if you add an alarm to a tag, a notification won't be immediately sent when the new state is created.

Alarm Properties

All alarm states have a list of properties that you can edit or bind when creating or editing a tag. Here is the list of attributes paired with their scripting names. This is useful when using the system.tag.add() and system.tag.edit() functions.

If the attribute you want to reference is not listed, you can simply change the attribute on your tag, export it to XML, and view the reference to the alarm attribute.

Property Name

Scripting Name

Description

Main

Name

name

The name of the alarm.

Enabled

enabled

Specifies whether or not this alarm is evaluated by the system.

Priority

priority

The priority (or "severity") of this alarm. Diagnostic (0), Low (1), Medium (2), High (3), Critical (4)

Timestamp Source

timestampSource

Dictates whether the timestamp used on the alarm comes from the system or the value. System (0), Value (1)

Display Path

displayPath

An optional path (separated by "/") that will be used for display and browsing purposes.

Ack Mode

ackMode

How acknowledgement works for the alarm: Auto (1) - Alarm is acknowledged when cleared. Manual (2) - Alarm acknowledged by user. Unused (0) - Alarm is always marked as 'acknowledged'.

Notes

notes

Documentation about the alarm.

Ack Notes Required

ackNotesReqd

Select this option to require operators to provide some explanation when the alarm is acknowledged. true or false

Shelving Allowed

shelvingAllowed

true or false

Alarm Mode Settings

Mode

mode

The alarm mode. Each mode has a unique behavior:

  • Equal - Active when the tag's value equals the alarm's setpoint.

  • Not Equal - Active when the tag's value does not equal the alarm's setpoint.

  • Above Setpoint - Active when the tag's value is above the alarm's setpoint.

  • Below Setpoint - Active when the tag's value is below the alarm's setpoint.

  • Between Setpoints - Active when the tag's value is between the low and high setpoints. If any change is true, an event will be generated for each value change between the setpoints.

  • Outside Setpoints - Active when the tag's value falls outside the low and high setpoints. If any change is true, and event will be generated for each value change outside the setpoints.

  • Out of range - The same as Outside Setpoints, but uses the tag's Engineering High and Engineering Low as the high and low setpoints.

  • Bad Quality - Active if the tag value becomes a bad quality, for example, on comm loss.

  • Any Change - An alarm event is generated every time the tag value changes. Note that this alarm will NEVER be "active" because each active event is paired with a matching clear event, instantly.

  • Bit State - This alarm mode is used to alarm when a specific bit out of an integer tag becomes high. You must specify which bit position to use, with zero being the least significant bit. The On Zero property is used to invert the logic and alarm when the bit is low.

  • On Condition - This free-form alarm mode is used for when you want to specify the condition using an expression or another tag. To do this, bind the "Is Active" property to an appropriate expression or tag.

Equal (0), Not Equal (1), Above Setpoint (2), Below Setpoint (3), Between Setpoints (4), Outside Setpoints (5), Out of Range (6),

Bad Quality (7), Any Change (8), Bit State (9), On Condition (10)

Setpoint / Low Setpoint

setpointA

The value used to initiate an alarm. If the alarm mode calls for two setpoints, this is the low value.

Inclusive / Low Inclusive

inclusiveA

If true, the Setpoint or Low Setpoint value is used inclusively for the condition to alarm.

High Setpoint

setpointB

The high value used to initiate an alarm when the alarm mode calls for two setpoints.

High Inclusive

inclusiveB

If true, the High Setpoint value is used inclusively for the condition to alarm.

Any Change

anyChange

If true, will alarm on each value change given the alarm mode conditions are met.

Bit Position

bitPosition

The position of the bit, starting at 0, that will be watched.

On Zero

bitOnZero

If true, will alarm when the specified bit is not high, or "0".

Deadbands and Time Delays

Deadband

deadband

A numeric deadband of the alarm condition. The interpretation of this value depends on the deadband mode. Note that his deadband is separate from, and evaluated after, the tag's deadband.

Deadband Mode

deadbandMode

Defines how the deadband value is used. If percent, the value (0-100) will be compared against the Eng. limits defined for the value. Absolute (0), Percent (1)

Active Delay

timeOnDelaySeconds

The time, in seconds, before the alarm will be considered truly active after the active condition becomes true. Also known as a "rising edge time deadband".

Clear Delay

timeOffDelaySeconds

The time, in seconds, before the alarm will be considered truly clear after the clear condition becomes true. Also know as a "falling edge time deadband".

Notifications

Active Pipeline

activePipeline

The pipeline that will be used to process active events generated by this alarm.

Clear Pipeline

clearPipeline

The pipeline that will be used to process clear events generated by this alarm.

Ack Pipeline

ackPipeline

The pipeline that will be notified when the alarm has been acknowledged.

Email Notification Settings

Custom Subject

CustomEmailSubject

If specified, will be used for the email subject. If blank, the subject defined in the notification block to be used.

Custom Email

CustomEmailMessage

If specified, will be used for email message. If blank,. the message defined in the notification block will be used.

SMS Notification Settings

Custom Message

CustomSmsMessage

If specified, will be used for the SMS message. If blank, the message defined in the notification block will be used.

Alarm Properties

An alarm event is made up of many pieces of information. The state, the value, the time, all of the configuration data for the alarm, and more are collectively known as the properties of the event. A "property" is generally a name, potentially along with a default value. There are many properties that an alarm may have, and if the property isn't present, the default value is usually assumed.

This is different than the alarm properties used during initial setup, these are the properties available when an alarm event occurs (active, clear, acknowledge).

How Properties are Used

Properties are used in a number of ways, they:

  • Define how an alarm behaves.

  • Are referenced in messages, such as the body of an email, or sms message.

  • Are referenced in Expressions, such as in the binding of a different property, or in an Expression block.

  • Are created and used in pipelines as temporary variables, such as to make a counter.

  • ... and various other places.

While properties are always accessed the same (for example by using the {propertyName} syntax in a message or Expression, or the getProperty() Expression function), there are some subtle variations on where the property value comes from, and what its lifecycle will be. To understand this better, consider that an Alarm Event has the following structure:

Alarm Event
Active Event Properties
Clear Event Properties
Acknowledged Event Properties
Runtime Properties

The first three collections of properties get created when the described type of event occurs.
Consequentially, it's possible for the same property to exist multiple times in an Alarm Event. For example, a bound configuration property or associated data is captured on both the active and clear events. When you reference a property, the alarm event will provide you with the most recent value. So, if you have a bound property call "MyData", and you reference it when the alarm is active, you may get a different result than when the reference is executed later and the alarm has cleared. The individual values are stored separately in the alarm journal, however.

Configuration Properties

 

Name

The name of the Alarm.

Enabled

Set to False to turn off the alarm state and all associated actions.

Priority

Used for sorting/filtering. Numerical values are associated with each priority to make comparision easier.

Value

Priority

0

Diagnostic

1

Low

2

Medium

3

High

4

Critical

Display Path

The unique path of the Alarm state.

Active Pipeline

Which pipeline (if any) to use when the alarm goes into the Active State.

ClearPipeline

Which pipeline (if any) to use when the alarm goes into the Clear State.

TimeOnDelaySeconds

The amount of consecutive seconds that the alarm state must be True before the Tag enters this alarm state.

TimeOffDelaySeconds

The amount of consecutive seconds that the alarm state must be False before the Tag exits this alarm state.

Notes

Free-form notes for the alarm state.

As described in the previous section, Runtime Properties are different in that they only exist while the alarm event is in memory (still "live", that is, not cleared, or not acknowledged). They do not get stored in the alarm journal. In addition to properties created through the Set Property block, the system also has a number of defined Runtime Properties that it may use for various purposes. Though these are used internally, they are technically still regular properties, and can be accessed and modified through the normal means.

Runtime Properties (generated for the event)

IsInitialEvent

Set to "true" when the event is caused by the initial state of the alarm.

SystemAck

Set to "true" when the alarm has been acknowledged by the system, due to an overflow of the "live event queue". Live events are alarm events that are active or not acknowledged, and are limited for each alarm by the general alarm settings.

ShelfExpiration

When the shelf will expire for this event.

IsShelved

Is the alarm currently shelved?

EventCanceled

If set, the event will drop out as soon as possible from the pipelines

EventId

The unique id (uuid) of this alarm event. Each event gets a completely unique id.

Source or Source Path

The qualified path to the item that generated this event. Includes the Tag Provider, Tag Path, and the name of the alarm. Example: prov:tagProviderName:/tag:folder/tagName:/alm:alarmName

DisplayPathOrSource

Gets the display path if defined, otherwise returns the source.

State

The current overall state of the alarm: ClearUnacked (0), ClearAcked (1), ActiveUnacked (2), ActiveAcked (3)

EventState

The transitional state that caused the current event: Active (0), Clear (1), Ack (2).

EventValue

The value associated with the current event.

AckUser

The user who acknowledged this event.

IsAcked

"True" if the event has been acknowledged.

IsActive

"True" if the event is still active.

IsClear

"True" if the event is not still active.

ActiveTime, ClearTime, AckTime

The timestamp for each event.

PipelineTransitionCount

How many transitions the event has made inside of the pipelines.

Associated Data

You can extent alarm properties by creating your own associated data. Associated data properties can be configured on any alarms that are already configured in a project.

To learn more, refer to Alarm Associated Data.

Next ...