Skip to main content
Version: 8.1

Scripting Object Reference

The following sections describe the structure of some prominent objects returned or expected by Ignition system functions. Not all classes, fields, and methods are included in the lists below. For a fully comprehensive reference of all Ignition types, refer to the Javadocs or the Ignition SDK Programmers Guide.

Alarming

AlarmQueryResult

Used By: system.alarm.queryStatus, system.alarm.queryJournal

The AlarmQueryResult object represents a collection of AlarmEvent objects with some additional helper methods.

Methods

NameReturnsDescription
getDataset()datasetReturns the alarms as a dataset. Columns for realtime (queryStatus) calls are:
  • EventId
  • Source
  • DisplayPath
  • EventTime
  • State
  • Priority

Columns from historical calls (queryJournal) have the following columns:
  • EventId
  • Source
  • DisplayPath
  • EventTime
  • EventState
  • Priority
  • IsSystemEvent

PyAlarmEvent

Used By: Perspective - Alarm Journal Table, Perspective - Alarm Status Table, system.alarm.queryJournal, system.alarm.queryStatus.

This object contains information about alarm events. See ScriptableBlockPyAlarmEvent below for a list of methods.

ScriptableBlockPyAlarmEvent

Used By: This object is the "event" object made available to Script Blocks in alarm pipelines.

note

The methods listed in the table below are shared between the PyAlarmEvent and ScriptableBlockPyAlarmEvent objects, with the latter being the "event" object made available to Script Blocks in alarm pipelines. However, there is one method called cancelNotification that is exclusive to ScriptableBlockPyAlarmEvent.

Methods

NameReturnsDescription
cancelNotification()NoneWhen invoked, cancels the running pipeline instance.
contains(String propertyName)BooleanReturns a boolean, based on whether or not the alarm event contains a value for the named property. Useful when testing for associated data.
get(String propertyName)AnyReturns the value of propertyName. Useful in cases when trying to view the value of associated data. A full list of built-in alarm properties can be found on the Tag Alarm Properties page.
getAckData()EventDataReturns an object containing information acknowledgement information for the event, assuming the event has been acknowledged.
getActiveData()EventDataReturns an object containing information detailing when the alarm went active.
getClearedData()EventDataReturns an object containing information detailing when the alarm transitioned to a cleared status, assuming it has done so.
getDisplayPath()StringPathReturns the Display Path of the alarm.
getDisplayPathOrSource()StringIf the Display Path for the alarm in an empty string, then returns the Source Path, otherwise, returns the Display Path.
getId()java.util.UUIDReturns the UUID of the alarm event.
getLabel()StringThe label of the alarm event.
getLastEventState()AlarmStateTransitionReturns the last state of the alarm. Possible return values are Active, Acknowledged, or Cleared.
The last event is always returned, so if you're looking to see if an alarm has been both Acknowledged and Cleared, use getState() instead.
getName()StringReturns the name of the alarm.
getNotes()String or NoneReturns the value of the Notes property. Returns a None-type object if a Note has not been configured on the Alarm.
getOrDefault(String propertyName)AnyReturns the value of the propertyName, or the default value if one isn't defined. Can return null if the value is null.
getOrElse(String propertyName, Object fallBackValue)AnyReturns the value of propertyName. If there is property by that name, fallBackValue is returned instead. Can return null if the value is null.
getPriority()AlarmPriorityReturns an AlarmPriority object representing the the Priority of the alarm. Can easily be converted to a String with str().
getProperties()SetReturns a set of all properties on the event.
getSource()QualifiedPathReturns the Source path of the alarm.
getState()AlarmStateReturns the current state of the alarm: i.e., Active, Unacknowledged.
isAcked()BooleanReturns a boolean flag indicating that the alarm has been Acknowledged.
isCleared()BooleanReturns a boolean flag indicating that the alarm has been Cleared.
isShelved()BooleanReturns a boolean flag indicating that the alarm has been Shelved.

In addition, PyAlarmEvents have the following keys that can be used to identify certain property values. For example:

results = system.alarm.queryStatus()
for i in results:
print i["EventId"]
KeyDescription
EventId A unique identifier for the alarm event.
SourceThe source path of the alarm event.
`DisplayPath``The display path of the alarm event.
EventTimeA date representing when the alarm event changed State/EventState.
StatequeryStatus Only. A string representing the state of the alarm. Expected values are:
  • Active, Unacknowledged
  • Active, Acknowledged
  • Cleared, Unacknowledged
  • Cleared, Acknowledged
EventStatequeryJournal Only. A string representing the state of the alarm. See State for a list of possible values.
PriorityA string representing the priority of the alarm.
IsSystemEventqueryJournal Only. A boolean representing if this event was a system event.

ShelvedPath

Used By: system.alarm.getShelvedPaths

This class provides information about an alarm that has been "shelved", including the alarm path, when it was shelved, and by whom.

Methods

NameReturnsDescription
getPath()pathReturns a Path object representing the path to the alarm. Can be cast to a string.
getExpiration()dateReturns the time that the shelve expires.
getUser()QualifiedPathReturns the actual AlarmEvent object for the specified event UUID.
isExpired()booleanReturns True if the shelve has expired for the alarm; otherwise returns False.

Datasets and PyDatasets

Used By: Many facets of Ignition including queries, Vision and Perspective components, and Tags

See Datasets.

Queries

SProcCall

Used By: system.db.createSProcCall, system.db.execSProcCall

See system.db.createSProcCall.

Tags

Results

Used By: system.tag.browse, system.tag.browseHistoricalTags

Methods

NameReturnsDescription
getResults()listReturns a list of node dictionaries, one for each Tag (including folders and UDT instances) in the result set. See Tag Dictionary Keys below for a summary of available keys in the Tag dictionaries.
getReturnedSize()integerReturns the number of results contained in this object. If different than getTotalAvailableSize(), only a partial browse was performed, and the continuation point should be non-null.

Tag Dictionary Keys

All Nodes (Tags, Folders, UDT Definitions, and UDT Instances)

NameTypeDescription
fullPathBasicTagPathA fully qualified Tag path to the node, including the name of the node.
The value returned by this key is a BasicTagPath. However, Python's str() method can be used to convert the path to a string.
hasChildrenbooleanRepresents whether the node contains sub-nodes, such as folders and UDT definitions.
nameunicodeThe name of the node.
The value returned by this key is unicode. However, Python's str() method can be used to convert the type to a string.
tagTypeTagObjectTypeThe type of the node. Possible values are:
  • AtomicTag: Represents a standard Tag.
  • Folder: Represents a Tag folder.
  • UdtType: Represents a UDT definition.
  • UdtInstance: Represents a UDT instance.

The value returned by this key is a TagObjectType. However, Python's str() method can be used to convert the type to a string.

Tags (tagType = AtomicTag)

NameTypeDescription
dataTypestringThe data type of the Tag.
valueSourcestringRepresents how the Tag derives its value.
valueVariesThe last known qualified value on the Tag.

UDT Definitions and Instances (tagType = UdtType or UdtInstance)

NameTypeDescription
typeIdstringRepresents the parent data type for the UDT.
UDT definitions without a specified parent type will have a value of None.

Users

Used By: system.user.getUser, system.user.getUsers

This class provides information about basic user properties, except for the user's password.

Methods

NameReturnsDescription
get()stringReturns the specified value, or a null value if the requested item is not present. The following list represents the various values you may use in this manner:
  • username
  • firstname
  • lastname
  • notes
  • schedule
  • language
  • parameter - this method also accepts a parameter string. Note that it will not always return a string.
getOrDefault()stringReturns the specified value, or a default value if the requested item is not present. For example, user.getOrDefault(user.schedule) will return that user's schedule, or the value of Always if no schedule has been set as that is the default schedule.
The following list represents the various values you may use in this manner:
  • username
  • firstname
  • lastname
  • notes
  • schedule
  • language
  • parameter - this method also accepts a parameter string. Note that it will not always return a string.
getId()stringReturns the internal identifier object that the backing user source needs to identify this user.
getRoles()stringReturns a sequence of strings representing the roles that this user belongs to.
getContactInfo()ContactInfoReturns a sequence of ContactInfo objects. Each of these objects will have a contactType and value property representing the contact information, both strings.
getScheduleAdjustments()ScheduleAdjustmentReturns a sequence of ScheduleAdjustment objects. Each of these objects will have two date properties, "start" and "end", a boolean property, "available", and a string property called "note".
getPath()QualifiedPathReturns a QualifiedPath object that represents this user in a deterministic manner.

Perspective

See Perspective Component Methods.

Misc Objects

QualifiedValue

Used By: Many facets of Ignition including Tag Event Scripts, various system.tag functions, and Perspective Property Change scripts

The QualifiedValue class is a representation of an Ignition value often used to represent a Tag's current condition (as in the result of a Tag read) and is meant to provide more context than a value alone. Two qualified values are considered equal if their quality and value are equal. The properties and methods on a QualifiedValue object are as follows:

Properties

NameTypeDescription
valuevariesThe data associated with the QualifiedValue object. Type depends on the type of the underlying value.
qualityqualityCodeThe quality associated with the returned value. See QualityCode.
timestampdateThe time associated with the returned value.

Methods

NameTypeDescription
getValue()variesGets the data associated with the QualifiedValue object. Type depends on the type of the underlying value.
getQuality()qualityCodeGets the quality associated with the returned value. See QualityCode.
getTimestamp()dateGets the time associated with the returned value.

QualityCode

Used By: QualifiedValue Objects

The QualityCode class describes a quality for a value.

Methods

NameReturnsDescription
getCode()integerReturns the 32-bit integer code associated with the quality. For more information on quality codes, including a list of available codes, see Quality Codes and Overlays.
getDiagnosticMessage()stringReturns the diagnostic message associated with this quality, if present. Otherwise, returns None.
isGood()booleanReturns True if this code represents a Good quality level. Otherwise, returns False.
isUncertain()booleanReturns True if this code represents an Uncertain quality level. Otherwise, returns False. Note that Bad and Error quality levels return False.
isBad()booleanReturns True if this code represents a Bad quality level. Otherwise, returns False. Note that Uncertain and Error quality levels return False.
isError()booleanReturns True if this code represents an Error quality level. Otherwise, returns False. Note that Bad and Uncertain quality levels return False.
isNotGood()booleanReturns True if this code represents an Uncertain, Bad, or Error quality level. Otherwise, returns False.
isBadOrError()booleanReturns True if this code represents a Bad or Error quality level. Otherwise, returns False.
toValue()QualifiedValueReturns this quality as the quality component of a QualifiedValue object.
is(QualityCode other)booleanCompares the integer quality codes of another QualityCode object to this one. Returns True if they match.
isNot(QualityCode other)booleanCompares the integer quality codes of another QualityCode object to this one. Returns True if they do not match.