Manual Migration to ThingWorx 9.x: Linux
Refer to the upgrade table to determine your upgrade path. The steps below are for migration only. For an in-place upgrade, refer to Manual In-place Upgrade: Linux.
 |
If you are using InfluxDB as the persistence provider, follow the steps for Manual Migration to ThingWorx 9.x: Linux with InfluxDB.
|
A.) Before You Upgrade
1. If your OS is RHEL, verify that you have upgraded to the supported version before performing an upgrade of ThingWorx. Refer to System Requirements for more information.
| | ThingWorx 9.1 is only supported on RHEL 8.2. |
2. Before beginning the upgrade, it is recommended to perform the following:
◦ Database dump
◦ Back up all data in the ThingworxStorage and ThingworxPlatform folders.
◦ Back up the Tomcat_home folder. This includes the bin, conf, lib, temp, webapps, and work folders.
◦ If you are upgrading to a ThingWorx version that supports Content Security Policy (9.5.1 and later), copy web.xml from “<tomcat_install_dir>/webapps/Thingworx/WEB-INF” to another folder for use later.
3. If you are using ThingWorx Apps in addition to ThingWorx platform:
a. Verify that the version of ThingWorx you are upgrading to is supported with the version of ThingWorx Apps. See ThingWorx Apps Upgrade Support Matrix.
b. There are steps that you must take before upgrading the platform. See Upgrading ThingWorx Apps before proceeding to the next step.
4. If you also have Navigate installed, verify compatibility at ThingWorx Navigate Compatibility Matrix.
5. Obtain the latest version of ThingWorx at PTC Software Downloads.
| | Download and extract the ThingWorx content in a folder where the current user has write permissions. Write permissions are required as the update scripts create some files in the process. |
6. Verify that you are running the required versions of Tomcat and Java. Refer to the System Requirements document for version requirements.
| | If you must upgrade your Java version, perform the ThingWorx upgrade before upgrading Java. |
7. Tomcat Java option setting requirements may have changed between versions. Refer to the Apache Tomcat Java Option Settings to verify that your settings are correct.
8. If you are upgrading MSSQL, Azure SQL, or H2, 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 fail to do so, the upgrade will fail and you will have to deploy the older version again (if schema updates were made, you must roll back/restore database) and add missing index values or remove the custom indexes from the data table and then perform upgrade. |
9. Add the following to the Apache Tomcat Java Options:
-Dlog4j2.formatMsgNoLookups=true
B.) Export Data and Entities
1. Stop Tomcat: In the Tomcat Properties, click Stop. Wait for Tomcat to stop.
2. It is highly recommended to back up the following folders before continuing:
◦ Apache Software Foundation/Tomcat x.x/webapps/Thingworx
◦ <Tomcat install location>://ThingworxStorage
3. Start Tomcat: In the Tomcat Properties, click Start. Restarting Tomcat assures that the database is clear before exporting.
4. Export entities and data:
a. In Composer, click Import/Export > Export > <export option>.
| | For more information on export options, refer to Importing and Exporting Data, Entities, and Extensions. |
b. If necessary, click Include data.
Data and entities are exported to ThingworxStorage\exports.
| | Data export progress can be monitored in the Application Log. |
5. Copy the data and entity export files and move to a safe location. You will import these files in a later step.
C.) Backup and Configure
1. Backup and delete the validation.properties file from the /ThingworxStorage/esapi directory.
| | The validation.properties file is created upon startup of ThingWorx. If you want to retain any changes you have made, save the file outside of the ThingworxStorage directory and then proceed with removing the esapi directory. Upon startup, ThingWorx will recreate the file and you can add your custom regexes back into the validation.properties file that was automatically generated. Reference this topic for additional information. |
2. Locate the keystore.jks file in the ThingworxStorage folder and move it to a safe place. You will add this file back to the ThingworxStorage folder post migration.
3. Locate the keystore-password file in the ThingworxPlatform folder and move it to a safe place. You will add this file back to the ThingworxPlatform folder post migration.
4. Note any extensions that are in use (located in ThingworxStorage/extensions). They will be reimported in a later step.
5. Stop Tomcat.
6. Delete the contents of the ThingworxStorage and ThingworxBackupStorage folders.
7. Delete the keystore-password file from the ThingworxPlatform folder.
8. Go to the Tomcat installation at /Apache Software Foundation/Tomcat x.x/webapps and delete the Thingworx.war file.
9. Delete the Thingworx folder located at Apache Software Foundation/Tomcat x.x/webapps.
10. Copy the Thingworx.war file for this version and place it in the following location of your Tomcat installation: /Apache Software Foundation/Tomcat x.x/webapps .
11. Enable extension import. By default, extension import is disabled for all users. Add the following to the platform-settings.json file. Add or update the following ExtensionPackageImportPolicy parameters to true to allow extensions to be imported.
"ExtensionPackageImportPolicy": {
"importEnabled": <true or false>,
"allowJarResources": <true or false>,
"allowJavascriptResources": <true or false>,
"allowCSSResources": <true or false>,
"allowJSONResources": <true or false>,
"allowWebAppResources": <true or false>,
"allowEntities": <true or false>,
"allowExtensibleEntities": <true or false>
},
"importEnabled": <true or false>,
"allowJarResources": <true or false>,
"allowJavascriptResources": <true or false>,
"allowCSSResources": <true or false>,
"allowJSONResources": <true or false>,
"allowWebAppResources": <true or false>,
"allowEntities": <true or false>,
"allowExtensibleEntities": <true or false>
},
12. If you are using H2 as a database with ThingWorx, a username and password must be added to the platform-settings.json file.
},
"PersistenceProviderPackageConfigs":{
"H2PersistenceProviderPackage":{
"ConnectionInformation":
{
"password": "<changeme>",
"username": "twadmin"
}
},
"PersistenceProviderPackageConfigs":{
"H2PersistenceProviderPackage":{
"ConnectionInformation":
{
"password": "<changeme>",
"username": "twadmin"
}
},
13. Start Tomcat.
14. If you are reusing the old keystore.jks file, locate the keystore.jks and keystore-password files that you previously moved from the ThingworxStorage and ThingworxPlatform folders and paste in the respective folders.
15. To launch ThingWorx, go to <servername>/Thingworx in a web browser. Use the following login information:
◦ Login Name: Administrator
◦ Password: <Source server admin password>
D.) Upgrade to Java 11
| | Java 11 is required for ThingWorx 9.2.0 and later. Refer to system requirements for details. |
1. If you are upgrading to Java 11, the following steps are required. Skip this section if Java 11 is already installed.
b. Install jEnv on Linux:
i. Git clone the jEnv repository:
git clone https://github.com/jenv/jenv.git ~/.jenv
ii. Add jEnv to your $PATH:
echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.bash_profile
iii. Initialize jEnv:
echo 'eval "$(jenv init -)"' >> ~/.bash_profile
iv. Update the changes made in ~/.bash_profile:
source ~/.bash_profile
v. Set the JAVA_HOME environment variable:
jenv enable-plugin export
vi. Restart your current shell session:
exec $SHELL -l
vii. Run the following command and the JAVA_HOME variable will be automatically set by jEnv, depending upon the currently active Java environment:
jenv doctor
c. Add Java environments:
i. Add any environments. All Java installs are located in /usr/lib/jvm/. Use the jenv add command. Examples below:
jenv add /usr/lib/jvm/java-11-amazon-corretto
jenv add /usr/lib/jvm/jdk-11.0.7
ii. Check all available Java versions to jenv:
jenv versions
iii. Set global Java environment:
jenv global <version>
iv. Set shell-specific Java environment:
jenv shell <version>
v. Verify current version set by jenv:
jenv versions
vi. Update the path in the Tomcat Java settings.
vii. Restart Tomcat.
E.) Import Data and Entities
1. Move the export files back to ThingworxStorage\exports.
2. If necessary, obtain and import the latest versions of the extensions. You must import the 9.x versions of the extensions. PTC supported extensions are available on the ThingWorx Foundation downloads page.
3. If you upgraded from 8.x to 9.x and have Java extensions, see Migrating Java Extensions from 8.x to 9.x.
4. Import entities and data.
| | If you are upgrading to ThingWorx 9.2 or later, you must import the principals.xml before importing the entities.xml. Failure to do so will cause all permissions to be lost. For more information, see Importing Entities in 9.2 and Later. |
a. In Composer, click Import/Export > From File.
b. Select the data and/or entities to import.
| | Select the Include Subsystems checkbox if you want to include the Subsystem settings of the imported entities (for example, if you are going from a test environment to production). |
| | The following error is seen in the Application log for MSSQL upgrades and displays if there are any migrated service, property, or event names that have run time permissions configured and their name contains more than 256 characters. To fix this error, limit all service, property, and event names to less than 256 characters. Error occurred while accessing the data provider |
c. Review the Application logs to verify that there are no “missing principal” warning messages in the logs. If there are, refer to Importing Entities in 9.2 and Later for troubleshooting.
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
},
"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. • To enable or disable CSP at a later time, see Content Security Policy. |
4. Start Tomcat.
G.) Upgrade Additional Components
• If you are using Integration Connectors, you must obtain and install the latest version of the integration runtime. For more information, refer to Initial Setup of Integration Runtime Service for Integration Connectors.
• If you are using ThingWorx Analytics as part of your solution, two installers are available to handle component upgrades:
◦ Analytics Server – installs or upgrades Analytics Server and Analytics Extension
◦ Platform Analytics – installs or upgrades Descriptive Analytics and Property Transforms
For more information about the upgrade procedures, see ThingWorx Analytics Upgrade, Modify, Repair