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

This script type is only available in the Client scope. This is a special script that will be called when the user tries to exit or close the client, that is, shutdown the Client. This script is run with a special event variable in its namespace. When the script terminates, if event.cancel is 1, the shutdown will be aborted, and the client will remain open. Otherwise, the normal shutdown script will be called, and the client will close.


if "SuperUser" not in
	system.gui.warningBox("Exit not allowed for non-admin user.")


Shutdown Scripts

Shutdown Intercept Script

Keystroke Script

Keystroke scripts are only available in the Client scope. These are scripts that run on a certain key combination. You may add as many keystroke scripts as you'd like, as long as each one has a unique key combination. The keystroke event scripts fire on the Client when a user performs a certain key stroke.

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 F-keys, ESC, etc, are only available in the pressed and released actions.


Keystroke Scripts

Timer Script

Timer scripts are available in both Gateway and Client scopes. These scripts execute periodically on a timer at a fixed delay or rate. Remember that Client timer scripts may never execute (if no clients are open) or may execute many times (once per open client). If you need scripting logic that occurs centrally, make sure you use Gateway scoped scripts.

Fixed delay or fixed rate?

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.

Shared thread or dedicated thread?

All timer scripts for a given project that choose Run in 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. 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.


Timer Scripts

Tag Change Script

Tag Change scripts are available in both Gateway and Client scopes. Each tag change script can be given a list of tag paths. Whenever one of these tags changes, the tag change script will execute. They will also get an initial execution whenever the scripting system starts up.

Each tag change script can be given a name for organizational purposes. To specify multiple tag for a given script, enter them one per line in the tag paths text area. To quickly import many tags, you can drag-and-drop tags from the Tag Browser window onto this text area.

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. The initialChange variable is a flag (0 or 1) that indicates whether or not this event is due to initially subscribing or not. The event variable is a TagChangeEvent object, which itself contains the properties: tagtagPath, and tagProperty. The third, newValue, is the new value for the tag property that is subscribed. These values are objects themselves that contain a value, quality, and timestamp. The following example script should be a good starting point:

print "Received tag change event for %s" % event.tagPath
value = newValue.value
quality = newValue.quality
timestamp = newValue.timestamp
print "value=%s, quality=%s, timestamp=%s" %(value, quality, timestamp)

The TagPath object that you access via event.tagPath is itself a complex object. You can turn it into a string if you want the whole tag path by using the str() function. You can also access individual parts of the tag path. The most useful is usually the itemName property, which is the name of the tag represented by the path. To get the name of the tag, you can use event.tagPath.itemName.


Tag Change Scripts

Menubar Script

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 Script

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