Installer Upgrade
If you used 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 example, 9.1.0 to 9.1.1).
If you are upgrading to ThingWorx 9.2 and are also upgrading to PostgreSQL 13, upgrading PostgreSQL will be the last step in the upgrade process.
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
For version information, see System Requirements.
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.
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 > Download Software > Order or Download Software Updates > ThingWorx Foundation > Release 9.0 > ThingWorx Upgrade Ready Utility from 8.5.0–8.5.3 to 9.0.0.
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.
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'?>

<applicationInstallDir>C:\Program Files
C.) Upgrade 
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 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
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 
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
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:
1. thingworxPostgresDBSetupBigIntTimezoneDataUpdate.bat
2. thingworxPostgresModelTablesDataUpdate.bat
3. thingworxPostgresDataTableSchemaUpdate.bat
4. thingworxPostgresValueStreamSchemaUpdate.bat
5. thingworxPostgresStreamSchemaUpdate.bat
6. thingworxPostgresDataTableDataUpdate.bat
7. thingworxPostgresStreamDataUpdate.bat
8. 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)
For more information about these parameters and their expected input, see Manual In Place Upgrade: Windows or Manual In Place Upgrade: Linux.
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, "") 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.x or later, 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> (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.) 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.
G.) (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.
2. Download PostgreSQL 13.
3. Upgrade to PostgreSQL 13 using PostgreSQL documentation as a reference.
H.) 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 : 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>'.
1. 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.
2. Start Tomcat.
If you have an existing installation of ThingWorx 8.5.3 or earlier but the installer did not find it, run the ThingWorx Upgrade-Ready Utility.
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 Help > About.
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:
1. 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.
2. Copy the package name from the output found above.
3. 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.
4. Go to the /opt directory and remove all Chef Infra Client files by deleting the installation directory $ sudo rm -rf /opt/chef.
Was this helpful?