Skip to main content
Version: 8.1

Tag Alarm Properties

Changed in 8.1.17

In 8.1.17, the Tag Editor was redesigned to improve usability. The new Tag Editor now requires fewer clicks and keeps relevant tag information visible while modifying bindings, alarms, and event scripts. Pages detailing features of the previous Tag Editor can be found in Deprecated Ignition Features.

Alarm Property Reference

The table in this section provides a description of alarm properties. The descriptions of these properties can also be viewed in the Tag Editor > Alarms popup by selecting the Show/Hide Description Area icon available above the property list.

Alarms in Scripting

When interacting with the tags system in via scripting, such as with the system.tag.configure function, alarms are represented as a JSON array of JSON objects, where each object contains the configurations for a single alarm. Thus, any scripting names here are assumed to exist under the alarms array.

Main Alarm Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
NamenameIdentifier of the alarm. Combined with the location of the alarm, this will be the unique alarm ID. For dynamic values, used Label or Display Path.StringOPC, Query, Expression, Derived, Reference, Memory
EnabledenabledThis boolean determines whether or not the alarm will be evaluated. A disabled alarm's condition will not be evaluated, and thus will not generate any alarm events.BooleanOPC, Query, Expression, Derived, Reference, Memory
PrioritypriorityThe priority or severity of this alarm. Alarm priorities can be examined by many other systems in Ignition, including the visualization modules, pipelines, and even scripting. Possible values are along with their JSON names are listed below:

  • Diagnostic Diagnostic
  • Low Low
  • Medium Medium
  • High High
  • Critical Critical
.
StringOPC, Query, Expression, Derived, Reference, Memory
Timestamp SourcetimestampSourceIndicates where the timestamp for the alarm event should come from: the system time of when the event was generated (i.e., the Gateway's time), or the timestamp of the value that triggered the the event (i.e., the timestamp of the value from the OPC server). See the list below for listing of possible values, including their JSON name and numeral representation:

  • System System : 0
  • Value Value : 1
.
StringOPC, Query, Expression, Derived, Reference, Memory
LabellabelAn optional name that will be used for display purposes. Provides a dynamic alternative to the static name property. If left blank, the name will be used.StringOPC, Query, Expression, Derived, Reference, Memory
Display PathdisplayPathOptional text that will be used for display and browsing purposes. If this is blank, this property will show the path to the Tag and the name of the alarm instead.StringOPC, Query, Expression, Derived, Reference, Memory
Ack ModeackModeDictates how acknowledgement works for the alarm. Possible values are listed below, along with their JSON name and numerical representation:

  • Unused Unused - 0
  • Auto Auto - 1
  • Manual Manual - 2
StringOPC, Query, Expression, Derived, Reference, Memory
NotesnotesA place for any free-form documentation about the alarm that can be displayed to users.StringOPC, Query, Expression, Derived, Reference, Memory
Ack Notes RequiredackNotesReqdIf this setting is true, the operators will be required to provide some explanation when the alarm is acknowledged.BooleanOPC, Query, Expression, Derived, Reference, Memory
Shelving AllowedshelvingAllowedIf this setting is false, the shelving feature will be unavailable for this alarm.BooleanOPC, Query, Expression, Derived, Reference, Memory

Alarm Mode Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
ModemodeThis setting controls what condition this alarm is evaluating. See the listing below for a description of possible modes:

  • Equal Equality - Active when the Tag's value equals the alarm's setpoint.
  • Not Equal Inequality - Active when the Tag's value does not equal the alarm's setpoint.
  • Above Setpoint AboveValue - Active when the Tag's value is above the alarm's setpoint.
  • Below Setpoint BelowValue - Active when the Tag's value is below the alarm's setpoint.
  • Between Setpoints BetweenValues - 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 OutsideValues - Active when the Tag's value falls outside the low and high setpoints. If any change is true, an event will be generated for each value change outside the setpoints.
  • Out of Range OutOfEngRange - The same as Outside Setpoints, but uses the Tag's Engineering High and Engineering Low as the high and low setpoints.
  • Bad Quality BadQuality - Active if the Tag value becomes a bad quality, for example, on communication loss.
  • Any Change AnyChange - An alarm event is generated every time the Tag value changes. Note: This alarm will never be "active" because each active event is paired with a matching clear event, instantly.
  • Bit State Bit - 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 OnCondition - 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.
StringOPC, Query, Expression, Derived, Reference, Memory
Setpoint/Low SetpointsetpointAUsed to determine if the alarm is active by comparing this value to the the tag value.

Some modes under the Mode property allow for multiple setpoints (i.e., a low setpoint and a high setpoint). In these cases, this property is considered to be the Low setpoint.

Note: Setpoints must be numerical values, not string representations of numbers. If a string is passed to a setpoint then it will be converted to a numeric value of 0.
NumericOPC, Query, Expression, Derived, Reference, Memory
InclusiveinclusiveAIf true, the Setpoint value is used inclusively for the condition to alarm.BooleanOPC, Query, Expression, Derived, Reference, Memory
High SetpointsetpointBThe high value used to initiate an alarm when the alarm mode calls for two setpoints. Available for modes: Between Setpoint, Outside Setpoints.

Note: Setpoints must be numerical values, not string representations of numbers. If a string is passed to a setpoint then it will be converted to a numeric value of 0.
NumericOPC, Query, Expression, Derived, Reference, Memory
High InclusiveinclusiveBIf true, the High Setpoint value is used inclusively for the condition to alarm. Available for modes: Between Setpoint, Outside Setpoints.BooleanOPC, Query, Expression, Derived, Reference, Memory
Any ChangeanyChangeIf true, will alarm on each value change given the alarm mode conditions are met.

Note: This alarm will never be "active" because each active event is paired with a matching clear event, instantly. Available for modes: Above Setpoint, Below Setpoint, Between Setpoints, and Outside Setpoints.
BooleanOPC, Query, Expression, Derived, Reference, Memory
On ZerobitOnZeroIf true, will alarm when the specified bit is not high (when the bit is 0).BooleanOPC, Query, Expression, Derived, Reference, Memory
Bit PositionbitPositionThe position of the bit, starting at 0 that will be watched. Available for modes: Bit State.NumericOPC, Query, Expression, Derived, Reference, Memory
Is ActiveactiveConditionWhen this property is active, the alarm will be active. Typically has a binding of some sort that will be used to determine when the alarm goes active. If the expression evaluates to True, the alarm is active. If the expression evaluates to False, the alarm is not active.BooleanOPC, Query, Expression, Derived, Reference, Memory

Deadbands and Time Delay Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
DeadbanddeadbandThe value for the deadband, interpreted according to the Deadband mode.

Note: All alarms are only evaluated after the Tag's value changes, which means that the Tag's own deadband will be considered first.

When the deadband is positive, an active alarm condition needs to clear its setpoint(s) by the amount of the deadband for the alarm to clear. For example, suppose you had a Between Setpoints alarm with a low setpoint of 50 and a high setpoint of 70, and with a deadband of 2. The alarm will go active if the value is between 50 and 70, but will only clear if the value falls below 48 or rises above 72.
NumericOPC, Query, Expression, Derived, Reference, Memory
Deadband ModedeadbandModeDefines how the deadband value is used. Possible values are listed below along with their JSON name and a description.

  • Absolute Absolute : The deadband setting is considered to be an absolute value.
  • Percent Percent : The actual deadband is calculated as a percent of the Tag's engineering unit span.
  • Off Off :
    New in 8.1.2
    The deadband setting is the equivalent to a value of 0.0, so that all values pass through if their timestamp has changed.
NumericOPC, Query, Expression, Derived, Reference, Memory
Active DelaytimeOnDelaySecondsThe time, in seconds, before the alarm will be considered active after the alarm's condition becomes true. Also known as a "rising edge time deadband."Numeric
Clear DelaytimeOffDelaySecondsThe time, in seconds, before an active alarm will be considered clear after the alarm's condition becomes false. Also known as a "falling edge time deadband."NumericOPC, Query, Expression, Derived, Reference, Memory

Notification Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
Active PipelineactivePipelineThe name of an alarm notification pipeline to put this alarm into when it becomes active in order to send out active alarm messages. Many alarms may share a single pipeline.StringOPC, Query, Expression, Derived, Reference, Memory
Clear PipelineclearPipelineThe name of an alarm notification pipeline to put this alarm into when it becomes cleared in order to send out cleared messages.StringOPC, Query, Expression, Derived, Reference, Memory
Ack PipelineackPipelineThe name of the alarm notification pipeline to put this alarm into when the alarm has been acknowledged.StringOPC, Query, Expression, Derived, Reference, Memory

Phone Call Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
Custom Messagevoip.customMessageThe voice message you want to play when sending the Alarm. See Configuring Messages for more information on custom phone messages.StringOPC, Query, Expression, Derived, Reference, Memory

Email Notification Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
Custom SubjectCustomEmailSubjectA string that will be used as the subject line of an email notification message. If blank, the message settings defined on the notification block that sent the email out will be used instead.StringOPC, Query, Expression, Derived, Reference, Memory
Custom MessageCustomEmailMessageA string that will be used as the body of this alarm's email notification message. If blank, the message settings defined on the notification block that sent the email out will be used instead. Supports HTML tags such as <html>, <body>, <h1>, etc.StringOPC, Query, Expression, Derived, Reference, Memory

SMS Notification Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
Custom MessageCustomSmsMessageIf specified, will be used for the SMS message. If blank, the message defined in the notification block will be used.StringOPC, Query, Expression, Derived, Reference, Memory

Associated Data Properties

Property NameJSON/Scripting NameDescriptionDatatypeApplicable Tag Type
User Defined DataN/AAssociated Data are custom alarm properties that can be added to any alarm. These properties will often be bound to other Tags that represent associated contextual data that may be related to the alarm. A snapshot of the values of these properties will be taken when the alarm becomes active. These values will be attached to the alarm event as it moves through the rest of the alarming system, meaning that the values will be available from the alarm status system, the alarm journal system, and in the alarm notification system.StringOPC, Query, Expression, Derived, Reference, Memory

Runtime Alarm Metric Properties

The Alarms property under a tag in the Tag Browser contains properties that report the current state of alarms on the tag.

Property NameDescription
ActiveAckCountThe number of alarms on the Tag that are both active and acknowledged.
ActiveUnackCountThe number of alarms on the Tag that are both active and unacknowledged.
ClearUnackCountThe number of alarms on the Tag that are both clear and unacknowledged.
HasActiveTrue, if the Tag has at least one active alarm. False, if there are zero alarms.
HasUnacknowledgedTrue, if the Tag has at least one unacknowledged alarm. False, if there are zero unacknowledged alarms.
HighestAckedNameThe Name of the highest acknowledged alarm, ranked by Priority.
HighestAckedPriorityThe highest Priority of all acknowledged alarms on the Tag.
HighestActiveNameThe Name of the highest active alarm, ranked by Priority.
HighestActivePriorityThe highest Priority of all active alarms on the Tag.
HighestUnackedNameThe Name of the highest unacknowledged alarm, ranked by Priority.
HighestUnackedPriorityThe highest Priority of all unacknowledged alarms on the Tag.
LastActiveTimeA timestamp representing the last time an alarm went active on the Tag.
ShelvedCountThe number of currently shelved alarms on the Tag.

Runtime Alarm Metrics for Individual Alarms

In addition to the metrics above, each alarm configured on a tag has further properties that are available. These properties are located after ShelvedCount. For each alarm on a tag, additional expandable items will be visible in the property editor. The name on these items will match the name of their associated alarm.

In the image below, the parent tag has two alarms configured, one named High Setpoint Alarm, the other named Low Setpoint Alarm. Because the tag has two alarms, we see two expandable entries towards the bottom of the image, with names that match the names of the alarms.

Expanding these items will reveal additional properties, as listed in the table below.

Property NameDescription
AckTimeIf the most recent alarm event for this alarm has been acknowledged, then this property will show a timestamp representing when acknowledgement occurred. If the most recent alarm event has not yet been acknowledged, the value of this property will be null.
AckUserIf the most recent alarm event for this alarm has been acknowledged, then this property will show the username that acknowledged the alarm event. Otherwise the value of this property we be null. If the alarm event was acknowledged by the system, such as when the Alarm Mode is set to Auto, then the property will show a null value.

If the user that acknowledged the alarm event was authenticated via a User Source, then the value will follow the pattern below, where X is the name of the User Source, and Y is the name of the user.

usr-prov:X:/usr:Y

If the user that acknowledged the alarm event was authenticate via an Identity Provider, then the value will follow the pattern below, where Y is the name of the user.

usr:Y
AckUserNameIf the most recent alarm event for this alarm has been acknowledged, then this property will show the username that acknowledged the alarm event. Otherwise the value of this property we be an empty string.If the alarm event was acknowledged by the system, such as when the Alarm Mode is set to Auto, then the property will show an empty string. This property is effectively a simplified version of AckUser, containing only the username.
ActiveTimeShows a timestamp representing when the most recent alarm event became active.
ClearTimeShows a timestamp representing when the most recent alarm event transitioned from an active state to a clear state.
DisplayPathRepresents the value of the Display Path property on the alarm.
DisplayPathOrSourceShows the display path if one has been configured. Otherwise shows the source path.
EnabledRepresent whether or not this alarm is enabled.
EventStateRepresents the most recent state transition. A listing of states and their numerical values are listed below:

  • Active : 0
  • Clean : 1
  • Acknowledge : 2
EventTimeA timestamp representing when the event last changed state.
EventValueRepresents the last value that made the alarm event transition to either active or cleared.
IsAckedA boolean representing whether or not the most recent alarm event has been acknowledged.
IsActiveA boolean representing whether or not the most recent alarm event is active.
IsClearA boolean representing whether or not the most recent alarm event is cleared.
IsShelvedA boolean representing whether or not the alarm has been shelved.
LabelA string representing the Label property on the alarm. Shows a null value if a Label wasn't defined.
NameThe name of the alarm.
PriorityThe priority of the alarm. A listing of priorities and numerical values are listed below:

  • Diagnostic : 0
  • Low : 1
  • Medium : 2
  • High : 3
  • Critical : 4
SetpointAWhen the Mode property on the alarm has a single setpoint, this property shows the setpoint value. When the Mode property has multiple setpoints, this represents the Low Setpoint property.
SetpointBWhen the Mode property on the alarm has a single setpoint, this property is hidden. When the Mode property has multiple setpoints, this represents the High Setpoint property.
SourceThe source path of the alarm.
StateThe state of the alarm. A listing of states and their numerical values are listed below:

  • Clear and Unacked : 0
  • Clear and Acked : 1
  • Active and Unacked : 2
  • Active and Acked : 3

Binding

Many alarm properties are bindable, which means they can be bound to other tags in the system, or expressions. For example, you might bind the enabled property to another tag which represents whether or not your process is running, thereby, disabling the alarm when production is stopped. Another example is you might bind the setpoint of an alarm to a tag that operators can manipulate, thereby, letting the setpoint be changed at runtime. For more information, see Configuring Alarms.

To bind an alarm property of a tag:

  1. Click on the binding icon. An Alarm Binding popup window will appear.


  2. From this window, you can select a Binding Type to configure a Tag or an Expression binding. For this example, let's select Expression. Binding to an Expression can reference many useful values such as the tag's value and other settings of the alarm.


  3. Now, enter your expression, using the Operators , Functions , Tags , and Alarm Properties selections as needed.
    note

    The alarm properties that can be selected using the Alarm Properties icon are the properties included in the Tag Editor > Alarms window or under the tag in the Tag Browser. See the Reference Table section and the Runtime Alarm Metric Properties section for descriptions of these properties. The State properties will only be available to view after alarming is enabled on the tag.



  4. When you configured the binding to your liking, click Apply.