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

Please read this guide carefully before upgrading a production Gateway.

8.3 Beta Release

Please review this list of selected known issues that are present in the current beta release of 8.3.

Important Considerations

Before performing any kind of upgrade, it is good practice to first take a Gateway Backup 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

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.

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.

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.1 Gateways are not able to store data to 8.3 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.

Enterprise Administration (EAM)

When upgrading from 8.1 to 8.3 using EAM, you will need to first run the Install Modules task to install the historian modules on the remote Gateway. This must be done prior to running the Remote Agent Upgrade task. New modules that must be installed before running the Remote Agent Upgrade task include:

• SQL Historian
• Event Streams
• Kafka
• Any JDBC Driver modules

In addition, make sure to run the Remote Agent Upgrade task against the most recent version of Ignition 8.1. This will help eliminate issues or errors when running the task.

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.

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

OPC UA

If you have the OPC UA 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 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 or Client Event Scripts. 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. 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.

Changes To Be Aware Of

The following sections detail the different changes made in Ignition 8.3.

Licensing Considerations

The Tag Historian license item has been replaced by the Historian 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. Additionally, permissions granted in 8.1 will not automatically roll over into 8.3, and must be reassigned.

Service Security and Security Zones

Service security settings have been renamed to Manage Policy and are now part of Security Zone configurations. To modify service security settings in 8.3, you can click on the three dots menu on the right of the item you want to modify, then 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 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.

Store and Forward

When upgrading your historians, the Store and Forward 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 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.

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

Ignition 8.3 introduces two new sets of system functions, prefixed by system.vision and system.historian.

The system.vision namespace replaces many system functions from different subsystems, including:

• system.dataset
• system.db
• system.file
• system.gui
• system.nav
• system.net
• system.print
• system.security
• system.tag
• system.util

Many of the replaced system functions are still useable, but it is recommended to utilize the new system.vision functions instead.

The system.historian 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	system.historian.queryAggregatedPoints
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 introducing two new system function namespaces, the system.db namespace has been overhauled to have many functions deprecated, replaced, or introduced. The following table details these changes:

System Function	Deprecated	Replacement System Function
system.db.addDatasource	Yes	None
system.db.removeDatasource	Yes	None
system.db.setDatasourceConnectURL	Yes	None
system.db.setDatasourceEnabled	Yes	None
system.db.setDatasourceMaxConnections	Yes	None
system.db.clearNamedQueryCache	Yes	system.db.clearCache
system.db.clearAllNamedQueryCaches	Yes	system.db.clearCache
system.db.dateFormat	Yes	system.date.format
system.db.beginTransaction	No	system.db.transaction
system.db.beginNamedQueryTransaction	No	system.db.transaction
system.db.closeTransaction	No	system.db.transaction
system.db.commitTransaction	No	system.db.transaction
system.db.rollbackTransaction	No	system.db.transaction
system.db.createSProcCall	No	system.db.storedProcedure
system.db.execSProcCall	No	system.db.storedProcedure
system.db.refresh	Yes	system.vision.refreshBinding
system.db.runQuery	Yes	None
system.db.runUpdateQuery	Deprecated in Vision only	None
system.db.runPrepQuery	Deprecated in Vision only	None
system.db.runPrepUpdate	Deprecated in Vision only	None
system.db.runScalarQuery	Yes	None
system.db.runScalarPrepQuery	Deprecated in Vision only	None
system.db.runSFPrepUpdate	Deprecated in Vision only	None
system.db.runSFUpdateQuery	Deprecated in Vision only	None
system.db.runNamedQuery	No	system.db.execQuery
system.db.runSFNamedQuery	No	system.db.execQuery

The system.net.httpClient function has also been updated to act as a namespace for various system.net.http* functions. You can now perform many HTTP actions using only the system.net.httpClient function.

See the Deprecated System Functions section for more information about which system functions have been deprecated with no replacements.

Discontinued Features

The following sections detail features that have been deprecated.

Deprecated System Functions

The following system functions have been deprecated, with no new system function replacements:

• system.gui.convertPointToScreen
• system.gui.getQuality
• system.dataset.toPyDataSet

Deprecated Expression Functions

The forceQuality expression function has been deprecated. Users should instead utilize the qualifiedValue expression function.

Designer

The Identity Provider property within the Designer's Project Properties > Perspective > General has been deprecated. The Identity Provider setting under Project Properties > Project > General will be used instead.

Perspective

The pager.initialOption property for Perspective Tables 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 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.

Susan's note: replace link to custom tag history deprecated page after sorting that out

New Features

The following sections details new major features added in Ignition 8.3. See the New in this Version 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 Module
• PostgreSQL JDBC Driver Module
• Siemens S7 Symbolic Driver Module
• SQL Historian Module

Drivers

A new Siemens driver is available through the Siemens S7 Symbolic Driver module. This new driver supports browsing and symbolic access when connected to S7-1200 and S7-1500 devices.

Event Streams

Event streams 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 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 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 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 Local Historian was introduced in 8.3. This new Local Historian, initially referred to as the Power Historian and powered by QuestDB, is optimized for storing time-series data. The Local Historian will automatically partition data by tables, using specified intervals set within the Historian's configuration. Additionally, the Local Historian will only use the Store and Forward system if there are pending writes to the database. If there are no pending writes, the Local Historian will skip the Store and Forward system entirely.

The original Internal Historian, powered by SQLite, is still available to use.

Ignition 8.3 also introduces new system.historian functions, allowing users to interact with Ignition's Historian system. Some of these new functions have replaced deprecated functions. See the Deprecated System Functions section for more information on which functions have been deprecated.

Launchers and Workstation

You can now set deep links and file associations 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 component, Form component, and Offline Mode.

The Perspective Drawing component allows you to create custom drawings and images, similar to Vision's Drawing Tools. 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 can be used as either raster or vector images:

• Barcode
• Bar Chart
• Pie Chart
• Radar Chart
• Timeseries Chart
• XY Chart

A new Radar Chart component is also available to use on reports.

Scripting

When using a scripting window, the autocomplete and hints 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 system and customize different aspects of it using Secret Providers. You can also use the Secrets Management Key CLI Tool to manage keys and run scripts from the command line.

Tags

A new System Tags folder called ModuleVersions 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 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.

Troubleshooting Issues

If you run into any problems while upgrading or after upgrading, we recommend reaching out to our Support 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 section of this document.

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.

System Rollback

Downgrading Ignition is not a supported use case of the Ignition upgrade, and can lead to unexpected problems. If you need to roll back to a previous version of Ignition, it is recommended to instead perform a clean reinstallation and restore a Gateway backup from the same version or older. When reinstalling Ignition, the Ignition service should first be uninstalled, and the Ignition installation directory itself should be deleted.