Installation and Upgrade > Upgrading ThingWorx Apps > Upgrading from ThingWorx Apps 8.5.2 to 9.1.0
Upgrading from ThingWorx Apps 8.5.2 to 9.1.0
To upgrade from ThingWorx Apps 8.5.2 to ThingWorx Apps 9.1.0, complete the steps in the following sections:
Before Beginning the Upgrade Process
Before you begin upgrading, review the following information:
ThingWorx 9.1 system requirements. For more information, see the 9.1 System Requirements in the ThingWorx Help Center.
Upgrading ThingWorx in the ThingWorx Help Center.
Customizations to ThingWorx Apps are impacted by the upgrade process. For more information, see Upgrade and Customizations.
Before Upgrading ThingWorx
Complete the following steps before upgrading ThingWorx to 9.1:
1. If you have customized any localization tables, export the customized localization tables before performing the upgrade. Localization tables are overwritten during an upgrade. The exported localization tables can be imported after the upgrade is complete to retain your modifications.
2. If you are using Operator Advisor functionality, review the following information. Otherwise, proceed to Upgrading ThingWorx.
Prior to 9.1, a work definition could be linked to a job order using the WorkDefinitionUID field on the job order. There were no constraints against linking an individual work definition to multiple job orders. With 9.1, an individual work definition can be linked to only one job order.
If you have used the WorkDefinitionUID field to link work definitions to job orders, query your database to find all job orders with a WorkDefinitionUID value that is used more than once. While it is not mandatory to address these duplicates before upgrading, addressing them now allows you to determine which job order you want to retain that WorkDefinitionUID value. The migration service will migrate the first job order with the WorkDefinitionUID value that it encounters. Other job orders with that same WorkDefinitionUID value must be addressed before they can be migrated. There is no way to control which job order the migration service will encounter first.
Complete the following steps:
a. Run the following query against your database:
SELECT *
FROM joborder t1
WHERE EXISTS (SELECT workdefinitionuid
FROM joborder t2
WHERE t1.workdefinitionuid = t2.workdefinitionuid
GROUP BY workdefinitionuid
HAVING COUNT(1)>1)
The query results list all job orders with a WorkDefinitionUID value that is used more than once.
b. Address duplicate WorkDefinitionUID values as appropriate. For example, you can:
Update the job orders to each reference a different WorkDefinitionUID value. Use the UpdateJobOrder service available from the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager).
Delete job orders with duplicate WorkDefinitionUID values, so that only one remains. Use the DeleteJobOrder service available from the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager).
* 
After upgrading to 9.1, a service is provided that allows you to set WorkDefinitionUID values on the non-migrated job orders to null.
If any duplicate WorkDefinitionUID values remain, the migration services will migrate the first job order they encounter with that WorkDefinitionUID value, and report any duplicates as invalid. These invalid job orders must be cleaned up at that time.
Upgrading ThingWorx
Complete the following steps:
1. Upgrade your ThingWorx installation. For more information, see Upgrading ThingWorx in the ThingWorx Help Center.
2. Restart the ThingWorx server.
Upgrading ThingWorx Apps
Complete the following steps to upgrade ThingWorx Apps to 9.1:
1. Ensure that you are logged in as the Administrator user. Using a different user from the Administrator user group to perform the upgrade results in import failures.
2. Import the ThingWorx Apps extension files. Your data and connections are automatically preserved.
a. Download and unzip the contents of the following file: ThingWorx-Apps-<version>-extension-bundle
To locate the download, go to the PTC Software Download page and expand the following folders: ThingWorx Foundation > Release 9.1 > ThingWorx Manufacturing & Service Apps Extension.
b. Import the ThingWorx Apps extension files. The extension files must be imported in the following order:
a. ThingWorx-Apps-<version>-extension-dependencies
b. ThingWorx-Apps-<version>-extension
To import the extension files:
a. In ThingWorx Composer, navigate to Import/Export > Import.
b. On the Import window, select Extension from the Import Option list.
c. Under File Name, click Browse. Navigate to and select the extension file.
d. Click Import. When the import finishes, click Close.
e. Repeat as needed.
c. View the extensions after the import by navigating to Manage > Extensions.
3. Import any optional extensions. Optional extensions are downloaded from the PTC Software Download page and are imported in the same manner as you imported the ThingWorx Apps extensions.
The following optional extensions are available to import along with ThingWorx Apps:
The ThingWorx-Asset-Remoting-<version>-extension is available for download from ThingWorx Foundation > Release 9.1 > ThingWorx Manufacturing & Service Apps Extension. It enables you to use the Remote Access and Control features in Asset Advisor. For more information, see Remote Access and Control.
The ThingWorx-Rockwell-FT-MES-8-5-0-Extension-Bundle optional extension is available for download from ThingWorx Foundation > Release 8.5 > ThingWorx Rockwell FactoryTalk MES Extension. This 8.5.0 extension is supported with ThingWorx Apps 9.1. If this extension was already present on your 9.0.0 system, it does not need to be imported again after upgrading to 9.1. For more information, see ThingWorx Rockwell FactoryTalk MES Integration.
The following optional extensions are available to import along with ThingWorx Apps, but cannot be imported until after the ThingWorx server has been restarted:
The ThingWorx-Apps-<version>-extension-factory-demo is available for download from ThingWorx Foundation > Release 9.1 > ThingWorx Manufacturing & Service Apps Extension. It provides an example implementation for manufacturing planning activities. This extension is not intended for use in a production environment. For more information, see Manufacturing Planning Example Implementation.
The ThingWorx-Utilities-Software-Content-Management-<version> optional extension is available for download from ThingWorx Foundation > Release 9.1 > ThingWorx Utilities > Most Recent Datecode. For more information, see Software Content Management.
* 
The ThingWorx Utilities Core extension bundle (ThingWorx-Utilities-Core-<version>) is a prerequisite for the ThingWorx Software Content Management extension, and must be imported first. If you have not already imported the ThingWorx Utilities Core extension bundle, do so before importing the ThingWorx Software Content Management extension. For more information, see ThingWorx Utilities Installation in the ThingWorx Utilities Help Center.
4. Restart the ThingWorx server.
5. Update the ThingWorx Remote Access Extension (RAE) present in ThingWorx by importing the supported version for the 9.1.0 release. You can find the compatible version of the ThingWorx Remote Access Extension in the "ThingWorx Extensions" section of the release matrix in Release Advisor for your installed version of ThingWorx.
6. Restart the ThingWorx server.
7. Clear your browser cache.
8. Complete the post import database configurations.
a. Navigate to the database Thing corresponding to your database: PTC.SCA.SCO.PostgresDatabase or PTC.SCA.SCO.MSSQLDatabase.
b. Under Configuration, set the JDBC Settings appropriately for your database, including the JDBC Connection String, Database User Name, and Database Password fields. If you are using the same database that is used for the ThingWorx Platform, use the same values for those three fields as the values that are specified in the platform-settings.json file.
* 
Before configuring your database Thing, ensure that the necessary JDBC drivers are present in ThingWorx. ThingWorx can use JDBC drivers to connect to any JDBC compatible database (such as SQL Server, MySQL, and so on). You can also connect using the ThingWorx Edge MicroServer and the ThingWorx Host/Resource using OLEDB and ODBC if the database is behind a firewall. If a JDBC extension for your database is not in ThingWorx, you can manually add the JDBC driver by downloading the driver and adding the files to the following location: /<Tomcat folder>/webapps/Thingworx/WEB-INF/lib. After copying the driver, you must restart your ThingWorx server.
c. Click Save to save the database Thing.
d. Navigate to the PTC.Factory.C_LaunchPointConfigurationThing_[ReleaseVersion] Thing.
e. Under Configuration, in the DatabaseConfigurationSettings section, edit the DBConnection field to point to the database Thing you configured in step 2.
f. Click Save to save the launch point configuration Thing.
9. Migrate your data.
a. In ThingWorx Composer, open the PTC.SCA.SCO.OAMigrator Thing.
b. Under Services, execute the MigrateFrom_8_5_2_To_9_1_0 service.
The service output is an infotable displaying any job orders with linked work definitions that could not be migrated. Prior to 9.1, a work definition could be linked to more than one job order using the WorkDefinitionUID field on the job order. With 9.1, an individual work definition can be linked to only one job order through a job-order-to-work-definition link (PTC.SCA.SCO.JobOrderWorkDefinitionLink). The migration service creates a job-order-to-work-definition link for the first instance of a WorkDefintionUID that it encounters on a job order. If the service encounters that same WorkDefinitionUID value again, that relationship is reported in the MigrateFrom_8_5_2_To_9_1_0 service output as an invalid relationship that could not be migrated.
If the infotable in the MigrateFrom_8_5_2_To_9_1_0 service output is empty, showing No data, proceed to step 10.
c. Clean up the non-migrated job-order-to-work-definition relationships using one of the following methods:
Delete a non-migrated job order using the DeleteJobOrder service on the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager).
Update the WorkDefinitionUID field using the UpdateJobOrderWorkDefinitionRelationships service on the PTC.SCA.SCO.OAMigrator Thing.
To use the UpdateJobOrderWorkDefinitionRelationships service, add a row to the JobOrders input parameter infotable for each job order which needs to be updated. Specify the following fields:
UID—Enter the UID of the job order to be updated.
WorkDefinitionUID—Enter the UID for a work definition that is not already linked to a job order, or leave this field blank to change the WorkDefinitionUID value to null.
All other fields can be left blank.
Execute the UpdateJobOrderWorkDefinitionRelationships service. The service output shows the updated job orders.
* 
Open a second ThingWorx Composer session in another browser tab or window, so that you can execute and view the UpdateJobOrderWorkDefinitionRelationships service and MigrateFrom_8_5_2_To_9_1_0 service at the same time. This allows you to more easily reference the MigrateFrom_8_5_2_To_9_1_0 service output for the job order UIDs to use in the UpdateJobOrderWorkDefinitionRelationships service input. You can execute both services multiple times, as needed.
d. Repeat executing the MigrateFrom_8_5_2_To_9_1_0 service, and using the UpdateJobOrderWorkDefinitionRelationships service to clean up non-migrated job orders, until the output from the MigrateFrom_8_5_2_To_9_1_0 service is an infotable showing No data. This indicates that all job orders have been successfully migrated and no further cleanup is necessary. If you run the service again after this point, you will see errors as there is no more data to be migrated.
10. If you have equipment with properties that are bound to KEPServerEX tags using the previous local-to-local binding implementation, and you want to take advantage of the new remote binding implementation, complete the following steps. This updates the property bindings to use the new remote binding implementation on all equipment for which these steps are performed.
For more information about the implementation change for binding properties to KEPServerEX tags, see theThingWorx Apps 9.0.0 Release Notes.
a. Ensure that any equipment which has properties bound to KEPServerEX tags implements the IndustrialThingShape, either directly on the equipment Thing itself, in the Thing Template for the equipment type, or in a Thing Template inherited by the equipment type. Once the IndustrialThingShape is added to a Thing or Thing Template, it cannot be removed. Equipment implementing the IndustrialThingShape can remotely bind properties only to KEPServerEX tags.
Before adding IndustrialThingShape to the Thing Template for an equipment type, consider whether all equipment of that type binds properties to KEPServerEX tags. If this is the case, then IndustrialThingShape can be added to the Thing Template. If some equipment must remotely bind properties to a non-KEPServerEX data source, such as to Edge MicroServer (EMS) devices, consider creating a separate equipment type to use for that equipment, or add IndustrialThingShape only to the individual equipment Things which bind properties to KEPServerEX tags.
Update the appropriate equipment Things or Thing Templates to implement the Thing Shape.
* 
Equipment using the PTC-provided Asset equipment type should only have the IndustrialThingShape added if that equipment does not need to bind properties to Edge MicroServer (EMS) devices. For more information, see Connecting Assets to Edge MicroServer (EMS).
b. Ensure that the Thing Templates for any custom equipment types which have properties bound to KEPServerEX tags inherit one of the following Thing Templates: RemoteThing, RemoteThingWithFileTransfer, RemoteThingWithTunnels, or RemoteThingWithTunnelsAndFileTransfer. For more information, see Creating Custom Thing Templates for Equipment Types.
c. In ThingWorx Composer, open the PTC.SCA.SCO.MigrationUtility Thing.
d. Under Services, execute the MigrateLocalKepServerBindingsToRemoteBindings service. This service migrates the local-to-local property bindings on equipment Things to remote property bindings for all equipment of the specified equipment types which implement the IndustrialThingShape. Properties inherited by the equipment Things from Thing Templates or Thing Shapes, which are locally bound to KEPServerEX tags on the Thing Templates or Thing Shapes, continue to be locally bound, and are not impacted by the migration service. Status expressions, trends, and alerts which use KEPServerEX tags continue to be locally bound, and are not impacted by the migration service.
In the equipmentType input table for the service, add each equipment type for which you want to migrate the property bindings. The value entered must match EquipmentType value for the equipment type as it appears in the EquipmentTypeSettings configuration table on the PTC.Factory.C_LaunchPointConfigurationThing_[ReleaseVersion] Thing. The optional overrideKepServerThingName field for each equipment type replaces the KEPServerEX connection that is used for the bound properties.
Consider the following guidelines for when to set the overrideKepServerThingName field for an equipment type:
If you use a single KEPServerEX connection for all equipment of an equipment type, leave the overrideKepServerThingName field blank.
If you have multiple KEPServerEX connections, but each piece of equipment has properties bound only to a single KEPServerEX connection, leave the overrideKepServerThingName field blank.
If you have multiple KEPServerEX connections, and any equipment has properties bound to more than one KEPServerEX connection, determine the KEPServerEX connection to which you want to bind the equipment of each such equipment type. Select the name of that KEPServerEX connection from the overrideKepServerThingName field. A piece of equipment can have properties bound to tags on only one KEPServerEX connection. Ensure that the tags from the other KEPServerEX connections are present on the chosen KEPServerEX connection.
The service has completed successfully when "No results" displays in the service output pane.
11. Prepare to add foreign keys to the database by finding and cleaning up any bad data. Bad data is existing data that would violate referential integrity once foreign keys are added to the database.
a. In ThingWorx Composer, open the PTC.SCA.SCO.DatabaseManager Thing.
b. Under Services, execute the ForeignKeyDataIntegrityReport service. The output of this service is an infotable listing each Data Shape name and referencing field that need to be addressed.
If there is no bad data found, the service output is empty. Proceed to step 12.
c. Execute the GetFailedDataForForeignKey service, providing as input a Data Shape and referencing field returned by the ForeignKeyDataIntegrityReport service. The output of this service is an infotable listing up to 500 database records with bad data.
d. Address each bad data instance as appropriate for your system: delete the record, set the referencing field value to null (if allowed), or update the record so that the referencing field has a valid value for the foreign key.
* 
For advanced database administrators, the GetDataShapeSqlQuery service on the PTC.SCA.SCO.DatabaseManager Thing returns an SQL query that can be used in direct database queries.
e. Repeat steps c and d until no further bad data is found.
12. Add foreign keys to the database.
a. In ThingWorx Composer, open the PTC.SCA.SCO.OAMigrator Thing.
b. Under Services, execute the following services, in the order listed:
MigrateDropIndexes
MigrateAddForeignKeys
MigrateAddIndexs
Each service has completed successfully when "No results" displays in the service output pane.
13. The process for mapping Windchill attributes to Operator Advisor properties for process plan conversion has changed. If you had overridden the TranslateODataBOPToWDJson service to specify mapping of custom Windchill attributes in ThingWorx Apps 8.5.2, those mappings must be re-done after upgrading to ThingWorx Apps 9.1, following the new mapping process. For more information, see Supporting Windchill Custom Attributes.
14. The MPMLink OData connector Thing (PTC.SCA.SCO.MPMLink_ODataConnector) has been updated. It is no longer necessary to make a duplicate Thing on which to perform your configurations unless you customize the connector.
If you use Operator Advisor to convert process plans from Windchill MPMLink and are not customizing the connector, configure and use the MPMLink OData connector Thing that is provided with ThingWorx Apps 9.1, rather than retaining a configured duplicate from a past release.
If you use Operator Advisor to convert process plans from Windchill MPMLink and are using a duplicate of the MPMLink OData connector Thing to customize the connector, you must create a new duplicate of the Thing for your configurations after upgrading to 9.1.
For more information, see Configuring the MPMLink OData Connector.
15. If you have added custom equipment types that you want to appear in Asset Advisor, add the PTC.SCA.SCO.AssetIdentifierNumberThingShape Thing Shape as an implemented shape on the Thing Template for the equipment type. For more information, see Creating Custom Thing Templates for Equipment Types.
16. If you have large numbers of assets and do not use KPIs, you can consider using the subscription-based status calculation for improved performance. For more information, see Enabling Subscription-Based Status Calculation for Systems with Large Numbers of Assets.
17. Starting in 9.1, all new or duplicated entities must have a project assigned, and cannot be assigned to one of the projects that are delivered with the ThingWorx Apps extension. They can be assigned to the PTCDefaultProject project or to a new project that you have created.
All entities that are delivered with the ThingWorx Apps extension retain their project setting from the previous release after upgrading to 9.1. Whether a project is assigned, or the Project field is blank, that value is retained. For editable entities that are delivered with the ThingWorx Apps extension, the Project field in ThingWorx Composer is set to read-only after upgrading.
Any entities that were created or duplicated in a previous release retain their assigned project after upgrading to 9.1, even if they are assigned to one of the ThingWorx Apps extension projects. If no project was assigned in the previous release, the PTCDefaultProject project will be assigned after the upgrade.
For more information, see Duplicating Extension Entities in this help center, and Projects in the ThingWorx Help Center.
18. If you customized your ThingWorx Apps, refer to Upgrade and Customizations to address any impact to your customizations resulting from the upgrade.
Was this helpful?