Skip to main content
Version: 8.1

Alarm Event Properties Reference

Alarm Event properties provide a lot of information regarding an alarm event and fall into several categories:

  • General Alarm properties
  • Event Alarm properties
  • Runtime Event properties

General Alarm properties are automatically configured with default settings when the module is first installed. Event Alarm properties are properties that occur when an event happens. Runtime Event Properties are properties that are only present while the alarm event is in memory.

Alarm Event properties are described below. If you are looking for information on the properties associated with configuring an alarm, please see the Tag Properties page.

General Alarm Properties​

General alarm properties are configured during initial setup.

  1. Go to the Configure section of the Gateway webpage, and choose Alarming > General from the menu on the left. The General Alarms Settings page will appear.
  2. Set the general alarm properties shown in the following table:

Alarm Evaluation​

PropertyDescription
Live Event LimitDefault 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​

PropertyDescription
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 EventsDefault 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 Tag Properties​

All alarm states have a list of properties that you can edit or bind when creating or editing a Tag. These are useful to know when using the system.tag.addTag() and system.tag.editTag() functions. To see the list of alarm properties that can be configured on a Tag, see the Tag Properties page.

Alarm Event 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, acknowledged).

How Properties are Used​

Properties are used in a number of ways:

  • 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.
  • 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 Active Event, Clear Event, and Acknowledge Event properties get created when the described type of event occurs. Consequently, 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 called "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.

Alarm Event Properties​

Event PropertiesBinding/Scripting NameDescriptionDatatype
NamenameThe name of the AlarmString
EnabledenabledSpecifies whether or not this alarm is evaluated by the system. Set to False to turn off the alarm state and all associated actions.Boolean
PrioritypriorityThe priority (or severity) of the alarm. Used for sorting/filtering. Numerical values are associated with each priority to make comparison easier. This property can also be referenced as a string with the following priority names.
  • Diagnostic (0)
  • Low (1)
  • Medium (2)
  • High (3)
  • Critical (4)
Integer or String
Display PathdisplayPathThe unique path of the Alarm state. Used for display and browsing purposes.String
Active PipelineactivePipelineThe pipeline (if any) that will be used to process active events generated by the alarm.String
Clear PipelineclearPipelineThe pipeline (if any) that will be used to clear events generated by the alarm. Used when the alarm goes into the Clear State.String
Active DelaytimeOnDelaySecondsThe amount of consecutive seconds that the alarm state must be True before the Tag enters this alarm state.Double
Clear DelaytimeOffDelaySecondsThe amount of consecutive seconds that the alarm state must be False before the Tag exits this alarm state.Double
NotesnotesFree-form notes for the alarm state.String

Alarm Runtime Properties​

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 by default. 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 PropertyDescriptionDatatype
IsInitialEventSet to "true" when the event is caused by the initial state of the alarm.Boolean
SystemAckSet 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.Boolean
ShelfExpirationWhen the shelf will expire for this event.Integer
IsShelvedIs the alarm currently shelved?Boolean
EventCanceledIf set, the event will drop out as soon as possible from the pipelines.Boolean
EventIdThe unique id (uuid) of this alarm event. Each event gets a completely unique id.String
Source or Source PathThe 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:alarmNameString
DisplayPathOrSourceGets the display path if defined, otherwise, returns the source.String
StateThe current overall state of the alarm. States include:
  • Clear and Unacked (0)
  • Clear and Acked (1)
  • Active and Unacked (2)
  • Active and Acked (3)
Integer
EventStateThe transitional state that caused the current event. States include:
  • Active (0)
  • Clear (1)
  • Acknowledged (2)
Integer
EventValueThe value associated with the current event.Integer
AckUserThe user who acknowledged this event.String
IsAcked"True" if the event has been acknowledged.Boolean
IsActive"True" if the event is still active.Boolean
IsClear"True" if the event is not still active.Boolean
ActiveTime, ClearTime, AckTimeThe timestamp for each event.Date
PipelineTransitionCountHow many transitions the event has made inside of the pipelines.Integer

Associated Data​

You can extend 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.

The AlarmEvent Object​

Some system functions, such as system.alarm.queryStatus, return an AlarmEvent object which contains many methods to retrieve additional information about the individual alarm. This section details the various methods on an AlarmEvent Object.

Note, many of the functions below return some complex object, as opposed to just a standard Python datatype. In these cases, normal Python type-casting can be used to turn the object into a native Python type. For example, getDisplayPath() returns a StringPath object, which can easily be converted to a Python string with the str() function.

FunctionDescriptionReturned Object
getDisplayPathReturns the Display Path of the alarm.StringPath
getDisplayPathOrSourceIf the Display Path for the alarm is in an empty string, then returns the Source Path, otherwise, returns the Display PathPython Unicode
getIdReturns the UUID of the alarm event.java.util.UUID
getLastEventStateReturns the last state of the alarm. Possible return values are Active, Acknowledged, or Cleared.
The last event is always returned, so if you're looking to see if an alarm is has been both Acknowledged and Cleared, use getState() instead.
AlarmStateTransition
getNameReturns the name of the alarm.Python Unicode
getNotesReturns the value of the Notes property. Returns a None-type object if a Note has not been configured on the Alarm.Python Unicode or None
getPriorityReturns an AlarmPriority object representing the Priority of the alarm. Can easily be converted to an Integer with .intValue. Default is String.AlarmPriority
getSourceReturns the Source path of the alarm.QualifiedPath
getStateReturns the current state of the alarm: i.e., Active, UnacknowledgedAlarmState
isAckedReturns a boolean flag indicating that the alarm has been Acknowledged.Python Boolean
isClearedReturns a boolean flag indicating that the alarm has been Cleared.Python Boolean
isShelvedReturns a boolean flag indicating that the alarm has been Shelved.Python Boolean