The Update Script event runs after a project is saved or updated on the Gateway. This enables you to insert a script that will run every time a project is saved.
This script now reports which resources were modified during a project save. The following parameters have been added:
|actor||The user or system responsible for the project update.||String|
A dictionary that holds the following keys:
Since multiple Timer Scripts can be added, there are separate buttons that allow you to manage each Timer Script.
- - Adds a new Timer Script. Add Timer Script
- Remove Timer Script - Will delete the selected Timer Script.
- Modify Timer Script - Will modify the settings for the selected Timer Script.
Timer Script Settings
Below is an overview of the settings for a Timer Script.
- Name: The name of the Timer script. Names must be unique per project, so two timer scripts in the same project cannot have the same name.
- Delay: The delay period in milliseconds. The meaning of this setting is dependent on the Delay Type setting.
- Enabled: Allows you disable the Timer Script when set to false.
- Delay Type: Determines how the Delay setting is utilized.
- A Fixed Delay timer script (the default) waits for the given Delay between each script invocation. This means that the script's rate will actually be the delay plus the amount of time it takes to execute the script. This is the safest option since it prevents a script from mistakenly running continuously because it takes longer to execute the script than the delay.
- Fixed Rate scripts attempt to run the script at a fixed rate relative to the first execution. If the script takes too long, or there is too much background process, this may not be possible. See the documentation for java.util.Timer.scheduleAtFixedRate() for more details.
- Threading: Determines which thread this script should run in. In other words, this setting allows you to specify if you want this timer script to share execution resources or not. The rule of thumb here is that quick-running tasks should run in the shared thread, and long-running tasks should get their own dedicated thread.
- The Shared setting means that all timer scripts will share a thread. This is usually desirable, as it prevents creating lots of unnecessary threads: threads have some overhead, so a small amount of resources are used per thread. However, if your script takes a long time to run, it will block other timer tasks on the shared thread.
- The Dedicated setting will create a separate thread specifically for the timer script to use. This setting is desirable when your scripts executions must be as consistent as possible, as other timer scripts can't slowdown or otherwise impact the execution of a script in a separate thread.
Tag Change Script Interface
Lists all of the available Tag Change scripts in the project. Two icons are available below the list:
- - Adds a new Tag Change Script to the list. Add Script
- - Removes the currently selected script from the list. Remove Script
The Tags tab contains settings for the script. See the Script Settings description below
- Script Name - The name of the script. Script names must be unique per project.
- Enabled - Determines if the script is active or not. Set to false to disable the script.
- Change Triggers - When the Tag changes, the script can trigger based on the Value, Quality, and/or Timestamp. Note that regardless of how many triggers changed, the script only executes once per tag, so leaving all triggers enabled will not trigger three executions each time the Tag changes.
- Tag Paths - A list of Tag paths to monitor. When any of the Tags listed in this area change, the script will trigger. Note that the list is not comma separated: new paths are specified each line.
- Tag Browser - Opens a Tag Browser window, allowing you to quickly lookup and add Tag paths to the Tag Change Script.
Path Diagnostic - Click this icon to verify the paths specified under the Tag Paths list. This is useful for checking for typos in the list.
Wildcards can be used at the end of configured tag paths. Using a wildcard will execute the script for all tags within the same folder. In the below example, the script "New Script" will run when the value of any tag in the "folder" folder changes.Note: Wildcards can only be used at the folder level and cannot be used at the tag level. For example, configuring a tag path like
[default]folder/*will execute a script on all tags within the folder, but
The Script tab is where the Python script associated with this event will be placed.
Tag Change Objects
Tag Change Scripts contain several built-in objects that are useful for inspecting the event, such as seeing what value the Tag changed to. These objects are listed below.
The initialChange Value
The boolean initialChange variable indicates if an event is due to an initial subscription. This is useful as you can filter out the event that is the initial subscription, preventing a script from running when the values haven't actually changed.
The executionCount Value
An integer representing a number of event executions since gateway scripts were restarted (typically by applying a change to a script and saving the project).
The newValue Object
A QualifiedValue object that represents the current value on the tag.
|Varies||Returns the new value on the tag|
|QualityCode||Returns the new quality on the tag|
|Date||Returns the new timestamp value|
The previousValue Object
A QualifiedValue object that represents the previous value of the tag.
|Varies||Returns the previous value on the tag|
|QualityCode||Returns the previous quality on the tag|
|Date||Returns the previous timestamp value|
The Event Object
This object offers some additional utility, such as accessing the previous values on the tag.
|QualifiedValue||Returns a QualifiedValue object (similar to the newValue object), representing the current value on the tag.|
|QualifiedValue||Returns a QualifiedValue object, representing the values on the tag before the change.|
|TagPath||Returns a TagPath object, that can be further examined for details about the path on the tag that changed. See the TagPath Object table below. Additionally, the TagPath object can easily be turned into a string, providing quick access to the path of the tag that changed value.|
|QualifiedValue||Returns a QualifiedValue object (similar to the newValue object), representing the current value on the tag. This method is functionally identical to getCurrentValue(), and maintained mostly for backwards compatibility reasons.|
|changes||TagChangeType||A RegularEnumSet typed attribute that describes what changed: the value, quality, or timestamp. Values in the set are TagChangeType objects, which can be converted to string with either Python's built-in str() or Java's toString().|
An attribute that describes the tag path on the tag that changed.
Gateway Scheduled Scripts
Scheduled scripts are events that execute at fixed times of the day, based off of the Gateway's system time. Configuration for the event is split between two tabs: Settings and Script .
The settings tab allows you to give the event a unique name and determine how often it executes. Schedules are driven by cron job scheduling.
The Common Settings dropdown contains several common selections, which can be further modified with the fields and dropdowns under each unit of time.
Each unit of time consists of a field, and corresponding dropdown. The dropdown is filled with suggestions and simple options, but more complex values can be provided in the field on the left. See Crontab Formatting Reference.
The script tab houses the Python script that will execute when the scheduled event executes.
Troubleshooting Gateway Scripts
While they are technically project resources, remember that Gateway Event Scripts technically run on the Gateway. Thus the Status section of the Gateway is useful for diagnosing issues with Gateway Event Scripts.