Gateway Event Scripts

Gateway Event Scripts execute on the Ignition Gateway service. This means that they will always execute as long as Ignition is running, even if there are no clients open. If there are multiple clients open, these scripts will still only run once. For example, if you have a script that writes to the Gateway when a Tag changes, it belongs in the Gateway scope so you don't get duplicate records when multiple clients are open.

Shutdown-Intercept Script

The Shutdown-Intercept Script is unique in that it runs when a user attempts to shutdown a client, but before actual shutdown occurs. This means it will actually run before the Shutdown Script, and there is only a client version of it. There is a special event object that you can set a cancel property to prevent shutdown by using the code "event.cancel = 1." Doing this will cancel the shutdown event and leave the user at the spot they were last. This allows you to set special restrictions  when the client is actually allowed to shut down, such as having a certain role, as seen in the example below:

if "SuperUser" not in system.security.getRoles():
	system.gui.warningBox("Exit not allowed for non-admin user.")
	event.cancel=1

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

The top level nodes will show up in the menubar. Each node can have an action script unless it has children. In the image above, the Command object will have a grayed out action script field because it has three children. This allows the Client to click into the menu, and look at what is inside. Children of objects can themselves have children, allowing you to create submenus within your menu. The structure is easy to create, using the buttons to the right to add peer () or child () nodes. You can also move the nodes up () or down () in the hierarchy, as that will affect the order they appear in the Client. You can also delete () nodes that you don't want.

With a node selected you can add to or edit its behavior. Each node can be given a name that it will display in the Client, an icon which will be displayed at the front of the name, and a tooltip that will display when hovering over the menu option. These help to identify what the node is and what it does.

Each node can also be given an accelerator and a mnemonic character. The accelerator is a key or key combination that can be pressed at any time in the client to initiate that nodes event. It will display next to the name of the node in the client, and works much like many commonly known accelerators such as Control + S to Save. The mnemonic character is a key that can be pressed when currently in the menu to initiate the node event. If the character chosen is in the name of the node, then that character will be underlined.

Finally, you can set an action script on the node which will determine what happens when the node is selected. Typically this is used for navigation, such as swapping to a new window, or logging out and exiting, like the default nodes. However, you can enter in any kind of script you want.

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:

value1 = payload["MyFirstValue"] #"MyFirstValue" is the key that is associated with a value. We are taking the value associated with MyFirstValue, and assigning it to value1.
value2 = payload["MySecondValue"] #Similarly, we are taking the value associated with MySecondValue and assigning it to value2.

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.

project="test"
messageHandler="My Message Handler"
myDict = {'MyFirstValue': "Hello", 'MySecondValue': "World"}
results=system.util.sendMessage(project, messageHandler, myDict)

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. 

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

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