Skip to main content
Version: Deprecated Pages

system.alert.queryAlertHistory

caution

Ignition version 7.6 introduced a new alarming system. All of the associated functions can be found under the system.alarm section.

Description​

This function queries one of the configured Alert Storage profiles for alert history. The filter arguments help to narrow down the results to alerts that match various criteria, most commonly a range of dates. You can use * to match any number of characters and ? to match a single character in the filter string arguments.

System - The system that issued the alert.
Path - The path to the alert item.
Display Path - The custom display path (if any) for the alert. Will be the Path if no Display Path is configured.
State Name - The state name for the alert.
Severity - The severity, as a string.
Severity Code - The severity as an integer. 0-4, low-high.
Active - A boolean indicating whether this alert state is still active.
Active Timestamp - The time at which this alert went active.
Active Value - The value that triggered this alert to go active.
Cleared - A boolean indicating whether this alert has cleared.
Cleared Timestamp - The time at which this alert cleared. May be null.
Cleared Value - The value that cleared the alert.
Acked - A boolean indicating whether or not this alert was been acknowledged.
Ack Timestamp - The time that the alert was acknowledged. May be null.
Ack user - The user who acknowledged the alert.
Notes - The notes field for the alert.
Flags - A bitmask representing the current alert state. 0x01= Active, 0x02=Cleared, 0x04=Acknowledged. So if the alert is active and acknowledged, but not cleared, this will be 0x01 | 0x04 = 5

Syntax​

system.alert.queryAlertHistory(storageProfile, startDate, endDate, system, path, stateName, minSeverity, maxSeverity, activeAndUnacked, activeAndAcked, clearAndUnacked, clearAndAcked, sortOrder, displayPath)

  • Parameters

    • String storageProfile - The name of the alert storage profile to query.
    • Date startDate - Earliest alert to return. Defaults to 8 hours earlier than current time if omitted.
    • Date endDate - Latest alert to return. Defaults to current time if omitted.
    • String system - Filter string to restrict results based on the alert system.
    • String path - Filter string to restrict results based on the alert path.
    • String stateName - Filter string to restrict results based on the alert state name.
    • Integer minSeverity - Minimum severity to return. Defaults to 0 (Low).
    • Integer maxSeverity - Maximum severity to return. Defaults to 4 (High).
    • Boolean activeAndUnacked - Whether or not to return alerts that are currently active and unacknowledged. Default is true.
    • Boolean activeAndAcked - Whether or not to return alerts that are currently active and have been acknowledged. Default is true.
    • Boolean clearAndUnacked - Whether or not to return alerts that are cleared and unacknowledged. Default is true.
    • Boolean clearAndAcked - Whether or not to return alerts that are cleared and have been acknowledged. Default is true.
    • String sortOrder - The sort order in which to return matching alerts. Either "asc" or "desc", referring to the alert's active timestamp. Default is "desc".
    • String displayPath - Filter string to restrict results based on the alert's display path.
  • Returns

    • Dataset - A dataset containing the historical alert events from the given storage profile that matched the filter and date range arguments.
  • Scope

    • All

Examples​

Code Snippet
 #code would query an alert storage profile called "DBHistory", looking for the number of unacknowledged alerts in the last 36 hours, displaying the number to the user in a popup message.

from java.util import Date
from java.util import Calendar

cal = Calendar.getInstance()

end = cal.getTime()
cal.add(Calendar.HOUR, -36)
start = cal.getTime()

results = system.alert.queryAlertHistory("DBHistory", start, end,
activeAndAcked=0, clearAndAcked=0)

if results.rowCount > 0:
system.gui.messageBox("There are %d un-acked alerts!" % results.rowCount)