Alarm Event Properties Reference

An alarm event is made up of many pieces of information. The state, value, time, and configuration data for the alarm are collectively known as the properties of the event. Alarm event properties fall into two categories:

• Alarm event properties, which are created when an alarm becomes active, cleared, or acknowledged.
• Alarm runtime properties, which exist only while the alarm event is in memory.

You can extend either category with your own associated data, which can be configured on any alarm that already exists in a project. To learn more, see Alarm Associated Data.

For the properties you set when configuring an alarm, see the Tag Alarm Properties page. For the alarm settings that apply to the entire Gateway, see the Gateway General Alarm Properties page.

Alarm event properties define how an alarm behaves, and you can reference them in:

• Messages, such as the body of an email or SMS message.
• Expressions, such as the binding of a different property, or an Expression block.
• Alarm pipelines, where they can also be created as temporary variables, such as a counter.
• Scripts, such as a Script block in an alarm pipeline.

Reference a property by wrapping its binding or scripting name in curly brackets. For example, {name} returns the name of the alarm, and {eventValue} returns the value associated with the event. Expressions can also retrieve a property with the getProperty() function.

Properties are always referenced the same way, but the value you get back depends on where that value comes from, and how long it lasts. An alarm event holds active event properties, clear event properties, acknowledged event properties, and runtime properties. The active, clear, and acknowledged properties are created when that type of event occurs, so the same property can exist more than once within a single alarm event. A bound configuration property or associated data, for example, is captured on both the active and clear events. When you reference a property, the alarm event returns the most recent value, so referencing a bound property named MyData while the alarm is active can return a different result than referencing it after the alarm clears. The Alarm Journal stores the individual values separately.

Alarm Event Properties

Event Properties	Binding/Scripting Name	Description	Datatype
Name	name	The name of the Alarm.	String
Enabled	enabled	Specifies whether or not this alarm is evaluated by the system. Set to False to turn off the alarm state and all associated actions.	Boolean
Priority	priority	The 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 Path	displayPath	The unique path of the Alarm state. Used for display and browsing purposes.	String
Active Pipeline	activePipeline	The pipeline (if any) that will be used to process active events generated by the alarm.	String
Clear Pipeline	clearPipeline	The 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 Delay	timeOnDelaySeconds	The amount of consecutive seconds that the alarm state must be True before the tag enters this alarm state.	Double
Clear Delay	timeOffDelaySeconds	The amount of consecutive seconds that the alarm state must be False before the tag exits this alarm state.	Double
Notes	notes	Free-form notes for the alarm state.	String

Alarm Runtime Properties

Runtime properties exist only while the alarm event is live, meaning it has not yet cleared or been acknowledged. They are not stored in the Alarm Journal by default. In addition to the properties you create through the Set Property block, the system defines the runtime properties below. The system uses these internally, but they are still regular properties, so you can access and modify them through the normal means.

Runtime Property	Description	Datatype
IsInitialEvent	Set to true when the event is caused by the initial state of the alarm.	Boolean
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.	Boolean
ShelfExpiration	When the shelf will expire for this event.	Integer
IsShelved	Whether the alarm is currently shelved.	Boolean
EventCanceled	If set, the event will drop out as soon as possible from the pipelines.	Boolean
EventId	The unique id (uuid) of this alarm event. Each event gets a completely unique id.	String
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	String
DisplayPathOrSource	Gets the display path if defined, otherwise, returns the source.	String
State	The 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
EventState	The transitional state that caused the current event. States include: Active (0) Clear (1) Acknowledged (2)	Integer
EventValue	The value associated with the current event.	Integer
AckUser	The 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, AckTime	The timestamp for each event.	Date
PipelineTransitionCount	How many transitions the event has made inside of the pipelines.	Integer

The PyAlarmEvent Object

Some system functions, such as system.alarm.queryStatus(), return PyAlarmEvent objects. Each PyAlarmEvent object contains methods that retrieve additional information about an individual alarm.

Many of these methods return a complex object instead of a standard Python datatype. In these cases, normal Python type casting turns the object into a native Python type. For example, getDisplayPath() returns a StringPath object, which the str() function converts to a Python string.

The following example prints the display path, state, and acknowledgement status of each active alarm:

Read Properties from Active Alarms

results = system.alarm.queryStatus(state=["ActiveUnacked", "ActiveAcked"])

for alarm in results:
    print str(alarm.getDisplayPath()), alarm.getState(), alarm.isAcked()

Function	Description	Returned Object
getDisplayPath	Returns the Display Path of the alarm.	StringPath
getDisplayPathOrSource	If the Display Path for the alarm is in an empty string, then returns the Source Path, otherwise, returns the Display Path	Python Unicode
getId	Returns the UUID of the alarm event.	java.util.UUID
getLastEventState	Returns 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
getName	Returns the name of the alarm.	Python Unicode
getNotes	Returns 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
getPriority	Returns an AlarmPriority object representing the Priority of the alarm. Can easily be converted to an Integer with .intValue. Default is String.	AlarmPriority
getSource	Returns the Source path of the alarm.	QualifiedPath
getState	Returns the current state of the alarm: i.e., Active, Unacknowledged	AlarmState
isAcked	Returns a boolean flag indicating that the alarm has been Acknowledged.	Python Boolean
isCleared	Returns a boolean flag indicating that the alarm has been Cleared.	Python Boolean
isShelved	Returns a boolean flag indicating that the alarm has been Shelved.	Python Boolean

For the full list of methods, including the methods available to Script blocks in alarm pipelines, see the PyAlarmEvent section of the Scripting Object Reference page.