Upgrading from 3.4 to 4.0

Jump to Section

This section covers upgrading an existing 3.X installation to 4.0, including any manual migration that is required. In most cases, no manual migration is necessary.

Upgrading the JVM

Version 4.0 requires minimum a JVM of 21. If you were not using v21 for 3.X you will need to upgrade the JVM.

Upgrading Configuration and State to 4.0

4.0 by default places all application state in an appData directory, next to the existing runtime and configuration directories.

If the old installation relied on the default behavior of storing application state in the runtime directory or relied on the default behavior of finding the intelligencehub-settings.json in the runtime directory, you will need to manually move application state files before launching 4.0. Follow the steps below.

Shutdown the existing 3.4 (or older) runtime
Backup the existing 3.4 installation to ensure no data is lost
Unzip the new 4.0 installation in a new directory
Copy the following files from the 3.4 runtime directory to the 4.0 appData directory
- intelligencehub-settings.json
  - If the settings.directories.appData setting was used in this file to store application state in another directory then only move this file and ignore the rest
- Any and all files with a .json extension
  - intelligencehub-configuration.json
  - intelligencehub-remoteconfig.json
  - intelligencehub-secrets.json
  - intelligencehub-systemvariables.json
  - intelligencehub-users.json
- Any and all files with a .db extension
- intelligencehub-certificatestore.pcks12
- intelligencehub-state.dat
- intelligencehub-events.json
- intelligencehub-events.log
Run the new 4.0 installation. 4.0 will find the appData files, upgrade them as needed and launch the Intelligence Hub.

Upgrading Remote Configuration

If your old installation was using remote configuration, you’ll need to upgrade all Intelligence Hub instances to version 4.0. This includes central and remote hubs. The protocol for remote configuration was updated significantly to support future migrations and new capabilities.

Other

{{System.Internal.Datetime}} references

The reference {{System.Internal.Datetime}} and other Datetimes are now bound to JavaScript as a Date data type. JavaScript expressions like “{{System.Internal.Datetime}} + 1” will now evaluate to a string in the form “Tue Jun 11 2024 18:50:00 GMT+0000(GMT)1”. In 3.x this would evaluate to a number (unix epoch time + 1). To keep the previous behavior, update the expression as follows “{{System.Internal.Datetime}}.getTime() + 1”.

{{System.Flows}} and {{System.Flows.Flowname}} references

In 4.0 all existing Flows are migrated to pipelines. This means if system references were being used to monitor flow status, these must be manually upgraded to {{System.Pipelines}} or {{System.Pipeline.PipelineName}} references. Pipelines have more advanced statistics to perform better troubleshooting.

Removed Global REST Data API Tokens

If the old installation was using a global API token, configured under Settings, these will no longer work in 4.0. You must create a new API Token that is linked to a User Account. These new tokens can be global, but can also be scoped to limit access.

v1/ REST API Configuration Routes

The v1/model and v1/instance routes have been removed. If these were being used to build models/instances we recommend instead using the v1/project/import and export APIs that can be found in the guide.

hub.withMetaData{{Connection.opc.tag}}

This method only works with Instances in Legacy Mode to support upgrading. This method is not available for Instances with Legacy Mode disabled. As an alternative, enable the Include Metadata option for the OPC input to get the timestamp and quality for the tag.

Docker