Upgrading the ThingWorx eMessage Connector > Upgrading a ThingWorx eMessage Connector to Version 2.2.0
Upgrading a ThingWorx eMessage Connector to Version 2.2.0
This topic explains how to upgrade a ThingWorx eMessage Connector from version 2.1.x to version 2.2.0 when using the Connector in a ThingWorx Single-Server Environment and when using it in a ThingWorx High Availability Clustering environment. Before you begin, read the section, Best Practices for Upgrading.
Best Practices for Upgrading 
Before you begin any upgrade, here are some best practices to follow:
• Before you upgrade the ThingWorx Platform, export any entities you want to preserve.
• Upgrade your ThingWorx Platform computer to Java 11 and then upgrade your ThingWorx Platform to v.9.2.x before you begin the upgrade for the Axeda Compatibility Package. You will import the extensions provided in the Axeda Compatibility Package into the upgraded platform instance.
• Similarly, upgrade the machine that will run the eMessage Connector v.2.2.0 to use Java 11.
• After upgrading to Java 11, make sure that you set the JAVA_HOME environment variable to point to the Java 11 JDK.
• Copy any site-specific configuration values from the existing installation configuration to the new installation configuration file. Do not just copy the existing emessage-ha-sample.conf file to the new installation.
• When the upgrade is complete, import the exported entities into the new ThingWorx Platform v.9.2.x. You must 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 the entities because the entities are installed as new entities, not as upgraded entities.
• 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
Steps Overview 
Upgrading to version 2.2.0 of the Axeda Compatibility Package differs from previous upgrade procedures, as follows:
1. Before upgrading ThingWorx Platform, you must export any entities that you have created using the entities in the Axeda Compatibility Extension (ACE) or Remote Access Extension (RAE).
2. After exporting your entities, shut down the ThingWorx Platform instances, and upgrade them to run Oracle JDK 11 or Amazon Corretto Java 11 (Open JDK).
3. Upgrade your ThingWorx Platform instances to version 9.2.x. For instructions on upgrading ThingWorx Platform, refer to the instructions for upgrading in the ThingWorx Platform 9 Help Center.
4. Download the Axeda Compatibility Package v.2.2.0 distribution bundle and extract it, as explained in Downloading the Distribution Bundle.
5. Install the new versions of the CSE, RAE, and ACE extensions on a v.9.2.x ThingWorx Platform, as explained in Upgrading the Extensions.
6. REQUIRED: Restart the ThingWorx Platform after importing the extensions.
7. From ThingWorx Composer v.9.2.x, create new security entities for the eMessage Connector, as explained in Create Security Entities in ThingWorx for a Connector and for Remote Access. If you exported the security entities for the Connector when you upgraded ThingWorx Platform, you should verify that they have been imported properly.
8. Upgrade the machine running the eMessage Connector to run Java 11, either Oracle JDK 11 or Amazon Corretto 11 (OpenJDK).
10. From ThingWorx Composer, you must run the permissions services for the eMessage Connector, as explained in Setting Up Permissions and Visibility for the eMessage Connector. The entities and services provided in v.2.2.0 have changed in this release and the eMessage Connector will not work as expected if you do not run the updated permissions services.
Downloading the Distribution Bundle 
To download the distribution bundle for your operating system, follow these steps:
2. Select the Product Family, THINGWORX CONNECTION SERVICES.
3. 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.2 node.
4. Expand the node, ThingWorx Axeda Compatibility Package, and then the node, Most Recent Datecode.
5. Click HTTPS to download the distribution bundle.
6. Extract the downloaded file to an appropriate location.
Upgrading the Extensions 
All of the extensions in the ThingWorx Axeda Compatibility Package are compatible with Java 11. This includes the Axeda Compatibility Extension (ACE), Connection Services Extension (CSE), and Remote Access Extension (RAE).
Before upgrading the ThingWorx Utilities Core Extension and the ThingWorx Utilities Software Content Management (SCM) Extension, complete the upgrades of the CSE, RAE, ACE, and eMessage Connector. Then, refer to Upgrading to a New Version of ThingWorx Utilities and Avoiding Upgrade Impacts in the ThingWorx Utilities help center for upgrade instructions.
* 
This release of the Axeda Compatibility Package does not require and therefore does not include a Migrator for the Axeda Compatibility Extension (ACE). If you are running a version prior to v.1.3.x and require the Migrator, first upgrade to ACP v.1.3.x and run the Migrator for that version. Then upgrade to v.2.2.0.
As part of upgrading to RAE v.3.0.0 and ACE v.5.0.0, you need to import the RAE before importing the ACE. You must also restart the ThingWorx Platform and rerun the permissions scripts after importing ACE. Assuming that you exported your entities and upgraded the ThingWorx Platform, follow these steps to upgrade the extensions provided in the Axeda Compatibility Package, v.2.2.0:
1. Import the CSE into the ThingWorx Platform first.
* 
For assistance with the import procedure, refer to Importing the Extensions (CSE, RAE, and ACE).
2. Import the RAE.
3. Import the ACE.
4. Import your entities back into the platform.
5. Restart the ThingWorx Platform. This restart is required to update the entities per the new extensions and entities. Make sure that you restart the ThingWorx Platform before running the permissions services. If you do not, the services may fail.
6. Finally, you must run the permissions services provided in the eMessageServices Thing and, if you require remote access functionality, the services of the RemoteAccessPermissionServices Thing. Running these services is required to grant runtime permissions to new services and entities provided in this release. The eMessage Connector does not have Execute permissions on a new service or visibility to a GASModel Thing until the permissions services are run.
Upgrading from v.2.1.x to 2.2.0 in a ThingWorx Single-Server Environment 
These instructions explain how to upgrade the ThingWorx eMessage Connector from v.2.1.x to v.2.2.0 when the eMessage Connector connects to a ThingWorx Platform single-server environment.
1. If you want to but have not yet upgraded to Java 11, you must do so before attempting to install v.2.2.0 of the eMessage Connector. It is recommended that you perform a fresh installation of Java 11 and then a fresh installation of the Connector. The Oracle Java SE Development Kit 11 is available for download at https://www.oracle.com/java/technologies/javase-jdk11-downloads.html. The Amazon Corretto 11 (OpenJDK 11) is available for download at https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html.
* 
Make sure you set the JAVA_HOME environment variable to point to the new JDK installation.
2. Stop the eMessage Connector that you want to upgrade.
3. Ensure that the CSE, ACE, and RAE extensions provided with the Axeda Compatibility Package, v.2.2.0, have been imported to the ThingWorx Platform. For assistance, refer to the section above, Upgrading the Extensions.
* 
Before upgrading the ThingWorx Utilities Core Extension and the ThingWorx Utilities Software Content Management (SCM) Extension, complete the upgrades of the CSE, RAE, ACE, and eMessage Connector. Then, refer to Upgrading to a New Version of ThingWorx Utilities and Avoiding Upgrade Impacts in the ThingWorx Utilities help center for upgrade instructions.
4. Restart the ThingWorx Platform to ensure that the entity changes required take place in the database.
5. On the eMessage Connector machine, navigate to the <emessage_connector_install>/conf directory of the new installation (extracted), and make a backup copy of the emessage-ha-sample.conf configuration file. Then open the emessage-ha-sample.conf file in a text editor.
6. If the currently installed eMessage Connector is using an encrypted configuration file and you want to copy settings from it into the new configuration file, decrypt the existing configuration file, following the decrypting instruction in Step 5 of the procedure in Encrypting the Configuration File.
* 
Follow the instructions in Minimal Configuration to Connect to a Single-Server ThingWorx Platform Using SSL/TLS. Then encrypt the new configuration file.
7. To copy settings from the decrypted configuration file, open it in a text editor.
8. If TLS is used for connections between the eMessage Agent devices and the eMessage Connector, convert the JKS keystore to a PKCS#12 keystore, following the instructions in Converting JKS Keystores to PKCS Keystores.
* 
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.
9. In the new configuration file, update the cx-server.protocol.ssl.key-store.file property in the configuration file to point to the PKCS#12 keystore.
10. If the password has changed, update the cx-server.protocol.ssl.key-store.password property in the configuration file.
11. Copy 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).
12. Save the configuration file.
13. To encrypt the configuration file again, follow the instructions in Setting Up an Encrypted Configuration File for an eMessage Connector.
14. If you created a new configuration file, be sure to update the environment variables to point to the location of the new configuration file. For assistance with this step, refer to Setting Environment Variables for an eMessage Connector.
15. 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.
16. Assuming that the Axeda Compatibility Extension (ACE) v.5.0.0 has been imported, log in to ThingWorx Composer on the ThingWorx Platform instance where you imported the extension. You need to verify the TokenPropertyAuthenticator settings on the platform. For instructions, refer to Configuring the TokenPropertyAuthenticator (eMessage Connector).
17. If you have not already, shut down the v.2.1.0 eMessage Connector.
18. Start the v.2.2.0 eMessage Connector. For assistance, refer to Starting the eMessage Connector and Running a Quick Test.
19. 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.
20. After the upgrade is complete, you must run the permissions and visibility scripts for the Connector. Refer to Setting Up Permissions and Visibility for the eMessage Connector. Running these scripts is required to grant runtime permissions to new services provided in this release and to re-apply permissions not preserved upon export/import for an upgrade.
21. Run the Smoke Test, as explained in Running the Smoke Test
Upgrading from 2.1.x to 2.2.0 in a ThingWorx High Availability Clustering Environment 
These instructions explain how to upgrade the eMessage Connector from version 2.1.x to version 2.2.0 in a ThingWorx High Availability Clustering environment.
1. If you want to but have not yet upgraded to Java 11, you must do so before attempting to install v.2.2.0 of the eMessage Connector. It is recommended that you perform a fresh installation of Java 11 and then a fresh installation of the Connector. The Oracle Java SE Development Kit 11 is available for download at https://www.oracle.com/java/technologies/javase-jdk11-downloads.html. The Amazon Corretto 11 (OpenJDK 11) is available for download at https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html.
* 
Make sure you set the JAVA_HOME environment variable to point to the new JDK installation.
2. Stop the eMessage Connector that you want to upgrade.
3. Ensure that the CSE, ACE, and RAE extensions provided with the Axeda Compatibility Package, v.2.2.0, have been imported to the ThingWorx Platform. For assistance, refer to the section above, Upgrading the Extensions.
* 
Before upgrading the ThingWorx Utilities Core Extension and the ThingWorx Utilities Software Content Management (SCM) Extension, complete the upgrades of the CSE, RAE, ACE, and eMessage Connector. Then, refer to Upgrading to a New Version of ThingWorx Utilities and Avoiding Upgrade Impacts in the ThingWorx Utilities help center for upgrade instructions.
4. Restart the ThingWorx Platform to ensure that the entity changes required take place in the database.
5. On the eMessage Connector machine, navigate to the conf subdirectory of the new eMessage Connector installation (created when you extracted), and make a copy of the emessage-ha-sample.conf file and rename it to emessage-ha-sample.conf. Then open it in a text editor.
6. If the currently installed eMessage Connector is using an encrypted configuration file, decrypt it following the decrypting instruction in Encrypting the Configuration File, and open the decrypted file in a text editor. You can use it to copy settings into the new configuration file.
7. If TLS is used for HTTPS connections between the Axeda Agent devices and the eMessage Connector, convert the JKS keystore to a PKCS#12 keystore, following the instructions in Converting JKS Keystores to PKCS Keystores.
* 
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.
8. In the new configuration file, update the cx-server.protocol.ssl.key-store.file property in the configuration file to point to the PKCS#12 keystore.
9. If the password has changed, update the cx-server.protocol.ssl.key-store.password property in the configuration file.
10. Set the following properties to enable service discovery:

cx-server {
. . .
platform.transport = "websockets_active_active"

transport.websockets.service-discovery.enabled = true
. . .
}
11. Add the hosts and ports of the ZooKeeper instances to which the eMessage Connector should connect as a comma-separated list of {host}:{port}, as shown in the following example:

cx-server {
discovery {
connectionString = "zookeeper-1:2181,zookeeper-2:2181,zookeeper-3:2181"
}
}
12. If ZooKeeper is configured to use SSL/TLS, enable the eMessage Connector to connect to ZooKeeper securely by following the instructions in the section, "Configuring the Connection Server," in the topic, Configuring SSL/TLS for ZooKeeper in the ThingWorx Platform 9 Help Center. The instructions for the ThingWorx Connection Server apply to the eMessage Connector.
13. If Zookeeper is configured to use Simple Authentication and Security Layer (SASL), enable the SASL support in the eMessage Connector by uncommenting and setting the following properties:

cx-server {
. . .
#transport.websockets.discovery {
# sasl-enabled = true
# sasl-krb5-conf-file = /path/to/kerberos-conf
# sasl-jaas-file = /path/to/jaas-conf
#}
}
* 
For information about configuring SASL for ZooKeeper, refer to ZooKeeper and SASL Client-Server mutual authentication.
14. The eMessage Connector needs to be configured with the service name used to look up the ThingWorx Platform instances in ZooKeeper and to determine whether to connect securely to the registered ThingWorx Platform instances.
◦ To connect securely with SSL/TLS to the ThingWorx Platform instances, uncomment and set the following properties:

cx-server {
#transport.websockets.service-discovery.tls-enabled = true
#transport.websockets.service-discovery.service-name = "thingworx-https"
}
◦ To connect without SSL/TLS to the ThingWorx Platform instances, uncomment and set the following properties:

cx-server {
# transport.websockets.service-discovery.tls-enabled = false
# transport.websockets.service-discovery.service-name = "thingworx-http"
}
* 
By default the ThingWorx Platform uses the thingworx-http service name when registering its HTTP endpoint information in ZooKeeper and the thingworx-https service name when registering its HTTPS endpoint information. If the ThingWorx Platform is configured to use different service names, be sure to use the correct service name for the eMessage Connector service-discovery.service-name value.
* 
For best security practices, always use SSL/TLS to connect securely to the ThingWorx Platform instances.
If SSL/TLS is used to connect securely to the ThingWorx Platform instances and the SSL/TLS certificates presented by the ThingWorx Platform instances do not contain the instance’s IP address that is registered in ZooKeeper, you must disable host name verification by uncommenting and setting the following property to false, as shown here:

cx-server {
. . .
transport.websockets.connections.verifyHostName = false
. . .
}
* 
The IP address of a ThingWorx Platform instance can be set in the instance’s SSL/TLS certificate either in Subject Common Name (CN) field or in the Subject Alternative Name field. The IP address that the ThingWorx Platform registers in ZooKeeper is either the first site-local IP address, if found, or the first non-loopback IP address found on the available network interfaces.
16. Copy 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 and file uploads. 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
Location for file uploads
Any additional configuration for file transfers
Property settings for Remote Access
Property settings for metrics reporting
17. After setting the properties, save and close the configuration file.
18. To encrypt the configuration file again, follow the instructions in Setting Up an Encrypted Configuration File for an eMessage Connector.
19. Once the new extensions have been imported and the Connector configuration is complete, you must run the permissions and visibility scripts for the Connector. Refer to Setting Up Permissions and Visibility for the eMessage Connector. Running these scripts is required to grant runtime permissions to new services provided in this release and to re-apply permissions not preserved upon export/import for an upgrade.
20. If a new configuration file was created, be sure to update the environment variables to point to the new configuration file location. For assistance with this step, refer to Setting Environment Variables for an eMessage Connector.
21. After setting the environment variables, refer to Setting Up Permissions and Visibility for the eMessage Connector to set the required permissions and visibility before starting the Connector.
22. Start the v.2.2.0 eMessage Connector. For assistance, refer to Starting the eMessage Connector and Running a Quick Test.
23. Assuming that the Axeda Compatibility Extension (ACE) v.5.0.0 has been imported and that you have run the permissions scripts for the eMessage Connector, log in to ThingWorx Composer on the ThingWorx Platform instance where you upgraded the extensions. You need to verify the TokenPropertyAuthenticator settings on the platform. For instructions, refer to Configuring the TokenPropertyAuthenticator (eMessage Connector).
24. 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.
25. Run the Smoke Test, as explained in Running the Smoke Test
* 
Now that you have upgraded the CSE, RAE, ACE, and eMessage Connector, upgrade ThingWorx Utilities Core and SCM extensions. For instructions, refer to the topics in the ThingWorx Utilities Help Center, Upgrading to a New Version of ThingWorx Utilities and Avoiding Upgrade Impacts.
Was this helpful?