---
title: "8.1 to 8.3 Upgrade Guide"
---
# 8.1 to 8.3 Upgrade Guide
>
>
## Overview
Ignition 8.3 is a **major** update across all subsystems and modules. Inductive Automation strives to maintain its commitment to backwards compatibility and a straight-forward upgrade process. However, given the vast scope of changes in 8.3, there are inevitably special considerations that need to be evaluated and actions taken in order to successfully upgrade an existing system. This document seeks to identify those issues and provide guidance for users who are migrating from an Ignition 8.1 system. To discover the new features of Ignition 8.3, please see the [What's New](new-in-this-version\new-in-this-version.mdx) section.
**Please read this guide carefully before upgrading a production Gateway.**
:::note Upgrading Redundant Pairs?
If you are looking to upgrade redundant pairs, refer to the [Upgrading a Redundant Pair](/getting-started/installing-and-upgrading/installing-and-upgrading.md#upgrading-a-redundant-pair) procedure on the Installing and Upgrading page for a step-by-step description of the process. Be sure to review this guide before getting started.
:::
## Important Considerations
Before upgrading, check your license to ensure it is compatible with 8.3. If your license is not 8.3 ready, contact your Sales Representative.
Since Ignition 8.3 is a major version update with many new features such as Store and Forward multi-threading, you may notice some performance impacts after upgrading.
Prior to performing any kind of upgrade, it is good practice to first take a [Gateway Backup](platform\gateway\gateway-backup-and-restore\gateway-backup-and-restore.md) of your system. In case something goes wrong during the upgrade process, you will still have a configuration of your system to restore available.
It is **strongly advised** to first upgrade your Gateway to the latest version of 8.1, if you have not already. There **will** be compatibility issues if upgrading directly from 7.9 to 8.3, including changes to:
* Gateway Network
* Serialization
* Data syncing, communication, and storage
:::caution 7.9 End of Life (EoL)
Ignition's Long-Term Support (LTS) for version 7.9 ends on June 30th, 2025. This means that 7.9 Gateways will not be supported by neither the development nor support teams past this date. Due to this, it is recommended to upgrade to Ignition 8.1 to continue receiving support, bug fixes, and security updates.
:::
Additionally, it is **strongly advised** to upgrade either your development or test environment before production. This will help you foresee and eliminate any potentially issues when upgrading, without affecting production. To further reduce any potential issues, your development environment should have similar hardware to your production environment. Upgrading your development environment first will also allow you to see exactly what changes have been made, and how they affect your system.
## Upgrade Process
There are two general approaches when upgrading from Ignition 8.1 to Ignition 8.3. The recommended approach is to use the installer to upgrade, but some users may prefer to uninstall their current Gateways and install a fresh copy of Ignition 8.3. Both options are described below.
### Using the Installer
Using the Installer to upgrade is the easiest approach. Simply run an Ignition 8.3 installer on your existing server, similar to how [minor version upgrades](../installing-and-upgrading.md#upgrade-ignition) work. As always, we highly advise taking a Gateway backup before upgrading.
### Importing Projects into a Fresh Install
When installing a fresh copy of Ignition, you'll need to manually import projects and tags from the Ignition 8.1 Gateway. We generally **discourage** this practice, as it results in unintended consequences. However, if you must import 8.1 resources into an 8.3 Gateway, then we recommend you use Gateway Backups when possible.
The reason for this is that a Gateway Backup triggers an upgrade check that makes modifications to the resources so they run as expected on the Ignition 8.3 system. The same check is triggered when running the installer. Project and tag imports do **not** trigger this check. As a result, you may need to make manual modifications to the imported resources.
For example, the file system in Ignition 8.3 is drastically different, so without the updates and checks, legacy resources may not work without user intervention. This same consideration applies to other differences, like product name changes. Your 8.1 tags are likely using an old name, where a freshly installed Gateway is using the new name. Therefore, tags imported from an Ignition 8.1 file will likely break upon import due to name mismatches.
## Changes That Require User Action
The following sections detail changes made from 8.1 to 8.3 that require user action, and are organized by subsystem.
### Audit Profile Schemas
Audit Profile table and column names differ in capitalization between 8.1 and 8.3, which can cause SQL queries to fail when new 8.3 installs connect to 8.1 databases with existing Audit Profiles. For example, `AUDIT_EVENTS` and `AUDIT_EVENTS_ID` in 8.1 are now `audit_events` and `audit_events_id` in 8.3, respectively. However, when upgrading a Gateway from 8.1 to 8.3, the Audit Profiles will maintain formatting and work as expected.
### Architecture Considerations
#### Data Management
Ignition systems that rely on any Gateway Network services for remote storage will need to follow a specific process when upgrading. Because of serialization changes using Protobuf instead of Java serialization, 8.3 Gateways are not able to store data to 8.1 Gateways over the Gateway Network. This includes storing data using:
* Edge Sync Services
* Remote History Providers
* Remote Alarm Journals
* Remote Audit Profiles
To prevent data loss, the central Gateway hosting the data **must** be upgraded to 8.3 first. This includes Gateways where the main Alarm Journal, audit profile, and history provider are configured. After taking your Gateway offline and upgrading it, ensure that the Gateway is running correctly.
Once the primary Gateway has been successfully upgraded to 8.3, you can proceed to upgrade each of your remote and Edge Gateways that utilize data storing services.
#### Tag Editing
Editing tag configurations originating from a different major Ignition version is not supported. If you attempt to edit a tag hosted on an 8.3 remote provider within an 8.1 Designer, this action will fail and cause the Gateway to throw an error, such as a GatewayException or UndeclaredThrowableException.
### Gateway Network
Ignition 8.3 Gateways can only communicate with other 8.3 or 8.1 Gateways, even if you are using proxies.
The **Require Two-Way Authentication** property now also defaults to `True`. This change enhances your Gateway Network's security, but requires that both ends of a Gateway Network connection [explicitly trust each other](platform\gateway-network\gateway-network.md#main).
To have two Gateways trust each other using **Require Two-Way Authentication**, you will need to approve the certificates on each end of the Gateway Network. On the outgoing Gateway, accept the certificate on the Outgoing Connections page. You can then accept the certificate and connection on the Gateway expecting the incoming connection on the [Incoming Connections](platform\gateway-network\connections-gateway-network\connections-gateway-network.md) page.
If you are upgrading a redundant pair and the backup node is a new installation, you **must** adjust the backup node's **Require Two-Way Authentication** property to mirror the master Gateway's configuration in order to establish a connection.
#### Protobuf and Java Serialization Within the Gateway Network
Due to security and configuration persistence updates, Ignition 8.3 no longer uses Java serialization to convert your data to a saveable state, but instead relies on Protobuf. When upgrading or restoring an 8.3 Gateway, the webserver settings will enable the **Allow Java Serialization** [property](platform\gateway-network\gateway-network.md#main) automatically. In the Gateway Network, there will be a banner on the Gateway expecting an incoming connection warning you that this property is enabled.
Keep in mind that **Allow Java Serialization** must be enabled if you add 8.3 Gateways to your architecture containing 8.1 Gateways.
### JDBC Driver Modules
Since the MariaDB, MSSQL, and PostgreSQL [JDBC drivers](#modules) are now added as modules, containers that used the `GATEWAY_MODULES_ENABLED` flag in 8.1 will need to have the drivers added to the enabled modules list using their new [module identifiers](/platform/advanced-deployments/docker-image/docker-image.md#module-identifiers-table) after upgrading. Once added, the JDBC drivers will startup and their database connections will work as expected.
### OPC UA
If you have the [OPC UA](ignition-modules\opc-ua\opc-ua.md) module, new client and server application instance certificates will be generated when you upgrade. The new client certificate will need to be trusted on the server for any **outbound** connections to third party OPC UA servers. Additionally, the new server certificate will need to be trusted on the client side for any **inbound** connections from third party OPC UA clients.
Ignition now uses OPC UA 1.05. Version 1.05 includes better security with role-based access control for your Ignition OPC UA Server, devices, and tag providers. However, this update results in some changes regarding OPC UA access. Namely, anonymous (not logged in) OPC UA clients will no longer have write and call access to devices and Tag Providers by default. Instead, anonymous users will be granted browse and read permissions, while browse, read, write, and call access will be granted to authenticated users.
This change also applies to any device or Tag Provider without explicit role mappings defined. After upgrading, if write and call permissions for anonymous users is necessary, you **must** configure custom permission mappings on the desired devices and Tag Providers to restore that functionality.
Make sure you thoroughly test both anonymous and authenticated OPC UA clients to confirm expected browse, read, write, and call behaviors, especially if they are impacted by the changes detailed above. You can review your [Gateway logs](platform\gateway\web-interface\diagnostics\diagnostics-logs\diagnostics-logs.md) for any OPC UA access errors.
### Projects
After you successfully upgrade to 8.3, you may see an icon in your Designer next to projects that use [Gateway](platform\scripting\scripting-in-ignition\gateway-event-scripts\gateway-event-scripts.md) or [Client Event Scripts](ignition-modules\vision\scripting-in-vision\client-event-scripts\client-event-scripts.md). This indicates that one final step is needed to finish migrating your scripts.
The scripts that have this warning are still fully functional and will continue to work without needing any immediate action. The warning will also disappear when you select the resource in the Designer, as the platform will finish migrating that specific resource.
:::note
Migrated Gateway Event Scripts are located at `%IgnitionInstallationDirectory%/data/projects/%ProjectName%/Ignition/%GatewayEvent%/` as .py files, while migrated Client Event Scripts are located at `%IgnitionInstallationDirectory%/data/projects/%ProjectName%/Ignition/script-python/%ScriptName%/` as .py files.
:::
During this migration, some resources may need to be renamed to comply with our [naming validation schema](appendix\reference-pages\gateway-folder-structure\gateway-folder-structure.md#file-naming-conventions). Keep in mind that changing a script's name can break existing references within your project. You will need to manually update these references to the new script names and ensure your scripts are organized and up-to-date with Ignition 8.3's file structure.
### Third Party Modules
Due to major changes between 8.1 and 8.3, any third party modules will need to be checked to ensure they are compatible with 8.3. Check the official documentation and release notes from the developers of your third party modules for explicit statements of compatibility with Ignition 8.3. If compatibility information is not readily available, contact the support or development teams of your third party modules to inquire about their compatibility with Ignition 8.3.
### User Sources
Ignition 8.3 Gateways do not allow users in Internal or AD/Internal Hybrid User Sources to have the same username. An 8.1 Gateway with Internal or AD/Internal Hybrid User Sources must have duplicate users removed before upgrading. Any duplicate users will be displayed on an 8.1 Gateway User Source's Manage User page, and can also be deleted from there. If an upgrade is attempted before removing duplicates, you will need to restore your 8.1 Gateway, remove the duplicate users and upgrade again. Contact our [Support](https://support.inductiveautomation.com/hc/en-us) team for more assistance.
The migration process now detects User Sources with duplicate users, logs information on the duplicate users, and skips migrating the User Sources, instead of incorrectly migrating and breaking User Sources. It is still recommended to remove all duplicate users before an upgrade is attempted.
## Changes To Be Aware Of
The following sections detail the different changes made in Ignition 8.3.
### Call Scripts
The VOIP Notification call script serialization method has been switched from the Apache Commons library's Locale serialization to Java's built-in language tags, which are deterministic and used elsewhere in Ignition. When upgrading, note that certain locales may now resolve to the same language tag. If you have two different call scripts with these respective locales, it will cause a name collision and one of the records will fail to migrate.
For instance, the following locales are technically different, but share a language tag.
|Locale|Display Name|Language Tag|
|--|--|--|
|nn_NO_NY| Norwegian (Norway, Nynorsk) |nn-NO|
|nn_NO |Norwegian Nynorsk (Norway) |nn-NO|
### Licensing Considerations
The Tag Historian license item has been replaced by the Historian Core and SQL Historian license items. Some modules, such as Serial Support Client, Serial Support Gateway, and Web Browser, have also either been bundled into other modules, bundled into the Ignition platform, or replaced by newer modules. In particular:
* Serial Support Client and Serial Support Gateway have been bundled into the Ignition platform.
* The Web Browser module has been bundled into Vision. Due to this, the Web Browser component can now be found under the Misc category in the Designer's Vision components.
These items will no longer show up as individual modules, but may still be shown as separate license items. Due to the changes to the Historian, individual JDBC drivers will now show up on the Modules page. The license parameter for JDBC drivers will be marked as "Free" rather than "Activated".
### Gateway Security
8.3 Gateway webpages now operate on a required role basis. Certain pages and actions will not be available if a user is not signed in, or does not have the correct [roles or permissions](platform/security/gateway-general-security-settings/gateway-general-security-settings.md#roles-and-permissions). Additionally, permissions granted in 8.1 will not automatically roll over into 8.3, and must be reassigned. Note that some setting names have also been updated.
### Identity Providers
The shape of an exported JSON file for an Identity Provider on the Gateway has changed from 8.1 to 8.3, which means importing Identity Providers from 8.1 Gateways onto 8.3 Gateways is currently not supported.
### Service Security and Security Zones
Service security settings are now part of Security Zone configurations. To modify [service security settings for a policy](platform/security/service-security/service-security.md) in 8.3, you can click on the three dots menu on the right of the zone you want to modify on the Security Zones Gateway page and select **Manage Policy**.
If you have a policy defined on the `default` security zone, it will be brought in as part of the Gateway Deployment Mode's core collection for that zone.
### Enterprise Administration
The Agent Recovery EAM task has been removed from Ignition 8.3. You can still use other agent tasks to perform a similar operation.
The 8.3 [License Management](ignition-modules\enterprise-administration\agent-management\license-management\license-management.md) page on the controller Gateway can now display and manage leased licenses (eight-character licenses). Additional information, such as the last renewal timestamp and result, will be displayed. The Activate License, Update License, and Unactivate license tasks will also work with leased licenses.
The EAM Remote Upgrade task cannot upgrade Ignition agents from version 8.1.x to 8.3.x on Apple M-series Macs. This is because Ignition 8.3.0 introduced native builds for M-series architecture, whereas version 8.1.x only supported the x86 architecture. The EAM task doesn't handle the architecture change that occurs during this specific upgrade. To upgrade these agents, you must perform an in-place upgrade instead of using EAM. Once the agent is successfully upgraded to version 8.3.0 using this method, subsequent EAM Remote Upgrades task (e.g., to 8.3.1) will work.
:::note
When using the **Send Project** or **Send Project Resources** task, some resources, such as Gateway Event Scripts and Perspective Event Scripts, cannot be sent from an 8.3 EAM controller to an 8.1 agent.
:::
### Store and Forward
When upgrading your historians, the [Store and Forward](platform\store-and-forward\store-and-forward.md) **Primary Store Maintenance Value** property (known in 8.1 as Max Records) will be set to zero by default. This means that the local disk cache is configured to store an unlimited number of data points before forwarding them to the historian.
This is possible due to the Store and Forward engine now utilizing multi-threading, allowing different data types to be stored and forwarded at the same time without blocking another, namely:
* Alarming
* Auditing
* Scripting
* SECS/GEM
* Tag history
* Transaction Group
Quarantine exports have also been changed to use JSON rather than XML. This means that quarantine exports from 8.1 Gateways cannot be imported into 8.3 Gateways.
When upgrading the Gateway, the Store and Forward system will begin converting your old serialized data. Any leftover data will remain as an HSQL file, and should be moved to `%IgnitionInstallationDirectory%/data/local/store-forward/quarantined-databases/`.
### Tags
The `Alarms` folder in the [Tag Browser](platform\tags\tag-browser\tag-browser.md) for tags with alarms has been replaced with a new `Alarm Metrics` folder, providing a new set of metrics for scripting and monitoring issues. This change also makes it easier to find the `Alarm Metrics` folder, and improves performance related to tag alarm metrics. Existing scripts and bindings will still work with the deprecated `Alarms` folder.
Additionally, due to the Gateway file system changes, tag JSON files are now stored with the path that's shown in the Tag Browser following `C:\Ignition\8.3.0\data\config\resources\core\ignition\tag-definition`. This change can result in long filepaths, and may impact Windows users since the Windows API has a filepath limit of 255 characters. See the [Working with Long File Paths](../../../tutorials/tutorials-and-helpful-tricks/working-with-long-paths/working-with-long-paths.md) page for more information on how your system may be impacted.
Note that the names of files and directories are still bound by names less than 255 characters long, and this change is focused on the filepaths themselves.
### OPC UA
Ignition will not migrate any data within the `Iec61850ReportEntryIds` table, which uses reports that are subscribed to IEC61850 devices to help Ignition keep track of the latest ID it has received. In certain scenarios, migrating this data would cause Igntion to attempt to store duplicate data, resulting in the data being quarantined in the Store and Forward system.
### Perspective
#### File Upload Component
The File Upload component will now only accept files smaller than 20 MB, regardless of the [fileSizeLimit](appendix\components\perspective-components\perspective-input-palette\perspective-file-upload\perspective-file-upload.md#properties) property. This can be increased using the max-file-size property within the [web.xml](appendix\reference-pages\web-xml-file-reference\web-xml-file-reference.md) file.
#### Browser Requirements
The Ignition 8.3 minimum browser versions required to run Perspective Sessions have changed from 8.1. See the [Browser Version Requirements](ignition-modules\perspective\perspective-sessions\perspective-sessions.md#browser-version-requirements) page for the current list to make sure you meet the new minimums before upgrading.
### Launcher Considerations
Application launchers and Perspective Workstation running 8.3 are backwards compatible with 8.1. However, 8.1 launchers and Perspective Workstation are not forward compatible with 8.3. Because of this, you can use [DeepLinks and File Associations](launchers-and-workstation\launchers-and-workstation.md#deep-link-and-file-association-support) to open projects hosted on 8.1 Gateways.
### Hot Swapping Modules
Hot swapping modules is no longer supported in Ignition 8.3. You will need to restart your Gateway if you want to install or upgrade a module.
### System Function Changes and Deprecations
Ignition 8.3 introduces two new sets of system functions, prefixed by `system.vision` and `system.historian`.
The [`system.vision`](appendix\scripting-functions\system-vision\system-vision.md) namespace replaces many system functions from different subsystems, including:
* `system.file`
* [`system.gui`](versioned_docs\version-deprecated\system-functions\system-gui-deprecated\system-gui-deprecated.md)
* `system.nav`
* `system.net`
* `system.print`
* `system.security`
* [`system.util`](versioned_docs\version-deprecated\system-functions\system-util-deprecated\system-util-deprecated.md)
Many of the replaced system functions are still functional, but it is recommended to utilize the `system.vision` namespace instead.
The [`system.historian`](appendix\scripting-functions\system-historian\system-historian.md) namespace both introduces new system functions and replaces others. The following table of system functions have been deprecated, replaced with various `system.historian` functions:
| System Function | Replacement System Function |
|:---|:---|
| `system.tag.browseHistoricalTags` | `system.historian.browse` |
| `system.tag.queryTagHistory` | `system.historian.queryRawPoints` |
| `system.tag.queryTagCalculations` | `system.historian.queryAggregatedPoints` |
| `system.tag.queryTagDensity` | No Replacement Function |
| `system.tag.queryAnnotations` | `system.historian.queryAnnotations` |
| `system.tag.storeTagHistory` | `system.historian.storeDataPoints` |
| `system.tag.storeAnnotations` | `system.historian.storeAnnotations` |
| `system.tag.deleteAnnotations` | `system.historian.deleteAnnotations` |
In addition to the new system function namespaces, the `system.db` namespace has been overhauled with the following deprecated and replacement functions listed in the table below.
| Deprecated System Function | Replacement System Function |
|:---|:---|
| `system.db.clearAllNamedQueryCaches` | `system.db.clearCache` |
| `system.db.clearNamedQueryCache` | `system.db.clearCache` |
| `system.db.dateFormat` | `system.date.format` |
| `system.db.refresh` | `system.vision.refreshBinding` |
| `system.db.runNamedQuery` | `system.db.execQuery`, `system.db.execUpdate` |
| `system.db.runQuery` | `system.db.execQuery`, `system.db.runPrepQuery` |
| `system.db.runScalarQuery` | `system.db.execScalar`, `system.db.runScalarPrepQuery` |
| `system.db.runSFNamedQuery` | `system.db.execQuery` |
| `system.db.runSFUpdateQuery` | `system.db.execUpdateAsync`, `system.db.runSFPrepUpdate` |
| `system.db.runUpdateQuery` | `system.db.execUpdate`, `system.db.runPrepUpdate` |
Other functions that have been deprecated include the various `system.net.http*` functions, which can now be performed using the [`system.net.httpClient`](../../../appendix/scripting-functions/system-net/system-net-httpClient.md) function.
The following system functions have been deprecated, with no new system function replacements:
* `system.gui.convertPointToScreen`
* `system.gui.getQuality`
* `system.dataset.toPyDataSet`
* Note that this function has been deprecated because datasets no longer need to be manually wrapped as PyDatasets. This change also impacts `system.dataset.toDataSet` from 8.1, which now has only a single syntax and should be written as [`system.dataset.toDataset`](../../../appendix/scripting-functions/system-dataset/system-dataset-toDataset.md) in 8.3.
### Custom Themes
In 8.1, theme authorship relied solely on the filesystem. In 8.3, the new config and resource collection model required the existing theme structure to conform to this new model. The old entry point files that existed at the root of the themes folder have been removed. Instead, each respective theme gets a `config.json`.
Within this config file is an `isPrivate` property that when set to true will prevent this theme from being listed as an available theme. This is useful in instances where you may have a common or shared set of theme resources that other themes might import or extend. Also within this config file is an `entrypoint` property that lets Ignition know where to start processing your theme. This is generally an `index.css` file that exists within your theme folder. See the [Creating and Using Custom Perspective Themes](../../../ignition-modules/perspective/styles/creating-and-using-custom-perspective-themes.md) page for more information on how the new file structure works.
If you followed the structure and format Ignition used for the built-in themes (light, dark, light-cool, dark-warm, etc.) in 8.1, then your themes will migrate successfully. If not, you will likely need to update some of your imports, and in some situations create a new theme. For example, if your old `custom-theme.css` entry file had an import like `@import “./light.css”`, you will need to add `@import “../light/index.css”` to your theme's entrypoint file. Additionally, all external imports or declarations you might have had in the old entry file will need to be moved into the new entrypoint file for your theme. You can find all of the original migrated files in the `.migrated-themes-TIMESTAMP` directory within `data/modules/com.inductiveautomation.perspective` for reference when resolving your imports and into this new structure.
In circumstances where you had an old entry file (i.e., themes/test-theme.css), but no peer directory of the same name (i.e., themes/test-theme), one will be created as part of the migration process. Within this migrated directory will be an `index.css` entrypoint. You will need to update this `index.css` to include any imports you might have included in the old entry file as Ignition will not attempt to resolve, modify, or move any imports during the migration.
## Discontinued Features
### Deprecated Expression Functions
The `forceQuality` expression function has been deprecated. Users should instead utilize the `qualifiedValue` [expression function](appendix\expression-functions\advanced\qualifiedValue.md).
### Designer
The Identity Provider property within the Designer's **Project Properties** > **Perspective** > **General** has been deprecated. The [Identity Provider setting](platform\designer\project-properties\project-properties.md) under **Project Properties** > **Project** > **General** will be used instead.
### Perspective
The `pager.initialOption` property for Perspective [Tables](appendix\components\perspective-components\perspective-display-palette\perspective-table\perspective-table.md) has been deprecated and replaced with a new `option` property. This new property improves on the deprecated property by honoring external writes even after the table initializes upon loading.
### Tag Historian
[Custom Tag History Aggregates](versioned_docs/version-deprecated/modules/tag-historian/custom-tag-history-aggregates/custom-tag-history-aggregates.md) have been deprecated, as this was originally intended to be a workaround to older SQL historian schema limitations. This feature is only supported when used with the legacy `system.tag.queryTagHistory` and `system.tag.queryTagCalculations` functions, which are also deprecated. While still functional, these features are no longer recommended for new development.
## New Features
The following sections details new major features added in Ignition 8.3. See the [New in this Version](new-in-this-version\new-in-this-version.mdx) page for information on all new features.
### Modules
The following is a list of modules introduced in Ignition 8.3:
* Event Streams
* Kafka Connector
* MariaDB JDBC Driver
* MSSQL JDBC Driver
* PostgreSQL JDBC Driver
* Siemens Enhanced
* SQL Historian
### Drivers
A new [Siemens Enhanced driver](ignition-modules\opc-ua\opc-ua-drivers\siemens\siemens.md) is available through the Siemens Enhanced Driver module. This new driver supports browsing and symbolic access when connected to S7-1200 and S7-1500 devices.
### Event Streams
[Event streams](ignition-modules\event-streams\event-streams.md) have been added to Ignition 8.3 as project resources, and allow users to pull data from a specified source, perform different actions on the data, and send it to a defined handler.
Event streams operate in stages, with each stage performing a different action. Some stages, such as filtering and transforming, are optional. Each stage and their function is displayed below:
| Stage | Description |
|:---|:---|
| Source | The origin of the data to send through the event stream. |
| Encoder | Encodes the data in the event stream into a specified format. |
| Filter | Filters out any unwanted or unnecessary data using a script. |
| Transform | Transforms the data from one type of object to another, with the new object being sent down the event stream. |
| Buffer | The staging area for event data, batched together based off a set of defined parameters. Batches of data will be sent once the parameters are met. |
| Handler | Takes the data from the event stream and performs a user-defined action with them. Multiple handlers can be utilized at the same time, allowing your data to be sent to different places or used in different ways. |
| Error Handler | Acts as a final catch-all for any missed errors during the event stream. |
### Gateway Deployment Modes
[Gateway deployment modes](platform\gateway\web-interface\platform\gateway-deployment-modes\gateway-deployment-modes.md) allow you to create different configurations of your Gateway. These configurations can be preset with different values for Gateway resources and properties, creating a separate environment.
Deployment modes are created in the Gateway, but utilize the [Gateway Configuration File](appendix\reference-pages\gateway-configuration-file-reference\gateway-configuration-file-reference.md) when you want to switch the deployment mode your Gateway is running in.
You can also modify deployment modes through Ignition's file system. If modified this way however, the Gateway will not recognize any changes until the file system is scanned and updates are brought in.
Deployment modes follow [Gateway security](#gateway-security) logic, meaning any unauthorized users will not be able to view Gateway configuration pages or resources unless permissions and access roles are defined.
### Historians
A new [Core Historian](ignition-modules\tag-historian\tag-history-providers\tag-history-providers.md#core-historian) was introduced in 8.3. This new Historian, initially referred to as the Power Historian, is powered by QuestDB and optimized for storing time-series data. The Core Historian will automatically partition data by tables, using specified intervals set within the Historian's configuration. Additionally, the Core Historian will only use the Store and Forward system if there are pending writes to the database. If there are no pending writes, the Core Historian will skip the Store and Forward system entirely.
The historian changes additionally introduced a change in formatting for qualified historical paths. The path still relies on key-values pairs, but instead of using `drv` to include both the Gateway and Tag Providers names, `sys` and `prov` need to be used to identify the Gateway name and Tag Provider name, respectively.
```python title="Syntax Examples"
# 8.1 Historical Path Syntax
histprov:Sample_DB:/drv:myGateway:My_Provider:/tag:My_Folder/Another_Folder
# 8.3 Historical Path Syntax
histprov:Sample_DB:/sys:myGateway:/prov:My_Provider:/tag:My_Folder/Another_Folder
```
Note that the SQL Historian still requires the `drv` key-value pair syntax, and any `drv` syntax used in Ignition 8.1 will still work in 8.3.
:::info
The Internal Historian (Legacy), powered by SQLite, is still available to use.
:::
Ignition 8.3 also introduces new `system.historian` [functions](appendix\scripting-functions\system-historian\system-historian.md), allowing users to interact with Ignition's Historian system. Some of these new functions have replaced deprecated functions. See the [System Function Changes](#system-function-changes-and-deprecations) section for more information on which functions have been deprecated.
### Launchers and Workstation
You can now set [deep links and file associations](launchers-and-workstation\launchers-and-workstation.md#deep-link-and-file-association-support) to launch your application without needing to open the launcher. Keep in mind that the file extension and URL protocol associations options must be enabled when installing the launcher.
Deep links will allow you to open a project or Designer with a URL. These URLs use the following format: `%LauncherType%://%GatewayAddress%/%ProjectName%`. For example, if you wanted to launch a local Perspective project through Workstation, the URL would be: `perspective://localhost:8088/MyPerspectiveProject`.
File Associations allow you to customize how to launch projects by using JSON files based off the launcher type. Each launcher will use a different file extension:
* Perspective Workstation: .perspective
* Vision Client Launcher: .vision
* Designer Launcher: .designer
### Perspective
Perspective has several new features in 8.3, including the [Drawing](appendix\components\perspective-components\perspective-display-palette\perspective-drawing\perspective-drawing.md) component, [Form](appendix\components\perspective-components\perspective-input-palette\perspective-form\perspective-form.md) component, and [Offline Mode](ignition-modules\perspective\perspective-sessions\ignition-perspective-app\offline-mode\offline-mode.md).
The Perspective Drawing component allows you to create custom drawings and images, similar to Vision's [Drawing Tools](ignition-modules\vision\working-with-vision-components\drawing-tools\drawing-tools.md). You can also import vector graphics (SVGs) and images that use .gif, .jpeg, and .png file extensions.
The Perspective Form component makes inputting data much easier for your users. Different aspects of the form can be customized, such as dynamically displaying fields depending on user input and creating validation rules. You can use bindings to further tailor the form to behave exactly how you need.
Finally, Offline Mode allows users to continue using a Perspective project, even if the project loses network access to the Gateway. This is useful in scenarios like when you are using a mobile device, remote locations, and unstable network connectivity. Some features will not be available if a project is running in Offline Mode, including:
* Realtime values from tags, alarms, and queries
* Gateway Event or database scripts
* Previously unloaded views
Any data inputted by a user running in Offline Mode will be cached until network connectivity is restored, after which the data will be sent to the appropriate location.
### Reporting
The following [components](appendix\components\report-design-components\report-design-components.md) can be used as either raster or vector images:
* Barcode
* Bar Chart
* Pie Chart
* Radar Chart
* Timeseries Chart
* XY Chart
A new [Radar Chart](appendix\components\report-design-components\report-design-chart-palette\report-component-radar-chart\report-component-radar-chart.md) component is also available to use on reports.
### Scripting
When using a scripting window, the [autocomplete and hints](platform\scripting\scripting-in-ignition\scripting-in-ignition.md#system-functions-hints-and-autocomplete) feature will also list system library constants and identify deprecated functions.
### Security
You can encrypt secrets such as credentials, API tokens, and private keys using the 8.3 [Secrets Management](platform\security\secrets-management\secrets-management.md) system and customize different aspects of it using Secret Providers. You can also use the [Secrets Management Key CLI Tool](platform\security\secrets-management\secrets-management-key-cli-tool\secrets-management-key-cli-tool.md) to manage keys and run scripts from the command line.
### Tags
A new System Tags folder called [ModuleVersions](platform\tags\types-of-tags\system-tags\system-tags.md#eam-system-tags) has been added to help EAM controllers monitor module versions on connected agents.
## Post Upgrade Actions
The following sections detail different actions to take after upgrading to 8.3.
### Verifying System Health
It is good practice to ensure everything is working correctly after upgrading. The following list of tips is not exhaustive, but can help ensure your system is working properly.
* Check the Diagnostics Overview page for a quick top-level view of your system. This page is found on the **Gateway Webpage** > **Diagnostics** > **Overview**.
* Check your Gateway and wrapper logs for any repeated warnings or errors. See the [Logs](#logs) section for more details.
* Verify that historical data is still being stored.
* Verify your projects are still functioning correctly.
* Make sure that all behavior after upgrading is expected, and that there are no unintended actions or consequences.
:::tip Modules Running in Trial Mode?
If your modules show a Trial license status after upgrading when Activated is expected, you may need to reactivate your license. Once your license has be reactivated, the modules will display an Activated status.
:::
### Troubleshooting Issues
If you run into any problems while upgrading or after upgrading, we recommend reaching out to our [Support](https://support.inductiveautomation.com/hc/en-us) team. When creating a ticket, please provide a detailed explanation and any relevant resources, including any photos or screenshots that help illustrate the problem.
The section below details the various logs and locations that pertain to an upgrade that you can provide our Support team. If you are able to reliably reproduce the issue, please document the exact steps and include any necessary resources used during your replication attempts. For instructions on how to roll back to a previous version, refer to the [System Rollback](/getting-started/installing-and-upgrading/installing-and-upgrading.md#system-rollback) section of Installing and Upgrading page.
:::note
During the upgrade process, Ignition migrates resources from the internal database (IDB) to the new file system. The deprecated IDB is not removed after upgrading, but will not affect your system as it is no longer used.
:::
### Logs
The following table displays different types of logs that can help troubleshoot errors from upgrading and the log locations.
| Log Directory | Type of Log | Description |
|:---|:---|:---|
| `%IgnitionInstallationDirectory%/logs/` | Wrapper | Provides information about the Gateway, its subsystems, and errors from Gateway-scoped resources. |
| `%IgnitionInstallationDirectory%/logs/` | Tag-migration | Provides information about the migration status of different Tag Providers. Each Tag Provider will have its own JSON migration file, with a summary of metrics for different issues, and the affected tag paths. |
| `%IgnitionInstallationDirectory%/logs/` | install_`{YYYYMMDD-HHmm}` | Provides information about the installer for the extraction and replacement of the core Ignition 8.3 file system, after which the Ignition service is started. |
| `%IgnitionInstallationDirectory%/data/config/resources/` | migration-log | Provides a summary of migrated IDB resources to the Ignition 8.3 file system, along with information about tables that either failed to migrate or have yet to be migrated. |
| `%IgnitionInstallationDirectory%/data/projects/` | Conversion-report | Provides information about the conversion of project resources to the Ignition 8.3 file system. |