Skip to end of metadata
Go to start of metadata

This function is used in Python Scripting.


Queries the current state of alarms. The result is a list of alarm events, which can be queried for individual properties.

Note: Depending on the number of alarm events in the system, this function can be fairly intensive and take a while to finish executing. Which can be problematic if the application is attempting to show the results on a component (such as using this function to retrieve a count of alarms). In these cases it's preferred to call this function in a gateway script of some sort (such as a timer script), and store the results in a tag, which can easily be accessed by a component binding. 
The Tag Properties page contains more information on Alarm Properties

Client Permission Restrictions

This scripting function has no Client Permission restrictions.


system.alarm.queryStatus([priority], [state], [path], [source], [displaypath], [all_properties], [any_properties], [defined], [includeShelved])

  • Parameters

List[String] priority - A list of possible priorities to match. Priorities can be specified by name or number, with the values: Diagnostic(0), Low(1), Medium(2), High(3), Critical(4). [optional]

List[String] state - A list of states to allow. Valid values: "ClearUnacked", "ClearAcked", "ActiveUnacked", "ActiveAcked". [optional]

List[String] path - A list of possible source paths to search at. The wildcard "*" may be used. Works the same as the source argument, and either can be used. [optional]

List[String] source - A list of possible source paths to search at. The wildcard "*" may be used. Works the same as the path argument, and either can be used. [optional]

List[String] displaypath - A list of display paths to search at. Display paths are separated by "/", and if a path ends in "/*", everything below that path will be searched as well. [optional]

List[Tuple[String, String, Any] all_properties - A set of property conditions, all of which must be met for the condition to pass. This parameter is a list of tuples, in the form ("propName", "condition", value). Valid condition values: "=","!=","<","<=",">",">=". String values can only be compared using "=" and "!=" conditions. [optional]

List[Tuple[String, String, Any] any_properties - A set of property conditions, any of which will cause the overall the condition to pass. This parameter is a list of tuples, in the form ("propName", "condition", value). Valid condition values: "=","!=","<","<=",">",">=". String values can only be compared using "=" and "!=" conditions.  [optional]

List[String] defined - A list of string property names, all of which must be present on an event for it to pass. [optional]

Boolean includeShelved - A flag indicating whether shelved events should be included in the results. Defaults to false. [optional]

  • Returns

AlarmQueryResult - The AlarmQueryResult object is a list of AlarmEvent objects with some additional helper methods, see Scripting Object Reference

Additionally, each AlarmEvent inside of the AlarmQueryResult object has several built-in methods to extract alarm information. More details on these methods can be found on the Scripting Object Reference page.

This feature was changed in Ignition version 8.1.11:

As of 8.1.11, objects inside of the AlarmQueryResult object are now instances of PyAlarmEvent.

Note: Each item in the resulting list is a combination of each alarm event for the same alarm: details for when the alarm became active, acknowledged, and cleared are combined into a single item. This differs from system.alarm.queryJournal() which splits these events into separate items

  • Scope

Gateway, Vision Client, Perspective Session

Code Examples
Code Snippet - Querying Alarm Status
# This example queries the state of all tags named "HiAlarm", and puts the results in a Vision table Component named "Table" (this assumes it's being run from a button on the same screen)
#   Note that this example is simple for the sake of brevity. Normally you'll want to use system.util.invokeAsynchronous to search for alarms in a separate thread, especially so if calling
#   this function from a component based script. See the next example for more information. 
table = event.source.parent.getComponent("Table")
results = system.alarm.queryStatus(source=["*HiAlarm*"]) = results.getDataset()
Code Snippet - Call queryStatus in a Separate Thread
# In this example we'll call system.alarm.queryStatus in a separate thread, and return the results to the data property on a Vision Table component. Similar to the example above. 
#   What makes this example different is that it offers better performance when calling from a Vision component. Depending on the number of alarm events in the system, queryStatus 
#   may take a significant amount of time to finish, which would lock up a Vision Client while the script is running in the GUI thread. Thus this example will use
#   system.util.invokeAsynchronous to call queryStatus in a separate thread, and then system.util.invokeLater make any changes to our components. 

# Define a function that will retrieve alarm data in a separate thread
def getAlarms():
	# Call queryStatus to retrieve the alarm data we're looking for, and store the results in a variable. 
	#   In this case, we're looking for alarm events that contain the word "Sensor" in the source path.
	results = system.alarm.queryStatus(source=["*Sensor*"])	
	# From this same script, define a separate function that will later interact with the
	#    GUI, allowing us to move our alarm data over to a component
	# We're also using the getDataset() function on the object returned by queryStatus, 
	#   since that will provide a dataset that our table component will expect. 
	def setTheTable(alarms = results.getDataset()):
		# Replace the property reference below with a path leading to whichever property
		#    you want to move the alarm data to. 
		event.source.parent.getComponent("Table").data = alarms
	# The last thing we'll do in the separate thread is call invokeLater
	#   which will let our setTheTable function run in the GUI thread

# Call the getAlarms function in a separate thread, which starts the whole process		

Code Snippet - Querying Alarm Status Using any_properties
# The any_properties parameter allows you to filter the results for specific properties. This is useful when searching for alarms that contain associated data.

# Build a List of Tuples that represent the properties to search for. In this case, if our alarms have an Associated Data named 'Group', we can use 
# the following to search for potential values
props = [("Group", "=", "value1"), ("Group", "=", "value2")]
state = ["ActiveUnacked", "ActiveAcked"]

alarms = system.alarm.queryStatus(any_properties = props, state = state)

# Here we're printing out the number of alarms that meet our criteria. We could replace this and further examine each individual alarm in a for-loop instead. 
print len(alarms)


system alarm queryStatus, alarm.queryStatus