Upgrading a ThingWorx eMessage Connector to Version 1.2.7 (ACP v.1.3.1)
This topic explains how to upgrade a ThingWorx eMessage Connector to version 1.2.7. Click the title to expand each of the following sections, in the order in which they appear here:
Best Practices for Upgrading
Upgrading the eMessage Connector involves installing a new instance of the Connector. Upgrading the Connector also means installing the new versions of the extensions in your ThingWorx Axeda Compatibility Package on your ThingWorx Platform. Before you begin the upgrade, here are some best practices to follow:
• Before upgrading the eMessage Connector and extensions, you need to export any entities from ThingWorx Platform that were created for use with the Connector. Upgrade the ThingWorx Platform next.
• Copy any site-specific configuration values from the existing installation configuration to the new installation configuration file. Do not just copy over the existing emessage-ha-sample.conf file.
• After importing the Axeda Compatibility Extension into ThingWorx Platform, import your exported entities and re-run the permissions services, as explained in Setting Up Permissions and Visibility for the eMessage Connector. The required permissions are not automatically re-applied when importing your exported entities because the entities are installed as new entities, not as upgraded entities, when you are using this method of upgrading the platform.
• As needed, create any new security entities that you may need. For assistance, refer to Create Security Entities in ThingWorx for a Connector and for Remote Access.
• As a security best practice, convert any JKS keystores to PKCS #12 keystores. For assistance, refer to Converting JKS Keystores to PKCS Keystores
Upgrading the Extensions
All of the extensions in the ThingWorx Axeda Compatibility Package have been upgraded to work in a ThingWorx High Availability Clustering environment. This includes the Axeda Compatibility Extension (ACE), Connection Services Extension (CSE), Remote Access Extension (RAE), ThingWorx Utilities Core Extension, and ThingWorx Utilities Software Content Management (SCM) Extension.
To upgrade the extensions provided in the Axeda Compatibility Package, v.1.3.x, involves these steps:
1. Make sure that you exported any entities that you have created using the entities in the extension.
2. Uninstall the existing extension.
3. Import the new extension into the ThingWorx Platform. For assistance with this step, refer to Importing the Extensions (CSE, RAE, and ACE).
4. Import your entities back into the platform.
Upgrading the eMessage Connector to v.1.2.7
Here are the instructions for upgrading the ThingWorx eMessage Connector to v.1.2.7 (ACP v.1.3.1):
1. To download the distribution bundle for your operating system, go to the PTC Support site, Software Download page and then
a. Select the Product Family, THINGWORX CONNECTION SERVICES.
b. On the download page for the ThingWorx Connection Services Product Family, the releases are numbered by the related release of ThingWorx Platform. To upgrade, expand the Release 9.0 node.
c. Expand the node, ThingWorx Axeda Compatibility Package, and then the node, Most Recent Datecode.
d. Select the Axeda-Compatibility-Package-1-3-1 file and click HTTPS to download the distribution bundle.
2. Extract the downloaded zip file to an appropriate location.
3. If the currently installed eMessage Connector is using an encrypted configuration file, decrypt it following the decrypting instruction in Step 5 of the procedure in Encrypting the Configuration File.
 | If necessary, you can create a new configuration file by following the instructions in to create a new configuration file. Then follow the instructions in Minimal Configuration to Connect to a Single-Server ThingWorx
Platform Using SSL/TLS. Then encrypt the new configuration file. |
4. Open the decrypted configuration file.
5. If TLS is used for connections between the eMessage Agent devices and the eMessage Connector, convert the JKS keystore to a PKCS#12 keystore.
 | If you must continue using a JKS keystore, set the cx-server.protocol.ssl.key-store.type property to jks in the configuration file and skip the rest of this step. Using a JKS keystore is discouraged because it is less secure format than PKCS#12. |
a. To convert the existing eMessage Connector keystore from a JKS keystore to a PKCS#12 keystore, follow the instructions in the topic, Converting JKS Keystores to PKCS Keystores.
b. In the configuration file, update the cx-server.protocol.ssl.key-store.file property in the configuration file to point to the PKCS#12 keystore.
c. If the password has changed, update the cx-server.protocol.ssl.key-store.password property in the configuration file.
6. Migrate any site-specific settings from your existing emessage-ha-sample.conf file. If you have been using the file transfer capabilities, you must specify the location for file downloads. The following table lists additional settings that you may want to migrate and the help topic that explains them:
Settings | Help Topic |
|---|---|
Location for file downloads REQUIRED | |
Location for file uploads REQUIRED | |
Any additional configuration for file transfers | |
Property settings for Remote Access | |
Property settings for metrics reporting |
Later, after completing the upgrade, check the TokenPropertyAuthenticator on the platform. For instructions on its configuration, refer to Configuring the TokenPropertyAuthenticator (eMessage Connector).
7. Save the configuration file.
8. To encrypt the configuration file again, follow the instructions in Setting Up an Encrypted Configuration File for an eMessage
Connector.
9. As needed, update the EMESSAGE_OPTS environment variable to point to the location of the configuration file. For assistance with this step, refer to Setting Environment Variables for an eMessage Connector.
10. After setting the environment variable, refer to Setting Up Permissions and Visibility for the eMessage Connector to set the required permissions and visibility before starting the Connector.
11. Ensure that the extensions provided with the Axeda Compatibility Package, v.1.3.1, have been imported to the ThingWorx Platform. For assistance, refer to Importing the Extensions (CSE, RAE, and ACE) in this Help Center.
12. Assuming that the Axeda Compatibility Extension (ACE) has been imported, log in to ThingWorx Composer. You need to verify the TokenPropertyAuthenticator settings on the platform. For instructions, refer to Configuring the TokenPropertyAuthenticator (eMessage Connector).
13. If you have not already done so, shut down the old eMessage Connector.
14. Start the new eMessage Connector. For assistance, refer to Starting the eMessage Connector and Running a Quick Test.
15. Verify that the eMessage Connector successfully connected to ThingWorx by confirming it appears in the ThingWorx Composer list of Connection Servers. In ThingWorx Composer, click the 
icon (Monitoring menu) and then select Connection Servers to display the page.
icon (Monitoring menu) and then select Connection Servers to display the page.16. Run the Smoke Test, as explained in Running the Smoke Test