Getting Started with Building Blocks > Upgrading the Building Blocks > Upgrading Customer Deployments of the Building Blocks
Upgrading Customer Deployments of the Building Blocks
To upgrade the building blocks from 1.2.1 to 9.5.0, complete the steps in the following sections:
* 
PTC recommends that you upgrade on a test system first, before moving to production.
Before Beginning the Upgrade Process
Before you begin the upgrade process, review the following information:
• ThingWorx System Requirements in the ThingWorx Platform Help Center.
• Upgrading ThingWorx in the ThingWorx Platform Help Center.
• Customizations to the building blocks are impacted by the upgrade process. For more information, see Customization and Upgrade.
Before Upgrading ThingWorx
Before upgrading ThingWorx, complete the following steps:
• If you have customized any of the building blocks, back up your customizations.
• Localization tables are overwritten during an upgrade. If you have customized tokens in any localization tables, export the customized localization tables before performing the upgrade. The exported localization tables can be imported after the upgrade is complete to retain your modifications.
Upgrading ThingWorx
Complete the following steps:
1. Upgrade your ThingWorx installation. For more information, see Upgrading ThingWorx in the ThingWorx Platform Help Center.
For ThingWorx releases that are compatible with the 9.5.0 building blocks release, see System Requirements.
2. Restart the ThingWorx server.
Before Upgrading the Building Blocks
Before upgrading building blocks, review the following information and perform any necessary actions:
• Any application built using the building blocks will be unavailable during the upgrade process, meaning that production data cannot be entered during that time. PTC recommends upgrading a test system first before upgrading your production system. This will help you determine how long your production system will be unavailable.
• Increase the duration of the script timeout setting before performing the upgrade. This setting can be returned to its previous value after the upgrade is complete. To update the script timeout setting, a ThingWorx administrator must complete the following steps:
1. On the ThingWorx server, navigate to the ThingWorxPlatform folder.
2. Open the platform-settings.json file in a text editor.
3. Find and update the ScriptTimeout setting to 12000.
4. Save and close the platform-settings.json file.
5. Restart the ThingWorx server.
* 
If a message similar to the following appears in your script log, repeat the steps above to further increase the ScriptTimeout setting:
[message: Execution of Script terminated after : 12000 seconds. Timeout configured for 12000 seconds.]
For more information, see platform-settings.json Configuration Details in the ThingWorx Platform Help Center.
Upgrading the Building Blocks
To upgrade the building blocks, complete the following steps:
1. Download the new version of the building blocks from the PTC Software Downloads page. Complete the following steps:
a. Navigate to the PTC Software Download page at the following URL: https://support.ptc.com/appserver/auth/it/esd/index.jsp.
b. Select ThingWorx Foundation.
c. Expand the following folders: ThingWorx Foundation > Release 9.5 > ThingWorx Manufacturing Common.
d. Download the extension package ZIP file for the release you are deploying.
2. Import the building blocks. To import the building blocks, a ThingWorx administrator must complete the following steps:
a. Ensure that your license is installed in ThingWorx Composer. For more information, see this Technical Support Article in the PTC Knowledge Base.
b. In ThingWorx Composer, navigate to Import/Export > Import.
c. On the Import window, select Extension from the Import Option list.
d. Under File Name, click Browse. Navigate to and select the extension package ZIP file that you downloaded in the previous section.
e. Click Import. When the import finishes, click Close.
f. View the building block extensions after import by navigating to Manage > Installed Extensions.
3. Restart the ThingWorx server.
4. Get the configuration parameters for the UpgradeSolution service.
a. In ThingWorx Composer, navigate to the PTC.Base.Manager Thing.
b. Under Services, find and execute the GetSolutionUpgradeConfigurationParameters service. The service output is a JSON containing the configuration parameters needed for the UpgradeSolution service, dynamically based on the set of building blocks that are present. The service output JSON is similar to the following:
{
"databaseUser": {
"types": [
"STRING"
],
"description": "Name of the database user used for DPM database Thing",
"optional": false
},
"automatedMigration": {
"types": [
"Boolean"
],
"description": "When TRUE, the MigrateSolution service is automatically called by the UpgradeSolution service after the upgrade action completes. When FALSE, the MigrateSolution service must be manually executed.",
"optional": false
},
"databasePassword": {
"types": [
"STRING"
],
"description": "Password of the database user used for DPM database Thing",
"optional": false
},
"databaseJDBCString": {
"types": [
"STRING"
],
"description": "JDBC Connection String for the DPM database Thing",
"optional": false
},
"databaseThing": {
"types": [
"STRING"
],
"description": "The default database thing (PTC.DBConnection.SQLThingDatabase)",
"optional": true
}
}
c. Copy the JSON returned in the service output and paste it into a text editor.
d. Edit the JSON, replacing the content between the braces for each configuration parameter with the value specific to your site.
▪ databaseUser—The login name of the database user with system administration rights.
▪ databasePassword—The login password for the database user with system administration rights.
▪ databaseJDBCString—The JDBC connection string for the building blocks database.
▪ databaseThing—The default database Thing (PTC.DBConnection.SQLThingDatabase).
▪ automatedMigration—When this value is true, the MigrateSolution service is automatically executed, migrating all solution data to the updated database schema. This migration can take a long time, depending on the amount of data to be migrated. When this value is false, the MigrateSolution service is not automatically executed and must be manually executed at a later time.
The following is an example of the input JSON:
{
"databaseUser": "DPMadmin",
"databasePassword": "945DaTaBase!39525",
"databaseJDBCString": "jdbc:sqlserver://localhost:1433;databaseName=dpmdb",
"databaseThing": "PTC.DBConnection.SQLThingDatabase",
“automatedMigration”: true
}
5. Run the UpgradeSolution service, using the edited JSON from step 4.d as the config input parameter for the service.
When the service completes, the output displays an infotable listing the building blocks that were upgraded, deployed, and migrated (if the MigrateSolution service was automatically run), and their configuration status: Successful, Not Processed, or Error. The service stops if an error is encountered while the service processes a building block. That building block’s status is shown as Error, and the remaining building blocks have a Not Processed status.
If any building blocks have an Error or Not Processed status, complete the following troubleshooting steps:
a. Ensure the database credentials specified in the JSON are valid, then execute the UpgradeSolution service.
b. If any building blocks still have an Error or Not Processed status in the service output, review the ThingWorx Application and Script error logs and address any errors found there. Then execute the UpgradeSolution service.
6. If the MigrateSolution service was not automatically executed by the UpgradeSolution service, execute the MigrateSolution service. This service does not have any required input parameters.
The service output, statuses, and troubleshooting steps for the MigrateSolution service are the same as those for the UpgradeSolution service, shown in step 4. Repeat the troubleshooting steps until all building blocks have a Successful status.
* 
The upgrade is not complete until the MigrateSolution service has been successfully executed. The upgraded system cannot be used until the data has been migrated.
Post-Upgrade Activities
After the building blocks have been successfully upgrade, including migrating your solution data, and before making the updated system available to users, complete the following steps.
1. If you have customized the building blocks, refer to Customization and Upgrade to address any impact to your customizations resulting from the upgrade.
2. Import any customized localization tables that you exported from ThingWorx Composer before the upgrade.
3. If you increased the script timeout setting before upgrading the building blocks, return it to its previous setting.
4. Recommend that users clear the browser cache on any client machines.
Upgrading Custom Building Blocks
You can upgrade your custom building blocks after the PTC-provided building blocks have been upgraded.
* 
When code changes are made to custom building blocks, be sure to update the componentVersion property of the building block extension before creating the extension package. This property is found under Properties and Alerts on the entry point Thing for the building block in ThingWorx Composer.
This updated componentVersion property is required to successfully upgrade the custom building blocks.
To upgrade your custom building blocks, complete the following steps:
1. In ThingWorx Composer, import the new versions of your custom building block extensions.
2. Run the UpgradeSolution service. See steps 4 and 5 in the Upgrading the Building Blocks section for details.
Was this helpful?