Manual Migration to ThingWorx 9.x: Windows with InfluxDB
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: Windows.
A.) Before You Upgrade
1. 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.
2. If you are using ThingWorx Apps in addition to ThingWorx platform:
b. There are steps that you must take before upgrading the platform. See
Upgrading ThingWorx Apps before proceeding to the next step.
5. Verify that you are running the required versions of Tomcat and Java. Refer to the
System Requirements for version requirements.
| If you must upgrade your Java version, perform the ThingWorx upgrade before upgrading Java. |
7. If you are upgrading MSSQL, or Azure SQL, 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. |
8. Add the following to the Apache Tomcat Java Options:
-Dlog4j2.formatMsgNoLookups=true
B.) Export 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 > .
b. Use the following options:
▪ For Export Option, select To File.
▪ For Export Type, select Collection of Entities.
▪ For Collection, select All.
▪ Click Export.
5. Copy the entity export files and move to a safe location. You will import these files in a later step.
C.) Export Data
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 > .
b. Use the following options:
▪ For Export Option, select To File.
▪ For Export Type, select Collection of Data.
▪ For Collection, select All.
▪ Click Export.
5. Copy the data export files and move to a safe location. You will import these files in a later step.
D.) 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>
},
12. Start Tomcat.
13. 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.
14. To launch ThingWorx, go to <servername>\Thingworx in a web browser. Use the following login information:
◦ Login Name: Administrator
◦ Password: <Source server admin password>
E.) Upgrade to Java 11
1. If you are upgrading to Java 11, the following steps are required. Skip this section if Java 11 is already installed.
b. Unzip the downloaded openjdk-11 zip and copy the jdk-xxxx folder in the un-zipped folder.
c. Paste the jdk-xxxx folder in the following location: C:\Program Files\Java.
d. Verify that the JAVA_HOME system variable is configured to use the Java 11 directory location. For example, C:\Program Files\Java\jdk-11.0.7.
e. Edit the Path variable and add a new value: %JAVA_HOME%\bin.
f. To verify the Java version, open a command prompt and run the following command: java -version.
g. Update the path in the Tomcat Java settings.
h. Restart Tomcat.
F.) Import 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.
4. Import entities.
| 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 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). |
G.) Update the Influx DB persistence provider details
1. In the Composer, go to Persistence Providers, and open the existing Influx Persistence Provider.
2. On the Configuration page, update the information with the new InfluxDB persistence provider details.
H.) Import Data
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.
4. Import entities.
| 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 to import.
I.) 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.
J.) Upgrade Additional Components
• 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