Installer Upgrade
If you use the
ThingWorx Foundation Installer to install ThingWorx Foundation 8.5.0 or later, you can use the installer to upgrade ThingWorx Foundation, including maintenance release upgrades. For links to supported upgrade matrices for each ThingWorx version, see
Upgrading ThingWorx.
|
Starting with ThingWorx 9.4, customers are not able to upgrade directly from ThingWorx 8.5 or ThingWorx 9.0, to ThingWorx 9.4.0. Customers wishing to upgrade to 9.4.0 and later, from ThingWorx 8.5 or ThingWorx 9.0, need to upgrade to an intermediate version and then upgrade to ThingWorx 9.4.0 and later. ThingWorx recommends using latest ThingWorx 9.3.x as the intermediate upgrade path.
|
|
If you are upgrading to ThingWorx 9.2 and PostgreSQL 13, upgrading PostgreSQL will be the last step in the upgrade process.
|
|
If you are upgrading from ThingWorx 9.1.x and PostgreSQL 12 to ThingWorx 9.4.x and Postgre 13, then upgrade as following:
1. Upgrade to ThingWorx 9.3.x
2. Upgrade to PostgreSQL 13
3. Upgrade to ThingWorx 9.4.x
|
|
The user performing the upgrade must be the same user who performed the application's original installation.
|
|
ThingWorx Installer does not support upgrading Content Security Policy. There are several manual steps if upgrading to ThingWorx 9.5.1 or newer.
|
A.) Prerequisites
• Java Requirements (the installer does not package or install Java as part of the installation):
◦ The user that initially installed ThingWorx should run the upgrade. During the initial installation, the installer generates the ThingWorxFoundation.xml file, which includes information about the installation and is required for the upgrade. This file is located under the user profile of the user running the installation. For example, within C:\Users\Administrator\.ptc_cci.
◦ ThingWorx Foundation 9.2 requires Java 11, but Java 8 must also be installed. Verify that supported versions of Java 8 and 11 are installed before running the installer. Add Java 11 to the PATH environment variable.
◦ If you are running ThingWorx 9.0 or lower on Java 8, and are upgrading to ThingWorx 9.2, you must pre-install Java 11 but do not switch ThingWorx to point to the new jvm. JAVA_HOME should remain set to the Java 8 folder. Both Java directories should be in the PATH environment variable, but java8/bin should be listed before java11/bin in the PATH variable. During the upgrade to 9.2, the installer will also switch the version of Java that is in use to Java 11, as ThingWorx 9.2 does not support Java 8.
◦ If you are running ThingWorx 9.1, it supports Java 8 and Java 11, so you can either follow the advice above (install both, have both in path), or you can migrate your ThingWorx 9.1 instance to Java 11 before starting the upgrade.
• Back up your database. The installer does not run a database backup during the upgrade process.
• You must have one of the following operating systems with these database combinations:
◦ Windows with PostgreSQL
◦ Windows with Microsoft SQL Server
◦ Red Hat Enterprise Linux with PostgreSQL
◦ Red Hat Enterprise Linux with Microsoft SQL Server
• The upgrade will fail if any of the custom index field values are missing in the data tables. Verify all custom index fields have values before starting the upgrade process.
• If you are upgrading to a ThingWorx version that supports Content Security Policy, copy web.xml from “<tomcat_install_dir>/webapps/Thingworx/WEB-INF” to another folder for use later.
B.) Run the ThingWorx Upgrade Ready Utility
If you have ThingWorx Foundation 8.5.3 or earlier installed, you should first run the ThingWorx Upgrade-Ready Utility, available at > > > > > .
The ThingWorx Upgrade-Ready Utility creates XML files needed to support the automated upgrade of ThingWorx Foundation, and if installed, ThingWorx Flow. The utility prompts you to locate ThingWorx Foundation, and if installed, ThingWorx Flow, on your system and then configures the selected installations. It creates the ThingWorxFoundation.xml file, and if you have ThingWorx Flow installed, the ThingWorxFlow.xml file, in your user profile. The files are saved in the .ptc_ccif folder in your user profile (for example, on Windows: C:\Users\Administrator\.ptc_ccif; on Linux: ~/.ptc_ccif/).
If you installed ThingWorx 8.5.4 or later using the installer, the necessary XML files have already been created as part of the installation; therefore, it is not necessary to run the ThingWorx Upgrade-Ready Utility.
Troubleshooting
• If you used the installer to install ThingWorx Foundation 8.5.3 or earlier, then manually upgraded to a later 8.5.x version, and are now preparing to upgrade to 9.x by running the ThingWorx Upgrade Ready Utility, do the following:
◦ Run the ThingWorx Upgrade-Ready Utility.
◦ Validate that the <applicationVersion> property value in the ThingWorxFoundation.xml file in your user profile is your current version.
• If you had issues running the ThingWorx Upgrade-Ready Utility and need to manually create or edit the ThingWorxFoundation.xml file, you can use the following example and update it based on your upgrade path:
<?xml version="1.0" encoding='utf-8'?>
<installationInfo>
<projectFlavor>PostgreSQL</projectFlavor>
<applicationName>ThingWorxFoundation</applicationName>
<applicationVersion>9.0.1</applicationVersion>
<applicationInstallDir>C:\Program Files
(x86)\ThingWorxFoundation</applicationInstallDir>
</installationInfo>
C.) Upgrade
| If you upgrade ThingWorx and you are using CAS as AzureAD and connecting to a resource server using ThingWorx connectors based SSO connection type, then you must set the property mandatoryScopes in AuthorizationServersSettings in the sso-settings.json file to include offline_access. Due to the change in AzureAD behavior, the process of acquiring a new token does not provide a refresh token. As a result, after the access token expires, we cannot refresh it during the session. To overcome this issue, the user must log in again, returning the fresh token healthy and solving the issue permanently. |
1. Ensure that the prerequisites described in the above sections are met.
2. Obtain and download the latest ThingWorx Foundation installer files for on-premise installations at
support.ptc.com under
Download Software >
Order or Download Software Updates >
ThingWorx Foundation >
Release x.x >
ThingWorx PostgreSQL or
ThingWorx Mssql .
3. The installer lists your existing installation information, including:
◦ Installation directory
◦ Port
◦ SSL configuration setting
◦ SSO configuration setting
4. You are presented with the PTC license agreement. You must accept the terms of the agreement before continuing with the upgrade.
5. You must enter the ThingWorx Foundation administrator password, or if SSO is configured, enter your
application key.
6. You can review and confirm your installation configuration information.
7. The installer will complete the upgrade.
You can now upgrade extensions and applications to versions that are compatible.
D.) Migrate Time Zone Data
| Migrating Time Zone data is not necessary when updating to ThingWorx 9.4.0 and later. Direct upgrades are not supported from ThingWorx 8.5 or ThingWorx 9.0, to ThingWorx 9.4. Migrating time zones will be done during the migration process to the intermediate version. |
You must perform critical data migration steps in this section if one of the following is true:
• You had ThingWorx 8.5.x installed and used the installer to upgrade to ThingWorx 9.0.x or 9.1.
• You had ThingWorx 9.0.x installed and used the installer to upgrade to ThingWorx 9.0.3 or later.
To perform this data migration, do the following:
1. Immediately after successful upgrade, stop ThingWorx and Apache Tomcat.
2. Manually set the time zone parameter -Duser.timezone=UTC using the steps below based on your operating system.
Configure Time Zone Settings on Windows
1. Stop the ThingWorx-Foundation service.
2. Run CMD as the administrator.
3. Go to the Tomcat /bin directory under the ThingWorx Foundation installation directory.
For example: cd C:\Program Files (x86)\ThingWorxFoundation\tomcat\apache-tomcat-9.0.37\bin.
4. Edit the ThingWorx-Foundation service configuration to open the GUI application by executing the following:
tomcat9w.exe //ES//ThingWorx-Foundation
5. Go to the Java tab on the GUI application.
a. To Java Options, add the following:-Duser.timezone=UTC
b. Choose Apply.
6. Choose OK to close the GUI.
7. Update service parameters using tomcat9.exe.
8. Run CMD as the administrator and execute the following:
tomcat9.exe //US//ThingWorx-Foundation
Configure Time Zone Settings on Linux
1. Stop the ThingWorx-Foundation service using systemctl stop ThingWorx-Foundation.service.
2. Back up ThingWorx-Foundation.service in /etc/systemd/system/ThingWorx-Foundation.service.backup.
3. Edit the service configuration by changing the ThingWorx-Foundation.service for JVM options:
a. To CATALINA_OPTS, append the following: -Duser.timezone=UTC
4. Execute the following: systemctl daemon-reload.
Run Scripts
• Installer upgrade to 9.3.x and later versions
1. Obtain the list of all database-specific timezone names. To do this, manually connect to the database and run this query to get a list of all timezone names currently supported by the database:
SELECT name, utc_offset, is_dst FROM pg_timezone_names ORDER BY name
| Keep this list for later reference. |
2. Determine the name of the timezone to which all existing ThingWorx data is currently associated (your “From” timezone):
▪ Get the timezone value you noted in the "Set the ThingWorx Server Timezone" section above.
▪ That value is the timezone to which all existing ThingWorx data is currently associated.
▪ That value is specific to either the JVM or the operating system, and may not exactly match any timezone name within the database-specific list (queried in step 1).
▪ Manually examine the list of timezones queried from the database to determine which timezone name most appropriately matches that value from the "Set the ThingWorx Server Timezone" section.
▪ After you find the most appropriate match, that timezone name becomes the “From” timezone (vs. the “To” timezone) that will be needed in later steps.
3. Determine the timezone to which all existing ThingWorx data should be migrated (your “To” timezone):
▪ In the "Set the ThingWorx Server Timezone" section above, you set Tomcat’s -Duser.timezone configuration setting to UTC. This is the timezone that all existing ThingWorx data should be migrated to. However, that value is specific to the JVM, and may not exactly match any timezone name within the queried database list (queried in step 1).
▪ Manually examine the list of timezones queried from the database to determine which timezone name most appropriately matches that UTC value.
▪ After you find the most appropriate match, that timezone name becomes the "To” timezone (vs. the “From” timezone) that will be needed in later steps.
| The “From” and “To” timezone names can be the same. |
4. Run the BigInt/Timezone schema script to prepare for the migration of all data table, stream, and value stream data:
update_bigint_timezone_schema_postgres.ps1
| Running this script without arguments prints its usage statement: Usage: update_bigint_timezone_schema_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] --from_timezone <timezone> --to_timezone <timezone> [-y]
Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). --system_version_override version Forces the upgrade to assume the database schema is currently of this version (i.e. "n.n.n"), rather than of the actual, persisted version. --from_timezone timezone The name of the timezone for all existing data. --to_timezone timezone The name of the timezone to which all existing data will be updated. -y Suppress all non-required prompts, such as "Are you sure?" |
| While this script directly migrates some data, it does not migrate any data table, stream, or value stream data. Instead, this script creates a backup of all data table, stream, and value stream data so it can be migrated later. For performance reasons, this script does not actually create a backup copy of the data within the existing data table, stream, and value stream tables. Instead, this script renames the existing tables from "foo" to "foo_backup". This circumvents the potentially time-consuming process of copying huge amounts data. Once these existing tables are renamed (thus becoming their own backup tables), new tables are created with the original names. These new tables are empty and serve the same purpose as the original tables (because they have the same names as the original tables). |
5. After completing the previous step, the platform may be restarted if necessary. However, note that data table, stream, and value stream data has not yet been migrated. Therefore, until that data migration occurs, queries for that data may receive reduced result sets.
6. Run the BigInt/Timezone data script to migrate any data table, stream, or value stream data:
update_bigint_timezone_data_postgres.ps1
| Running this script without arguments prints its usage statement: Usage: update_bigint_timezone_data_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] --from_timezone <timezone> --to_timezone <timezone> --chunk_size <chunk_size> ( --update_data_table | --update_stream | --update_value_stream ) [-y]
Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). --system_version_override version Forces the upgrade to assume the database schema is currently of this version (i.e. "n.n.n"), rather than of the actual, persisted version. --from_timezone timezone The name of the timezone for all existing data. --to_timezone timezone The name of the timezone to which all existing data will be updated. --chunk_size chunk_size The number of records to update per transaction. Must be greater than 0. --update_data_table Update "data_table" information. Cannot be specified with any other "--update_..." flag. --update_stream Update "stream" information. Cannot be specified with any other "--update_..." flag. --update_value_stream Update "data_table" information. Cannot be specified with any other "--update_..." flag. -y Suppress all non-required prompts, such as "Are you sure?" |
| • Per the usage statement above, only one “--update…” option can be specified at a time. Therefore, to migrate all data table, stream, and value stream data, this script must be run three times (once for each dataset). Because these datasets are independent from each other, the migration of one dataset can be done in parallel with the migration of another dataset. For example, if you open three separate command windows, you can concurrently run the data table migration in the first window, the stream migration in the second window, and the value stream migration in the third window. However, do not attempt to use more than one process to concurrently migrate a given dataset. For example, do not attempt to use two concurrent processes to migrate value stream data. Doing so is undefined and will result in data corruption. • The suggested chunk_size for a typical environment is 10000. • Since the platform can be restarted before all data migration has been completed, the migration of data occurs from the newest data to the oldest data. This is intentional, and allows any queries for that data to start receiving the most pertinent data first. • The size of your data sets can have a dramatic impact on how long it takes to migrate all your data. For example, if you have billions of rows to migrate, the migration of that data may take several days to complete. |
7. After all BigInt/Timezone data migration has been completed, and after all migrated BigInt/Timezone data has been manually verified and validated, run the BigInt/Timezone cleanup script to clean up any temporary database artifacts created by the BigInt/Timezone schema script:
cleanup_bigint_timezone_data_update_postgres.ps1
| Running this script without arguments prints its usage statement: Usage: cleanup_bigint_timezone_data_update_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] [-y]
Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). -y Suppress all non-required prompts, such as "Are you sure?" |
| Although this script performs some cleanup of temporary database objects created during the upgrade process, it does not delete any of the backup tables created in the previous steps, nor does it modify any data within those backup tables. This is intentional, and ensures that data cannot be accidentally deleted. If you want to delete these backup tables, you must delete them manually. |
8. Run the main Cleanup script after all data migration has been completed, verified and validated.
After all BigInt/Timezone data migration has been completed, verified and validated, run this script to clean up any temporary database artifacts created by main ThingWorx update script:
cleanup_update_postgres.ps1
| Running this script without arguments prints its usage statement: Usage: cleanup_update_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] [-y]
Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). -y Suppress all non-required prompts, such as "Are you sure?" |
• Installer upgrade to 9.0.x, 9.1.x, 9.2.x
Once the time zone is set, go to <InstallLocation>/schema/update and run the appropriate scripts for your operating system and database combination (for example, for Windows, .bat files as listed below; for a RHEL installation, .sh files) in the following order:
a. thingworxPostgresDBSetupBigIntTimezoneDataUpdate.bat
b. thingworxPostgresModelTablesDataUpdate.bat
c. thingworxPostgresDataTableSchemaUpdate.bat
d. thingworxPostgresValueStreamSchemaUpdate.bat
e. thingworxPostgresStreamSchemaUpdate.bat
f. thingworxPostgresDataTableDataUpdate.bat
g. thingworxPostgresStreamDataUpdate.bat
h. thingworxPostgresValueStreamDataUpdate.bat
The scripts take parameters, such as the following:
-h <server>
-p <port>
-d <thingworx database name>
-l <thingworx database username> for MSSQL
-u <thingworx database username> for PostgreSQL
-i <SQL server instance name> (optional, for MSSQL installations only)
You will be prompted to enter the password for the database user, which is passed in the -u or -l parameters.
| The StreamDataUpdate and ValueStreamDataUpdate scripts (for example, thingworxPostgresStreamDataUpdate.bat and thingworxPostgresValueStreamDataUpdate.bat) are designed to be run asynchronously. The scripts are designed to pick up where they left off and operate in batches so that you can migrate your data while your ThingWorx instance is running. These scripts may take a long time to run depending on the volume of your data. |
The DataTableDataUpdate script (for example, thingworxPostgresDataTableDataUpdate.bat) will display the following message during execution: Essential System Data Has Been Migrated. It Is Now Safe To Restart Tomcat Server.
Once the DataTableDataUpdate script has posted this message, you can restart your ThingWorx instance and continue with the remaining data migration scripts. The remaining scripts can be run while ThingWorx is running and will finish the migration of your stream and value stream data.
When the migration is complete, you should run the cleanup script (for example, "thingworxPostgresDBCleanupBigIntTimezoneDataUpdate.sh") to clean up the migration_log table and the migration functions.
E.) Run the Cleanup Script for 9.2
If you are upgrading to ThingWorx 9.2, you must run the cleanup script to remove the temporary tables created during the upgrade process.
Run the thingworx<database_name>DBCleanupPermissionTempTableUpdate.bat(Windows) or thingworx<database_name>DBCleanupPermissionTempTableUpdate.sh (Linux) cleanup script located in <installDir>/schema/update.
The scripts take parameters, such as the following:
-h <server>
-p <port>
-d <thingworx database name>
-l <thingworx database username> for MSSQL
-u <thingworx database username> for PostgreSQL
-i <SQL server instance name> (optional, for MSSQL installations only)
You will be prompted to enter the password for the database user, which is passed in the -u or -l parameters.
F.) Configure Content Security Policy
If you are upgrading to a ThingWorx version that supports CSP, perform the following steps.
1. Stop Tomcat.
2. Add "EnableContentSecurityPolicyFilter": false, to platform.settings.json under BasicSettings as follows:
{
"PlatformSettingsConfig": {
"BasicSettings": {
"BackupStorage": "/ThingworxBackupStorage",
"DatabaseLogRetentionPolicy": 7,
"DatabaseWriteRetryAttempts": 10,
"EnableBackup": true,
"EnableClusteredMode": false,
"EnableContentSecurityPolicyFilter": false,
"EnableSystemLogging": false,
"EnableSSO": false,
"FileRepositoryRoot": "/ThingworxStorage",
"FileTransferLockType" : "LOCAL"
"HTTPRequestHeaderMaxLength": 2000,
"HTTPRequestParameterMaxLength": 2000,
"InternalAesCryptographicKeyLength": 128,
"MetricsLoggingFrequency": 30,
"MetricsLoggingLevel": "WARN",
"MetricsReportingEnabled": true,
"NonceKeyTimeout": 15,
"SessionUpdateDelay": 60,
"Storage": "/ThingworxStorage",
"ScriptTimeout": 30,
"MaxSearchItems": 100000
},
| CSP will be disabled in the new installation if the above flag is not added or if the flag is specifically set to false. Setting the flag to true will enable CSP. For more information about CSP, see the other CSP Help Center topics. |
3. Follow the steps below to restore the Clickjack Filter configurations.
a. Copy the Clickjack Filter configurations from the backup web.xml file.
b. Paste the Clickjack Filter configurations into the newly created web.xml file under <tomcat_install_dir>/webapps/Thingworx/WEB-INF.
| Note the following: • Do not replace the web.xml with the older version. Copy the configurations manually from the backup file to the new web.xml file. • ThingWorx will be upgraded with the CSP filter disabled if the EnableContentSecurityPolicyFilter flag is not specified or set to false explicitly. |
4. Start Tomcat.
G.) Additional Optional Cleanup for 9.3+
If you are upgrading from ThingWorx 9.2.x or earlier, and you have enabled single sign-on with access token encryption, there is an optional cleanup step you might want to perform. In releases earlier than 9.3, the KeyCzar tool is used to encrypt access tokens before they are persisted to the database. KeyCzar requires the creation of a symmetric folder in the ThingworxPlatform\ssoSecurityConfig folder of your ThingWorx installation directory.
The KeyCzar tool is now deprecated. In ThingWorx 9.3 and later, it has been replaced by the use of Tink for the encryption of access tokens. Tink does not require the symmetric folder or the keyczarKeyFolderPath parameter in the ThingWorx sso-settings.json file. You can leave these files and settings as they are and ThingWorx 9.3 and later will simply ignore them. But if you decide to remove them, you must wait until the upgrade procedure is complete.
H.) (Optional) Upgrade to PostgreSQL 13
Upgrading from an older PostgreSQL version to PostgreSQL 13 is optional for ThingWorx 9.2.0 and later.
1. Back up the database. This is the second back up you perform, as this will back up your database after the ThingWorx upgrade.
I.) Troubleshooting
• If the upgrade fails with the following error, follow the steps below. This error will occur if any custom index value is greater than or equal to 64 characters.
Unable to Invoke Service Reindex on Data Table : com.microsoft.sqlserver.jdbc.SQLServerException: String or binary data would be truncated in table 'thingworx.thingworx.data_table_indexes', column 'mskey'. Truncated value: '<with_actual_field_Value_from_mskey_field>'.
a. Execute thingworxMssqlSchemaUpdate<priorVersion>-to-<currentVersion>.bat/.sh or SQL script:
sqlcmd -S server\\serverinstance,port -U db_user -P password -d databaseName -i <schemaUpdateFile.sql>
Running this script will increase the mskey column length and will update indexes.
b. Start Tomcat.
• If the installer cannot complete the upgrade, do the following:
1. Check the log files in your installation directory under /installer/logs.
2. Revert to your pre-upgrade installation:
a. Restore your database to its backup.
b. Start the ThingWorx-Foundation service.
• If the installer ran successfully, ThingWorx Foundation was upgraded. However, the name of the ThingWorx Foundation installation location may not be current. You can verify your ThingWorx version in the Composer under > .
• If your operating system is RHEL 8.2 and you are upgrading from ThingWorx 8.5.7, you should first manually uninstall the Chef Infra Client to ensure that the installer is able to provision and use a supported version of Chef. To uninstall Chef, do the following:
a. To find the package name of the Chef Infra Client installer, execute the following command: $ rpm -qa chef.
The output should look like the following: chef-14.10.9-1.el7.x86_64.rpm.
b. Copy the package name from the output found above.
c. Execute the following command with the copied package name: $ sudo yum remove <copied_package_name>.
For example: $ sudo yum remove chef-14.10.9-1.el7.x86_64.rpm.
d. Go to the /opt directory and remove all Chef Infra Client files by deleting the installation directory $ sudo rm -rf /opt/chef.