Upgrading the Azure IoT Hub Connector from 4.0.x to 4.1.x
This topic explains how to upgrade an Azure IoT Hub Connector from version 4.0.x to version 4.1.x. These instructions assume that you have the following ThingWorx entities on your current ThingWorx Platform:
• An AzureIotHubTemplate Thing
• An AzureBlobStorageTemplate Thing
• An AzureIotThing that represents the edge module
• A Thing Shape that you can use to test the flow of telemetry from the edge to ThingWorx Platform
Important! The instructions also assume that you are running ThingWorx Platform 9.0.3 or later, Azure IoT Hub Connector v.4.0.0, Connection Services Extension (CSE) v.2.0.0, and the Azure IoT Hub Adapter Extension v.4.0.0. If you are running Azure IoT Hub Connector, v.3.0.0, upgrade to 4.0.x before upgrading to 4.1.x, as explained in
Upgrading the Azure IoT Hub Connector from 3.0.0 to 4.0.0.
Before starting the ThingWorx Platform or Connector upgrade, follow these steps:
1. Before shutting down ThingWorx Platform, export your Azure-related entities. Later when the platform upgrade is complete, you can import the Azure entities.
2. Shut down the Azure IoT Hub Connector and ThingWorx Platform.
3. Upgrade your ThingWorx Platform, following the instructions in the
Upgrading ThingWorx section of the ThingWorx Platform 9 Help Center.
4. Start your ThingWorx Platform 9.x.x in single-server mode or HA Clustering mode.
5. Import the Azure-related entities into the upgraded ThingWorx Platform.
The rest of this topic explains how to upgrade a ThingWorx Azure IoT Hub Connector from version 4.0.x to version 4.1.x when you have been using ThingWorx Platform 9.0.3 or later in single-server or HA Clustering mode. Follow the instructions that apply to your platform implementation.
Click a section title to display its content. Click the title again to hide the content:
Best Practices for Upgrading
Upgrading the Azure IoT Hub Connector involves installing a new instance of the Connector. Upgrading the Connector also means importing the new versions of the extensions in your ThingWorx Azure IoT Hub Connector distribution bundle into your ThingWorx Platform, v.9.1.0. Before you begin the upgrade, here are some best practices to follow:
• Before shutting down your ThingWorx Platform for an upgrade, export entities that you want to preserve. After the upgrade, import them into the new installation of the platform.
• Upgrade your ThingWorx Platform computer to Java 11 and then upgrade your ThingWorx Platform to v.9.1.0 before you begin the upgrade for the Azure IoT Hub Connector. You will import the extensions provided in the Connector distribution bundle into the upgraded platform instance.
• Similarly, upgrade the computer that will run the Azure IoT Hub Connector v.4.1.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.
• If you are upgrading to a ThingWorx High Availability Clustering environment with multiple instances of ThingWorx Platform from a single-server ThingWorx Platform installation, consider using the azure-iot-ha-sample.conf as a starting point.
• Copy any site-specific configuration values from the existing installation configuration to the new installation configuration file. Do not just copy over the existing azure-iot.conf file.
• After importing the Connection Services Extension, v.2.2.2, and the Azure IoT Extension, v.4.1.0, into ThingWorx Platform 9.1.0, re-run the permissions services, as explained in
Step 9. Run the Service to Grant Permissions and Visibility
to the Connector. This practice is important to do whether you followed the ThingWorx migration described in
Migrating to ThingWorx: Linux or the migration described in
Migrating to ThingWorx: Windows. The required permissions are not automatically re-applied when importing the 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
Step 4. Create Security Entities for the Connector.
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.1 node.
4. Expand the node, ThingWorx Azure IoT Hub, 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
The extensions in the ThingWorx Azure IoT Hub Connector distribution bundle, the Azure IoT Extension and the Connection Services Extension (CSE), have been upgraded for this release.
To upgrade the extensions provided in the ThingWorx Azure IoT Hub Connector distribution bundle, v.4.1.0, follow these steps:
1. Using ThingWorx Composer, import the new version of the Connection Services Extension (CSE) into the ThingWorx Platform.
 |
For step-by-step instructions for importing the extensions, refer to
Step 3. Import the Extensions
|
2. Using ThingWorx Composer, import the new version of the Azure IoT Hub Adapter Extension into the ThingWorx Platform.
Upgrading the Connector from v.4.0.0 to 4.1.0 to Run in Single-Server Mode
These are the instructions for upgrading the ThingWorx Azure IoT Hub Connector from version 4.0.0 to version 4.1.0 when running ThingWorx Platform in a single-server environment:
1. If you want to but have not yet upgraded to Java 11, you must do so before attempting to install the 4.1.x version of the Azure IoT Hub 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. Navigate to the connector/conf subdirectory of the new Azure IoT Hub Connector installation, and make a copy of the azure-iot-sample.conf file and rename it to azure-iot.conf. Then open it in a text editor.
3. To re-use an existing encrypted configuration file for single-server ThingWorx, decrypt it by following the decrypting instruction in .
|
|
If you are upgrading to use the Azure IoT Hub Connector in a ThingWorx High Availability (HA) Clustering environment, you should create a new configuration file by following the instructions in
High Availability Configuration. If you are using the Connector in a single-server ThingWorx Platform environment, you can but do not need to create a new configuration file by following the instructions in
Minimal Configuration for Connecting to a ThingWorx Platform in Single-Server Mode. Regardless of the ThingWorx Platform environment, make sure that you encrypt any new configuration file.
|
4. Open the decrypted configuration file.
5. Migrate any site-specific settings from your existing azure-iot.conf file. If you have been using the file transfer capabilities, you must specify the location for file uploads. The following table lists additional settings that you may want to migrate and the help topic that explains them:
|
Settings
|
Help Topic
|
|---|---|
|
Any additional configuration for file transfers
|
|
|
Property settings for metrics reporting
|
6. Save the configuration file.
7. To encrypt the configuration file again, follow the instructions in
Step 7. Encrypt the Configuration File.
8. 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
Step 8. Set the Environment Variables for the Azure IoT Hub
Connector .
9. After setting the environment variable, refer to
Step 9. Run the Service to Grant Permissions and Visibility
to the Connector to grant runtime permissions to new services provided in this release and to re-apply permissions not preserved upon export/import for an upgrade. This step is required.
10. Ensure that the extensions provided with the Azure IoT Hub Connector, v.4.1.0, have been imported to the ThingWorx Platform. For example, from ThingWorx Composer, browse Thing Templates and look for the AzureIotThing Thing Template, the AzureIotHubTemplate Thing Template, and the AzureBlobStorageTemplate Thing Template.
11. If you have not already done so, shut down the v.4.0.0 Azure IoT Hub Connector.
12. Start the v.4.1.0 Azure IoT Hub Connector. For assistance, refer to
Step 10. Start the Azure IoT Hub Connector.
13. Verify that the Azure IoT Hub 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.14. Run the Smoke Test, as explained in
Running the Smoke Test.
Upgrading from 4.0.0 to 4.1.0 to Run in a ThingWorx High Availability Clustering Environment
These instructions explain how to upgrade the Azure IoT Hub Connector from version 4.0.0 in a ThingWorx single-server mode to version 4.1.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 the 4.1.x version of the Azure IoT Hub 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. Navigate to the connector/conf subdirectory of the new Azure IoT Hub Connector installation, and make a copy of the azure-iot-ha-sample.conf file and rename it to azure-iot.conf. Then open it in a text editor.
3. If the currently installed Azure IoT Hub Connector is using an encrypted configuration file, decrypt it following the decrypting instruction in
Step 5 of the procedure in Encrypting the Configuration File.
4. Open the decrypted configuration file.
5. The Azure IoT Hub Connector will look up ThingWorx Platform instances in the High Availability (HA) Clustering environment from ZooKeeper. The following properties enable service discovery with ZooKeeper; leave the default values shown here:
cx-server {
. . .
platform.transport = "websockets_active_active"
transport.websockets.service-discovery.enabled = true
. . .
}
6. Set the hosts and ports of the ZooKeeper instances to which the Azure IoT Hub 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"
}
}
7. If ZooKeeper is configured to use SSL/TLS, enable the Azure IoT Hub 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 Azure IoT Hub Connector.
8. If Zookeeper is configured to use Simple Authentication and Security Layer (SASL), enable the SASL support in the Azure IoT Hub Connector by uncommenting and setting the following properties:
cx-server {
. . .
# transport.websockets.service-discovery {
# sasl-enabled = true
# sasl-krb5-conf-file = /path/to/kerberos-conf
# sasl-jaas-file = /path/to/jaas-conf
#}
}
| |
9. The Azure IoT Hub 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, leave the default values for the following properties as shown here:
cx-server {
transport.websockets.service-discovery.service-name = "thingworx-https"
transport.websockets.service-discovery.tls-enabled = true
}
◦ To connect without SSL/TLS to the ThingWorx Platform instances, set the properties as shown here:
cx-server {
transport.websockets.service-discovery.service-name = "thingworx-http"
transport.websockets.service-discovery.tls-enabled = false
}
 | 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 Azure IoT Hub Connector service-discovery.service-name value. |
10. 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. |
11. Migrate any site-specific settings from the existing configuration file for the Connector. 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 |
|---|---|
Any additional configuration for file transfers | |
Property settings for Service Discovery | Only for HA Clustering environments — refer to
Service Discovery Configuration |
Property settings for metrics reporting |
12. After setting the properties, save and close the configuration file.
13. To encrypt the configuration file again, follow the instructions in
Step 7. Encrypt the Configuration File.
14. 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
Step 8. Set the Environment Variables for the Azure IoT Hub
Connector .
15. After setting the environment variables, refer to
Step 9. Run the Service to Grant Permissions and Visibility
to the Connector to grant runtime permissions to new services provided in this release and to re-apply permissions not preserved upon export/import for an upgrade. This step is required.
16. If you have not already done so, shut down the v.4.0.0 Azure IoT Hub Connector.
17. Start the v.4.1.0 Azure IoT Hub Connector. For assistance, refer to
Step 10. Start the Azure IoT Hub Connector.
18. Verify that the Azure IoT Hub 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.19. If you have not already done so, import the entities you exported back into the ThingWorx Platform.
20. Run the Smoke Test, as explained in
Running the Smoke Test.
Testing the Installation
After upgrading the Azure IoT Hub Connector, test that your current installation is running properly by performing these steps:
1. Upload a file to the Azure Blob Storage Container.
2. From ThingWorx Composer, navigate to the Thing representing your Azure Blob Storage container.
3. Click the Services tab and run the BrowseFileSystem on it to verify that the file is visible from ThingWorx.
4. From the Services page, run GetFileListingWithLinks or GetDirectFileDownloadURL to verify file download capabilities.