Reading Tag Quality in Ignition 8.1 Change Event Scripts

Overview

In Inductive Automation Ignition 8.1, the currentValue object exposed inside a Tag Change event script is a QualifiedValue wrapper. It carries three fields engineers routinely need: value, quality, and timestamp. The quality field is not a string — it is a com.inductiveautomation.ignition.common.model.values.QualityCode object. Writing if currentValue.quality != 'Good': raises a type error and silently aborts the script, because the Jython runtime cannot coerce a QualityCode enum to a java.lang.String. This article shows the supported access patterns, the underlying API surface, and the version gating that controls IntelliSense for these members.

The behavior documented here is a direct consequence of how the Quality Codes and Overlays subsystem models tag health: each tag evaluation produces a discrete code from a fixed enumerator, and scripting layers receive the typed enum rather than a serialized label. Scripts written against the older string-comparison idiom (pre-8.1) must be updated when migrating.

Prerequisites

• Ignition Gateway 8.1.18 or later. QualityCode IntelliSense (code completion for isGood(), isBad(), .good, .bad, etc.) ships with the nightly build line that became the 8.1.18 release. Earlier 8.1.x versions expose the methods at runtime, but the Designer script editor will not present them in the autocomplete dropdown.
• A tag configured in the Tag Browser, with a UDT instance or atomic tag whose Value Changed event script is editable.
• Designer Client permissions to edit tag event scripts (typically Authenticated User with Designer write access to the tag provider).
• Jython 2.7 runtime knowledge — Ignition's script engine is Jython, not CPython. Imports use java.* namespaces.

The QualityCode Type Explained

The quality field on currentValue is an instance of com.inductiveautomation.ignition.common.model.values.QualityCode, an enum-like class that encodes the OPC UA status code semantics. It is the same type returned by system.tag.readBlocking(...).quality and the TagQuality column in Power Tables bound to historical queries.

The class exposes the following members engineers will use in change-event scripts:

The property form (currentValue.quality.good) is preferred over the method form (currentValue.quality.isGood()) when called inside tight event loops, since each Jython-to-Java method call incurs a runtime thunk. The performance difference is negligible per call, but accumulates on tag-change storms from 10k+ point scans.

Step-by-Step: Building a Quality-Gated Change Script

The following procedure replaces the broken if currentValue.quality != 'Good': pattern with a correct, version-safe implementation.

1. Open the Tag's Value Changed Event

1. In the Designer, expand the Tag Browser and navigate to the target tag or UDT instance.
2. Right-click → Edit Tag (or double-click).
3. Select the Events tab.
4. Expand Value Changed and click the Script Editor pen icon.

2. Use the Property Form (Recommended)

Write the guard clause using the boolean property accessor:

if not currentValue.quality.good:
    # Bail out before acting on a stale or invalid value
    system.tag.writeBlocking(['[default]Diagnostics/LastBadQuality'], currentValue.quality.toString())
    return

# Quality is Good — proceed with normal logic
newValue = currentValue.value
log.info("Tag updated to {}", newValue)

This pattern runs on every tag change, including quality changes themselves. Per the Tag Event Scripts training video, the Value Changed script fires on any subscription update — value, quality, or timestamp — so quality-only transitions will also reach this code path. The early return short-circuits stale-data work without raising an exception.

3. Use the Method Form (Compatible with Older 8.1.x)

If you must support gateways older than 8.1.18 (where the IntelliSense is incomplete but the runtime call still works), use the explicit method:

if not currentValue.quality.isGood():
    return

Both forms are functionally equivalent. Pick one style per project for grep-ability.

4. Distinguish Specific Bad Reasons

When you need to react differently to Bad_CommunicationError versus Bad_DeviceFailure, branch on the code integer or the name:

q = currentValue.quality
if q.bad:
    codeInt = q.getCode()
    if (codeInt & 0xFFFF0000) == 0x80040000:
        # Bad_DeviceFailure sub-range
        system.alarm.raiseSystemAlarm("Device failure on {}".format(tag.tagPath))
    elif (codeInt & 0xFFFF0000) == 0x80050000:
        # Bad_CommunicationError sub-range
        system.alarm.raiseSystemAlarm("Comm loss on {}".format(tag.tagPath))
    return

The bit-mask check (codeInt & 0xFFFF0000) extracts the OPC UA severity/subcode group, allowing you to bucket all Bad_ConfigurationError instances together without enumerating each constant.

Common QualityCode Values Reference

The full enumeration is published in the Quality Codes and Overlays manual page and mirrored in the SDK Javadoc for the QualityCode class.

Verification

To confirm the script behaves correctly across quality transitions:

1. Open the Tag Browser and locate the target tag.
2. Expand the tag and scroll to the meta.Quality property — this is the same QualityCode surfaced to the script, as documented in the Reading and Writing Tags course.
3. Force a Bad quality by disabling the upstream device or simulating a comms loss. The script should run and the early-return path should fire.
4. Restore communications. The script should run again on the Good transition.
5. Check the gateway log for the log.info entry — its presence confirms execution reached the success branch.

For a non-destructive test, bind a numeric tag to a derived expression that returns Bad_ConfigurationError temporarily, and watch the diagnostic tag you wrote to in step 2 of the procedure above.

Troubleshooting Matrix

Performance Notes for High-Frequency Tags

On scan classes faster than 100 ms, or arrays of tags, the currentValue.quality dereference still costs one Jython-to-Java hop. If the change event performs only logging, consider:

• Short-circuiting with if not currentValue.quality.good: return at the very top — avoid any Python string formatting in the bad path.
• Deferring heavy logic (database writes, alarm raises) to a system.util.invokeLater call so the subscription thread is not blocked.
• Using previousValue.quality comparisons to detect quality transitions rather than evaluating on every update.

Working Code: Quality-Transition Logger

A complete, field-tested pattern for logging only when quality flips from Good to anything else, or vice versa:

prev = previousValue.quality
curr = currentValue.quality

if prev.good and not curr.good:
    # Quality degraded
    log.warn("Tag {} went Bad: {}", tag.tagPath, curr.toString())
    system.tag.writeBlocking(['[default]Diagnostics/QualityFlips'],
                             system.tag.readBlocking(['[default]Diagnostics/QualityFlips'])[0].value + 1)
elif not prev.good and curr.good:
    # Quality recovered
    log.info("Tag {} recovered to Good", tag.tagPath)

# Normal value handling below
if not curr.good:
    return

newValue = currentValue.value
# ... downstream logic ...

Storing the flip counter as a tag makes the script's effect visible in the Tag Browser, which is invaluable during commissioning and SAT (Site Acceptance Testing).

FAQ