Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

Client and Gateway Event Scripts

These scripting workspaces are located in the Project menu of the designer underneath Properties, or in the Project Browser under Project>Scripts. Each Scope has its own set events, most of thembeing the same type of event in each Scope.

Client Event Scripts

Client scripts execute in the running Client, which means that they may never execute (if no clients are running), or they may execute many times (if multiple clients are running). Client scripts will also execute in the Designer, but only in Preview Mode. Because Clients are full-fledged applications, the scripts run on the computer running the Client, not on the Gateway's host server computer. This means that they don't have access to the Gateway's file system, and so on.

The Client Event Scripts are:

  • Startup
  • Shutdown
  • Shutdown-Intercept
  • Keystroke
  • Timer
  • Tag Change
  • Menubar
  • Message

Gateway Event Scripts

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

The Gateway Event Scripts are:

  • Startup
  • Shutdown
  • Timer
  • Tag
  • Message

On this page ...


Gateway vs Client Event Scripts

Startup Script

The Startup Script event runs at the startup of either the Client or the Gateway. This allows you to run a script at startup, giving you the chance to configure certain things dynamically.

Gateway Startup Behavior

In the Gateway scripting scope, this means that the script will run when the Gateway starts up and whenever the scripting configuration changes via a Designer save action. This means that while designing, the startup and shutdown events may happen frequently.

There is a specific order to when the various startup scripts are run. When troubleshooting your Gateway startup times, consider the following:

  1. Gateway starts - The Gateway will start as an OS service, and start the context. No startup scripts can run before this is complete.
  2. Projects are started - This includes all of the Gateway scoped items in the projects such as Transaction Groups, SFCs, etc. This does not refer to launching clients, and no clients can be automatically launched at this time. All Gateway Startup Scripts are run at this time for each project. Note: if you have copied a project, always check for Gateway scoped events such as these. You generally don't want a Gateway Startup Script to run twice because it is in two projects.

Client Startup Behavior

In the Client scripting scope, these scripts run after a user successfully logs in to the client, but before any "Open on Startup" windows are opened.


Startup Scripts

Shutdown Script

The Shutdown Script event run at the shutdown of either the Client or Gateway. It allows you to run a piece of code as the shutdown is occurring. After the script is run, the shutdown will finish.

Gateway Shutdown Behavior

Will run as the Gateway shuts down, such as from the Gateway Control Utility.

Client Shutdown Behavior

Will run as the Client shuts down, such as with a script or by clicking the close window "X" at the top of the OS window that is typical in most Operating Systems.


Shutdown Scripts

Shutdown Intercept Script

The Shutdown Intercept Script event 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 at. This allows you to set special restrictions on 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.gui.warningBox("Exit not allowed for non-admin user.")

Keystroke Scripts

The Keystroke Scripts let you create different events that will activate on certain key combinations. They only run in the Client, but you may add as many Keystroke Script events as you'd like, as long as each one has a unique key combination.

Since multiple Keystroke Scripts can be added, there are separate buttons that allow you to add () a Keystroke Script, or edit () and delete () the currently selected Keystroke Script.

When choosing a keystroke, you may choose any number of modifiers, which are keys or mouse buttons that must be down to activate the keystroke. You can also choose whether or not the keystroke is on the pressed or released event of a keyboard key, or upon the typing of a character. Special keys like the Function keys (F1) or ESC are only available in the pressed and released actions.


Keystroke Scripts

Timer Scripts

The Timer Scripts execute periodically on a timer at a fixed delay or rate. This allows you to set up a sort of heartbeat that can run in the Client or the Gateway Scope. Since multiple Timer Scripts can be added, there are separate buttons that allow you to add () a Timer Script, or edit () and delete () the currently selected Timer Script. The Timer Script has three major properties to be aware of: the Delay in milliseconds, the Delay Type, and the Threading.

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.

In addition, all timer scripts for a given project that choose run in a Shared thread will all execute in the same thread. This is usually desirable, to prevent creating lots of unnecessary threads. However, if your script takes a long time to run, it will block other timer tasks on the shared thread. In this case, you can have the Timer Script run in a Dedicated thread so that it runs independently. The rule of thumb here is that quick-running tasks should run in the shared thread, and long-running tasks should get their own thread.

Gateway Timer Behavior

This script will execute in the Gateway, meaning that it will begin running when the Gateway starts, and will continue running at the rate specified until the Gateway is stopped.

Client Timer Behavior

Since this will execute in a Client, it is important to remember that Client Timer Scripts may never execute (if no clients are open) or may execute many times (once per open client).


Timer Scripts

Tag Change Scripts

The Tag Change Script event occur when either the Value, Quality, or Timestamp of a tag or list of tags changes. They will also get an initial execution whenever the scripting system starts up. You can set the Tag Change Script to run in either the Client or the Gateway Scope. Multiple Tag Change Scripts can be created, using the add () button to add a script, and the remove () button to remove the selected script. To specify multiple Tags for a given script, enter them one per line in the tag paths text area. To quickly add many tags, you can open the Tag Browser () and drag-and-drop tags from the window onto this text area. The actual script is then entered in a different tab. When executing, each Tag Change Script runs in a separate thread. This prevents long running scripts from blocking the execution of other Tag Change Script. 

These scripts receive three special variables in their namespace when they are run: eventinitialChange, and newValue. Both the event and newValue objects refer to the Tag that changed to initiate the event.


Tag Change Scripts

  • 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.tag.getName().
    • event.tagPath - a TagPath object which contains information pertaining to the Tag path such as the parent and child paths via event.tagPath.getParentPath(). You can also get the path of the Tag by calling event.tagPath.toString().
    • event.tagProperty - a TagProperty object, which can access all of the properties of the Tag such as OPC Item Path or Scale mode via event.tagProperty.OPCItemPath().
  • 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, regardless of the number of times the Tag changes. However, because this is run from the Client Scope, it

Menubar Scripts

The Menubar Event Scripts are....  Here are their properties

Menubar Example

The menu in the Vision client is configured and customized through the Client Event Scripts dialog box in the Designer.  Just like customizing the runtime client for how a user navigates between different windows, you can also customize what menu items are in the Menubar, and how they are activated. Let's get started.


  1. The Menubar uses Client Event Scripts to customize and execute navigation actions.
    In Designer, go to the Project Browser, and double click on Client Event Scripts.  


  2. This opens the Client Event Scripts dialog box.  The structure of the Menubar is represented as a tree. Each item in the Menubar that does not have children executes a script when the user presses it.


    These scripts typically execute navigation actions such as opening, or swapping a window in the client.

  3. Menu items that have children are typically shown as nested items in the Menubar Structure and the Menubar of the client.


  4. Let’s add a new menu item that pops up a Welcome Message in the client.  In this example, select the last menu item in the Menu Structure called Overview, then click on Add Sibling.

    Enter the Name:  Welcome Message.  You have the option of associating your menu item with an icon by selecting an icon from the built-in icons folder or uploading your own.  

    Next, create the script for your message.  If you enter the word “system.” and hit “CRTL Space,” all the available system functions to choose from will be displayed.  The script used in this example is shown below:  

    Message Script
    system.gui.messageBox("Welcome to your New Project!”, “Message”)

    You also have the option of adding a Mnemonic Character to a menu item.  A mnemonic is the first letter in the menu item’s name.  In this example, the ‘w’ is the Mnemonic Character for your Welcome Message.  You will notice that the ‘w’ is bold and underlined in the “Welcome Message.”  The Mnemonic Character only executes when all the menu items are displayed under Navigation menu.  

    When you’re finished, click OK

  5. Save and Publish your project. 

  6. Go to your Client, and click update on the yellow bar and then dialogue box. 

  7. Under the Navigation window, click on the Welcome Message or type the Mnemonic "w."  This menu item runs the script that creates your Welcome Message in the window.   


  8. Lets look at the script for the User Management menu item.  Go to the Project Browser > Client Event Scripts.  This script swaps from the current window to the User Management window.  

    You also have the option of setting up  Accelerator keys for menu items.  An Accelerator key associates a keystroke with executing an action. In this example, the 'F1' key is defined as the Accelerator key and is listed to the right of User Management menu item.   

    When the 'F1' key is pressed while the Navigation window is open, the User Management window will open in the client. 


  9. In the Client, there are two additional menu items, Windows and Help.  These menu items are added by the Ignition client itself. 

    You can hide the Windows Menu by going the Project Browser > Project Properties > User Interface and check Hide Windows Menu box, or you can hide the entire menu bar clicking the Hide Menu Bar.


See also: Navigation StrategiesClient/User Interface Properties


Menu Bar

Message Scripts

***This section was take from Message Handlers under the  Advanced Scripting ***

Message Handlers allow you to write a script that will run in either the Client or Gateway that they are located in, but they can be invoked by making a call from other projects or even other Gateways. They can be called using three different scripting functions: system.util.sendMessagesystem.util.sendRequest, and system.util.sendRequestAsync.

Client Message Handlers

Located in the Message section of Client Event Scripts, client message handlers will execute in the client. This means if you have 5 clients open for a project with a message handler that gets called, the message handler will run in each client. You can easily create and manage all of your client message handlers in the Client Event Scripts window. Clicking on one of your message handlers will bring up its script on the right.

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

    The following feature is new in Ignition version 7.9.4
    Click here to check out the other new features

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

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


Script Messaging

  • No labels