---
title: "Scripting in Ignition"
---

# Scripting in Ignition

> Python is used in many places in Ignition. Each location has its own events that trigger your scripts to run, and add functionality to your projects in different ways. The most apparent place is in [event handlers](ignition-modules\vision\scripting-in-vision\scripting-in-vision.md) on components and other objects in Vision Clients and Perspective Sessions.

## Where Is Scripting Used?

### Script Scope

One important thing to keep in mind before scripting in Ignition, is to understand the concept of scope. 

Within Ignition, there are different scopes:

* Gateway Scope - The script runs on the gateway. Scripts running in this scope cannot interact with components in the other two scopes. 
* Perspective Session Scope - The script runs as a part of a Perspective Session. Note that scripts in Perspective execute on the gateway, not in the browser, but this scope is still distinct from the Gateway Scope. 
* the Vision Client Scope - The script runs inside of an instance of a Vision Client.

Where a script was written determines which scope it executes in. For example, Tags are in the Gateway Scope, so [Tag Event Scripts](platform\tags\tag-event-scripts\tag-event-scripts.md) execute in the Gateway Scope.

This means that the script will not be able to access any client level resources such as windows or components that you may have open in the Client. Additionally, some of the system functions like [system.gui.errorBox](appendix\scripting-functions\system-gui\system-gui-errorBox.md) only work in the "Client Scope," so you will not be able to use them in the script on the Tag.

### System Functions, Hints, and Autocomplete

Ignition comes with a group of system functions, which are built-in functions that interact with Ignition features. 

```python title="Python - Simple Script Using a System Function"
value = system.tag.readBlocking(["tagPath"]).value
```

A complete list of these functions (with their definitions) is available from the autocomplete popup. Wherever you can add a script, type **system**. and then press **Ctrl+Space** to get a list of all the functions available. If you keep typing, the list will be automatically narrowed down for you.  Additionally, the [System Functions](appendix\scripting-functions\scripting-functions.md) page in the appendix contains complete documentation for the built-in system functions.

:::note
The autocomplete popup always shows all system functions scoped to the current script. If a system function does not appear in the list, that means the function is not available in the current scope, or has been deprecated.
:::

![](scripting-image1.png)

Starting in 8.1.18, the autocomplete popup is enabled by default and will appear after typing "."

The new editor also offers parameter completion assistance; if you auto-complete a method with multiple required parameters, you’ll automatically enter a “parameter assistance” mode, where you can tab through the parameters and enter them one at a time:

![](scripting-image2.gif)

To disable these features, right-click anywhere within the Script Editor window and deselect **Automatic Activation** and/or **Parameter Assistance**.

![](scripting-image3.png)

Autocomplete hints are now also displayed for code other than Ignition's system functions. If Ignition detects a function or project script, a popup will automatically appear, from which you can select which function or project script you are trying to reference. You can also bring up this popup by pressing "ctrl-space".

![](scripting-image4.png)

Autocomplete hints will extract method parameters, return information, and limited type awareness for project script functions and class docstrings written in [Google Python Style Guide's](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods) docstring format. An example of the expected format is as follows:

```python title="Code Snippet"
def setMode(mode):
    """Changes the mode of the running system
  
    Args:
        mode: An integer representing the mode to switch to.
  
    Returns:
        A boolean that indicates if the attempt at switching to the given mode was successful.
  
    Raises:
        Error: If communications are down, an exception will be thrown.
    """
    # Function code goes here
```

The code above will display the description, parameter, and return information when autocomplete hints render the docstring:

![](scripting-image5.png)

#### Script Hint Scope

You can choose the scope of your scripting hints and suggestions come from by selecting the dropdown menu in your Project Library's scripts:

![](scripting-image6.png)

The table below lists possible values you can choose from in the dropdown menu:

|Value |Description |
|--|--|
|None |The project library will not use the Designer nor the Gateway to populate scripting hints. |
|Designer |The project library will use the Designer scope to populate scripting hints. |
|Gateway |The project library will use the Gateway scope to populate scripting hints. |
|All |The project library will use both the Designer and Gateway scope to populate scripting hints. |

## Components

Both Perspective and Vision offer component based scripting triggers, providing a means to execute a script under a number of different situations, such as a user interacting with a component or a component property value changing. For more information on how both module handle component based scripts, take a look at the [Scripting in Perspective](ignition-modules\perspective\scripting-in-perspective\scripting-in-perspective.md) and [Scripting in Vision](ignition-modules\vision\scripting-in-vision\scripting-in-vision.md) sections.

![](scripting-image7.png)

## Client, Gateway, and Session Event Scripts

Scripts can be set to activate on specific events that occur during runtime. For example, you can trigger a script to run when a vision client starts, or on certain time intervals.

More information on these events can be found on the [Client Event Scripts](ignition-modules\vision\scripting-in-vision\client-event-scripts\client-event-scripts.md), [Gateway Event Scripts](gateway-event-scripts\gateway-event-scripts.md), and [Perspective Session Event Scripts](ignition-modules\perspective\scripting-in-perspective\perspective-session-events-scripts.md) pages.

## Project Scripts

You can create your own reusable blocks of code in the [Project Library](project-library\project-library.md). Once configured, these functions can be called from anywhere in a project, just like our [system.*](appendix\scripting-functions\scripting-functions.md) functions.

![](scripting-image8.png)

## Tag Scripts

Once Enabled, these scripts are fired whenever a [Tag value changes](platform\tags\tag-event-scripts\tag-event-scripts.md) or an alarm event happens. You can use them for additional diagnostics, to set additional Tags, or to react to an alarm event. Because these events are on Tags, they are Gateway Scoped.

![](scripting-image9.png)

## Reporting

Reporting uses scripting in many different ways to help increase the effectiveness of the report. Scripting in Reports is used to [create and modify data sources](ignition-modules\reporting\report-data\scripting-data-source\scripting-data-source.md), [manipulate charts](ignition-modules\reporting\report-design\report-charts\report-charts.md#chart-scripting), and set up a script as a [scheduled report action](ignition-modules\reporting\report-schedules\scheduling-actions\scheduling-actions.md#run-script-action).

![](scripting-image10.png)

## Alarming

The Alarm Notification system can also use scripting to great effect. A [script block](ignition-modules/alarm-notification/alarm-notification-pipelines/pipeline-blocks/pipeline-blocks.md#script-block) allows a script to be run within the pipeline, allowing data to be manipulated as the alarm event travels through the pipeline. Additionally, scripting can be used to generate a [custom roster](ignition-modules\alarm-notification\alarm-notification-pipelines\pipeline-blocks\notification-block.md#calculated) of users at runtime, giving full customization to who gets notified by the alarm event.

![](scripting-image11.png)

## Sequential Function Charts

Sequential Function Charts (SFCs) are a flowchart of blocks that run scripts. They are executed in a specific sequential order along with some logic to potentially loop or call other charts. The scripts here can interact with the Gateway, and provide greater control when each step needs to complete before the next one can begin in multi-step processes.

![](scripting-image12.png)