- initialChange - a variable that is a flag (0 or 1) which indicates whether or not the event is due to the initial subscription or not. This is useful as you can filter out the event that is the inital subscription, preventing a script from running when the values haven't actually changed.
- event - a TagChangeEvent object which contains the properties: tag, tagPath, and tagProperty, all of which are also complex objects.
- event.tag - a Tag object which contains basic information about the Tag such as name, value, and type that can be accessed via event.getTag().getName().
- event.tagPath - a TagPath object which contains information pertaining to the Tag path such as the parent and child paths via event.getTagPath().getParentPath(). You can also get the path of the Tag by calling event.getTagPath().toString().
- event.tagProperty - a TagProperty object, which can be used to create an enum of a property, which can be used in conjunction with the Tag object to access properties of the Tag such as OPC Item Path or Scale mode via event.getTag().getAttribute(event.getTagProperty().getProp("OPCItemPath")). The possible properties are: 'AccessRights', 'AlarmActiveAckCount', 'AlarmActiveUnackCount', 'AlarmClearUnackCount', 'AlarmHighestAckName', 'AlarmHighestAckPriority', 'AlarmHighestUnackName', 'AlarmHighestUnackPriority', 'AlarmShelvedCount', 'AlertAckMode', 'AlertAcknowledgeUser', 'AlertAcknowledged', 'AlertAcknowledgedTime', 'AlertActive', 'AlertActiveTime', 'AlertClearedTime', 'AlertCurrentSeverity', 'AlertCurrentState', 'AlertDeadband', 'AlertDisplayPath', 'AlertExecEnabled', 'AlertMessage', 'AlertMessageMode', 'AlertMessageSubject', 'AlertMode', 'AlertNotes', 'AlertSendClear', 'AlertTimestampSource', 'ClampMode', 'DataType', 'Deadband', 'DeadbandMode', 'DeriveExpressionGetter', 'DeriveExpressionSetter', 'Documentation', 'DriverName', 'Enabled', 'EngHigh', 'EngLimitMode', 'EngLow', 'EngUnit', 'EventScripts', 'Expression', 'ExpressionType', 'ExtendedProperties', 'FormatString', 'HistoricalDeadband', 'HistoricalDeadbandMode', 'HistoricalScanclass', 'HistoryEnabled', 'HistoryMaxAge', 'HistoryMaxAgeMode', 'HistoryTimestampSource', 'InterpolationMode', 'LastChange', 'Name', 'OPCItemPath', 'OPCServer', 'OPCWriteBackItemPath', 'OPCWriteBackServer', 'PersistValue', 'PollRate', 'PrimaryHistoryProvider', 'PropertyOverrides', 'Quality', 'QueryType', 'RawHigh', 'RawLow', 'RuntimeQuality', 'SQLBindingDatasource', 'ScaleFactor', 'ScaleMode', 'ScaledHigh', 'ScaledLow', 'ScanClass', 'SourceDataType', 'SourceTagPath', 'TagType', 'TagTypeSubCode', 'Tooltip', 'UDTMemberUID', 'UDTParentType', 'Value'.
- newValue - a newValue object which contains a value, quality, and a timestamp of the Tag. They can be called via newValue.getValue().
Gateway Tag Change Behavior
Having the Tag Change Scripts run in the Gateway Scope means that the scripts will trigger when a Tag in their Tag list changes as long as the Gateway is running. The script will be able to interact with the Gateway and other Tags, but not the project.
Client Tag Change Behavior
Having the Tag Change Scripts run in the Client Scope means that the scripts will trigger when a Tag in their Tag list changes, but only if a Client of that project is open. This means that if no Clients are open, the script will not fire, and if many clients are open, the script will fire once for each open client. Additionally, because this is run from the Client Scope, it will have access to Client resources such as Client Tags.
Under the list of handlers, three small buttons allow you to add, remove and manage your handlers.
- Add Message Handler - Will add a message handler.
- Remove Message Handler - Will delete the highlighted message handler.
- Modify Message Handler - Will modify the settings for the highlighted message handler.
When adding or modifying a message handler, a small settings window will popup. In it, you can give your message handler a name or modify its existing name, enable or disable the message handler, and even select how it executes under the Threading dropdown. There are three different options that dictate how the message handler will execute:
- Shared - The default way of running a message handler. Will execute the handler on a shared pool of threads, in the order that they are invoked. If too many message handlers are called all at once and they take long periods of time to execute, there may be delays before each message handler gets to execute.
- Dedicated - The message handler will run on its own dedicated thread. This is useful when a message handler will take a long time to execute, so that it does not hinder the execution of other message handlers.
- EDT - This will run the message handler on the Event Dispatch Thread (EDT) which also updates the GUI. If a message handler were to take a long time to execute, it would block the GUI from running which may lock up your client. This is helpful when your message handler will be interacting with the GUI in some way, as the GUI will not be able to update until the message handler finishes.
Inside the message handler is your script. The script will have a single object available to it, the payload. The payload is a dictionary containing the objects that were passed into it. Each object in the payload dictionary can be accessed by calling their corresponding key. For example:
Gateway Message Handlers
Gateway Message Handlers are setup and function similarly to client message handlers. However, there are two major differences:
They are setup in the Message section of the Gateway Event Scripts. As such, they are executed on the Gateway.
- They have an added layer of security. In the Message Handler Settings, it is possible to configure Security Zone/User Role pairs. The user invoking the message handler must match one of the combinations of Security Zone/User Role listed or else the message handler will not execute.
Using Message Handlers
Once you have your message handlers created, you can then call them from a script using one of three scripting functions: system.util.sendMessage, system.util.sendRequest, and system.util.sendRequestAsync. These functions allow you to call a message handler in any project, even if the project that the message handler resides on is different from the one you are calling it from. The message handler will then execute in the scope in which it was created, and will use any parameters that you pass in through the payload.
Troubleshooting Gateway and Client Scripts
For both Gateway and Client scripts, Ignition gives you the tools to quickly check the status, troubleshoot, and diagnose problems with your scripts.
The Gateway has a special section (Gateway webpage - Status > Systems > Gateway Scripts) where you can quickly check to make sure your Gateway scripts are running properly. If any of your scripts have an error, you can find the details of the error to help you troubleshoot what went wrong. You can also find a list of logged errors for all Gateway Event Scripts under Log Activity. To learn more about statusing Gateway scripts and troublshooting, refer to Gateway Scripts.
The Console is very a important tool in Ignition for troubleshooting Client scripts. You can check to see if your script is working directly from the Client window, or the Designer while in Preview Mode. Any client scripting errors along with printouts go to the Console. The Console will identify the script name, error message, what line the script error is in, and a description of the problem.
To access the Console from a Client, go to the menubar and select Help > Diagnostics > Console. To access the Console from Preview Mode in the Designer, go to the menubar Tools > Console.