Skip to main content
Version: 8.1

Tag Event Scripts

Inductive University

Tag Event Scripts

Watch the video

Scripts can be attached to tags. When you edit a tag, you can navigate to the Tag Events section and click on the Edit icon to see a list of all of the available events. Those events are

  • Value Changed
  • Quality Changed
  • Alarm Active
  • Alarm Cleared
  • Alarm Acknowledged

Because tags are stored in the Gateway, they aren't scoped to a specific project. In these cases, some system functions may require that you specify a project or other resource, such as a database for the system.db.runPrepUpdate function.

note

Because these scripts are Gateway scoped, certain things like print statements will not print to the Designer console, but will print instead to the wrapper log file in Ignition's installation directory. The prefer approach to adding logging statements to Tag Event Scripts is to use the system.util.getLogger function, which will send the messages to the Gateway's Logs page.

Changed 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.

Event Options​

Once an event has been selected, note that the top of the text area is defining a function. As a result, all code that should execute when this event occurs should be indented at least once to be included in the definition.

Value Changed​

The Value Changed event is fired whenever the value of this particular tag changes. Prior to 8.1.32, this script will also fire whenever the quality or timestamp changes since tags use a QualifiedValue, which includes a value, quality, and timestamp. As of 8.1.32, this event will only trigger on the value of the tag changing, and the quality and timestamp changes are ignored. Refer to Scripting Object Reference for more information.

This event has a variety of arguments available for use in the script:

  • String tagPath - The full path to the tag. Example: [tagProvider]Folder/Folder/Tag
  • Object previousValue - The previous value. This is a qualified value, so it has value, quality, and timestamp properties.
  • Object currentValue - The current value. This is a qualified value, so it has value, quality, and timestamp properties.
  • Boolean initialChange - A boolean flag indicating whether this event is due to the initial subscription or the first execution after a tag update. The valueChanged event will have an initialChange of true if either:
    • The tag’s previous value was null, as in the first evaluation of an expression tag after a Gateway restart
    • Its previous quality was Uncertain_InitialValue. This is typically an OPC tag’s initial value before a true value is delivered from a subscription.
  • Boolean missedEvents - A flag indicating that some events have been skipped due to an event overflow.
note

The currentValue and previousValue arguments are qualified values: objects that contain a value, timestamp, and quality. This means that to get to the value of the currentValue, your script would need to access currentValue.value.

Quality Changed​

The Quality Changed event is fired whenever the quality of this particular tag changes. This event has a variety of arguments available for use in the script:

  • String tagPath - The full path to the tag. Example: [tagProvider]Folder/Folder/Tag
  • Object previousValue - The previous value. This is a qualified value, so it has value, quality, and timestamp properties.
  • Object currentValue - The current value. This is a qualified value, so it has value, quality, and timestamp properties.
  • Boolean initialChange - A boolean flag indicating whether this event is due to the initial subscription or the first execution after a Tag update.
  • Boolean missedEvents - A flag indicating that some events have been skipped due to an event overflow.

Alarm Active​

The Alarm Active event fires whenever a new active alarm event occurs. This event has a variety of arguments available for use in the script:

  • String tagPath - The full path to the tag. Example: [tagProvider]Folder/Folder/Tag
  • String alarmName - The name of the alarm. This does not include the full alarm path.
  • Object alarmEvent - The full alarm event object. The properties available to this object are:
    • eventId
    • source
    • name
    • priority
    • displayPath
    • displayPathOrSource (the display path if it is set, otherwise the source)
    • state (the current state, active/cleared + acked/unacked)
    • eventState (the last transition, active, clear, acknowledged)
    • isClear (a boolean if the alarm is currently cleared)
    • isAcked (a boolean if the alarm is currently acknowledged)
    • isShelved (a boolean if the alarm is currently shelved)
    • notes
  • String alarmPath - The full alarm path.
  • Boolean missedEvents - A flag indicating that some events have been skipped due to an event overflow.

Alarm Cleared​

The Alarm Cleared event fires whenever an alarm becomes cleared on the tag.This event has a variety of arguments available for use in the script:

  • String tagPath - The full path to the tag. Example: [tagProvider]Folder/Folder/Tag
  • String alarmName - The name of the alarm. This does not include the full alarm path.
  • Object alarmEvent - The full alarm event object. See the Alarm Active alarmEvent object for the full list of available properties.
  • String alarmPath - The full alarm path.
  • Boolean missedEvents - A flag indicating that some events have been skipped due to an event overflow.

Alarm Acknowledged​

The Alarm Acknowledged event fires whenever an alarm event becomes acknowledged on the Tag. This event has a variety of arguments available for use in the script:

  • String tagPath - The full path to the tag. Example: [tagProvider]Folder/Folder/Tag
  • String alarmName - The name of the alarm. This does not include the full alarm path.
  • Object alarmEvent - The full alarm event object. See the Alarm Active alarmEvent object for the full list of available properties.
  • String alarmPath - The full alarm path.
  • String ackedBy - The full path to the user that acknowledged the alarm.
  • Boolean missedEvents - A flag indicating that some events have been skipped due to an event overflow.

Using the Project Library in a Tag Event Script​

Scripts defined in a project script can be called from a Tag Event Script. However, only scripts defined in the Gateway Script Project may be used. For more information on configuring the Gateway Scripting Project, please see the Project Library page.

UDT Parameters in Tag Event Scripts​

Parameters on UDTs can be interacted with from Tag Event Scripts. There are two main approaches.

Modern Approach​

Parameters values can be accessed as dictionary values. The benefit of this approach is that value changes to UDT parameters will be reflected in subsequent calls. In most cases, this modern approach is preferable. Thus, if the script needs to access the most recent parameter values on a UDT, and the parameters can change through a means other than editing the UDT (which would restart the tag), then this approach should be used.

If trying to access the value of a parameter named "myParam" from a Tag Event Script within the UDT, the script would look like:

# Reminder: "tag" is a built-in argument on all Tag Event Scripts. 
# Accessing the "parameters" key on the tag argument will
# provide access to all UDT parameters.
paramValue = tag['parameters']['myParam']

Legacy Approach​

In Ignition release 7.9 and prior, UDT parameters could be access in Tag Event Scripts with the familiar curly brackets approach. Thus, if trying to access the value of a parameter named "myParam" from a Tag Event Script within the UDT, the script would look like:

paramValue = {myParam}

A large caveat with this approach is that value changes made to the parameter ("myParam", in the example above) would not be reflected in scripts until the UDT was restarted. UDT parameters are pre-compiled, which in this case means value changes are mostly ignored until the UDT is restarted.

In all cases, the modern approach above is preferred.

Tag Script Examples​

Printing All Parameters
# This script will fetch all of the possible parameters in the Tag Changed Script.
# Note that this will not print out to the console, but it will print to the wrapper logs located on the Gateway.
 
path = tagPath
prev = previousValue
cur = currentValue
init = initialChange
missed = missedEvents
print path, prev.value, cur.quality, init, missed
Automatic Reset
# This code can be used on a Value Changed script, and will automatically reset the value of the tag to 0 after it goes above 3000.
# This can be useful for counter tags.
if currentValue.value > 3000:
    system.tag.writeBlocking(["[default]IntegerCounterTag"], [0])
Copy to Another Tag
# This code can be used on a Value Changed script, and will record the highest value of the current tag onto another memory tag.
# This can be useful for recording the highest temperature.
highestRecordedTemp = system.tag.readBlocking(["[default]HighestTempTag"])[0].value
if currentValue.value > highestRecordedTemp:
    system.tag.writeBlocking(["[default]HighestTempTag"], [currentValue.value])

Troubleshooting​

It may be helpful when troubleshooting or testing Tag Event Scripts to increase the default threadpool count. Refer to the Gateway Configuration File Reference - Threadpool Counts for more information.

Last updated on by ia-nboehnke