system.alarm.queryJournal

Description

Queries the specified journal for historical alarm events. The result is a list of alarm events, which can be queried for individual properties. The result object also has a getDataset() function that can be used to convert the query results into a normal dataset, with the columns: EventId, Source, DisplayPath, EventTime, EventState, Priority, IsSystemEvent

Click here for more information on alarm properties

Syntax

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

Parameters

Date startDate - The start of the time range to query. Defaults to 8 hours previous to now if omitted. Time range is inclusive.

Date endDate - The end of the time range to query. Defaults to "now" if omitted.

String journalName - The journal name to query.

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

String[] state - A list of the event state types to match. Valid values are "ClearUnacked", "ClearAcked", "ActiveUnacked", and "ActiveAcked".

String[] path - A list of possible source paths to search at. The wildcard "*" may be used.

String[] source - A list of possible source paths to search at. The wildcard "*" may be used.

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.

Object[][] 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: "=","!=","<","<=",">",">=". Only the first two conditions may be used for string values.

Object[][] 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: "=","!=","<","<=",">",">=". Only the first two conditions may be used for string values.

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

Boolean includeData - Whether or not event data should be included in the return. If this parameter is false, and if there are no conditions specified on associated data, the properties table will not be queried.

Boolean includeSystem - Specifies whether system events are included in the return.

Boolean isSystem - Specifies whether the returned event must or must not be a system event.

Returns

List - A list of matching AlarmEvent objects. AlarmEvent objects can be examined with getAckData, getActiveData, getClearedData, getCount, getDisplayPath, getDisplayPathOrSource, getId, getLastEventState, getName, getNotes, getOrDefault, getOrElse, getPriority, getProperties, getRawValueMap, getSource, getState, getValues, isAcked, isCleared, isExtended, isInherited, and isShelved.

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

All

Code Examples

Code Snippet

#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()

Code Snippet

#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()