Skip to main content
Version: 8.1

system.alarm.queryJournal

This function is used in Python Scripting.

Description

Queries the specified journal for historical alarm events. The result is a list of alarm events, which can be parsed for individual properties.

Click here for more information on alarm properties.

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

system.alarm.queryJournal([startDate], [endDate], [journalName], [priority], [state], [path], [source], [displaypath], [all_properties], [any_properties], [defined], [includeData], [includeSystem], [includeShelved], [isSystem], [provider])

Parameters

TypeParameterDescription
DatestartDateThe start of the time range to query. Defaults to 8 hours previous to now if omitted. Time range is inclusive. [optional]
DateendDateThe end of the time range to query. Defaults to "now" if omitted. [optional]
StringjournalNameThe journal name to query. If only one journal exists on the Gateway, can be omitted. [optional]
List[Integer / String]priorityA 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[Integer / String]stateA list of event states to match. Valid values can either be integers or strings, representing a number of states. See State Values for a listing of possible values. [optional]
List[String]pathA list of possible source paths to search at. The wildcard "*" may be used. [optional]
List[String]sourceA list of possible source paths to search at. The wildcard "*" may be used. [optional]
List[String]displaypathA 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_propertiesA 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 propName values can be either associated data or the keys listed on the PyAlarmEvent object. Valid condition values: "=","!=","<","<=",">",">=". String values can only be compared using "=" and "!=" conditions. [optional]
List[Tuple[String, String, Any]any_propertiesA set of property conditions, any of which will cause the overall condition to pass. This parameter is a list of tuples, in the form ("propName", "condition", value). Valid propName values can be either associated data or the keys listed on the PyAlarmEvent object. Valid condition values: "=","!=","<","<=",">",">=". String values can only be compared using "=" and "!=" conditions. [optional]
List[String]definedA list of string property names, all of which must be present on an event for it to pass. [optional]
BooleanincludeDataWhether or not event data should be included in the return. If True, returns Python dictionaries (or nulls) for Active Data, Clear Data, Ack Data, Runtime Data inside of the AlarmQueryResult object. [optional]
BooleanincludeSystemSpecifies whether system events are included in the return. [optional]
BooleanincludeShelvedA flag indicating whether shelved events should be included in the results. Defaults to false. [optional]
BooleanisSystemSpecifies whether the returned event must or must not be a system event. [optional]
List[String]providerA list of tag providers to include in the query. Omitting this parameter will query all providers. [optional]

Returns

AlarmQueryResult - The AlarmQueryResult object is a list of PyAlarmEvent objects. See Scripting Object Reference.

Additionally, each PyAlarmEvent 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.

Changed in 8.1.11
As of 8.1.11, objects inside of the AlarmQueryResult object are now instances of PyAlarmEvent. Formerly they were AlarmEvent objects.
Important

Each item in the resulting list is a separate alarm event: an alarm becoming active is one item, while the same alarm becoming acknowledged is a separate item. This differs from system.alarm.queryStatus() which groups each event into a single item.

Scope

Gateway, Vision Client, Perspective Session

State Parameter Values

String RepresentationInteger Representation
ClearUnacked0
ClearAcked1
ActiveUnacked2
ActiveAcked3

As of 8.1.8, state now accepts Enabled and Disabled as valid values, allowing the function to match on events where alarms were enabled or disabled (requires that Stored Enabled & Disabled Events is enabled)

String RepresentationInteger Representation
Enabled4
Disabled5

Code Examples

Example #1
# This example shows the basic syntax for querying from the journal in a button's actionPerformed event, with a date range selector ("Range"), storing the results back to a table called "Table":

table = event.source.parent.getComponent("Table")
range= event.source.parent.getComponent("Range")

results = system.alarm.queryJournal(journalName="Journal", startDate=range.startDate, endDate=range.endDate)
table.data = results.getDataset()
Example #2
# This example extends the previous to only include non-acknowledged events of High or Critical severity, who have associated data called "Department", set to "maintenance". It also excludes system events (shelving notifications, etc):

table = event.source.parent.getComponent("Table")
range= event.source.parent.getComponent("Range")

results = system.alarm.queryJournal(journalName="Journal", startDate=range.startDate, endDate=range.endDate, state=['ActiveUnacked', 'ClearUnacked'], all_properties=[("Department","=","maintenance")], priority=["High", "Critical"], includeSystem=False)
table.data = results.getDataset()
Example #3
# Iterating through results

end = system.date.now()
start = system.date.addHours(end, -1)

data = system.alarm.queryJournal(startDate = start, endDate = end)

# Convert the results into a PyDataSet, since they're easy to iterate through
pyData = system.dataset.toPyDataSet(data.getDataset())

for row in pyData:
print row["DisplayPath"], " - ", row["EventState"]
Example #4
# Using any_properties (OR operator)

defined = ["DisplayPath", "Source"]
props = [
("DisplayPath","=","yo"),
("Source","Like","*Write*")
]

results = system.alarm.queryStatus(any_properties=props)

print len(results)
for r in results:
print r['source']
Example #5
# Using all_properties (AND operator)

props = [
("EventId","=","9bb7e0ee-011b-4f37-8e07-e54706e11852"),
("Priority","=","Medium"),
("EventTime", "=", "Jan 04 17:07:12 UTC 2022")
]
results = system.alarm.queryJournal(all_properties=props)