Upgrading the Azure IoT Hub Connector from 3.0.0 to 4.0.0
This topic explains how to upgrade an Azure IoT Hub Connector from version 3.0.0 to version 4.0.0. 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 data from the edge to ThingWorx Platform
The instructions also assume that you are running ThingWorx Platform 8.5.x, Azure IoT Hub Connector v.3.0.0, Connection Services Extension (CSE) v.1.5.5, and the Azure IoT Hub Adapter Extension v.3.0.0.
Before you begin, ensure 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 that Services page, run the WriteToTextFile to verify file creation from the ThingWorx Platform.
5. From the Services page, run GetFileListingWithLinks or GetDirectFileDownloadURL to verify file download capabilities.
Then follow these steps:
1. Shut down the Azure IoT Hub Connector and ThingWorx Platform.
2. Upgrade your ThingWorx Platform, following the instructions in the
Upgrading ThingWorx section of the ThingWorx Platform 9 Help Center.
3. Start ThingWorx Platform 9.0.
The rest of this topic explains how to upgrade a ThingWorx Azure IoT Hub Connector from version 3.0.0 to version 4.0.0 when using ThingWorx Platform 9.0 in single-server mode. Refer to the following sections:
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.0.0. Before you begin the upgrade, here are some best practices to follow:
• 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 Azure IoT Extension, v.4.0.0, into ThingWorx Platform v.9.0.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.
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.0.0, follow these steps:
1. Using ThingWorx Composer, import the new version of the Connection Services Extension (CSE) into the ThingWorx Platform.
2. Using ThingWorx Composer, import the new version of the Azure IoT Hub Adapter Extension into the ThingWorx Platform.
 |
For step-by-step instructions for importing the extensions, refer to
Step 3. Import the Extensions
|
Upgrading the Connector from v.3.0.0 to 4.0.0
These are the instructions for upgrading the ThingWorx Azure IoT Hub Connector from version 3.0.0 to version 4.0.0:
1. To download the distribution bundle for your operating system, go to
the PTC Support site, Software Download page and follow these steps:
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 Azure IoT Hub, and then the node, Most Recent Datecode.
d. Select the ThingWorx-Azure-IoT-Hub_Connector-4-0-0 and click HTTPS to download the distribution bundle.
2. Extract the downloaded zip file to an appropriate location.
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.
|
|
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 for Connecting to a ThingWorx Platform in Single-Server Mode. Then encrypt the 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 set the required permissions and visibility before starting the Connector.
10. Ensure that the extensions provided with the Azure IoT Hub Connector, v.4.0.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.3.0.0 Azure IoT Hub Connector.
12. Start the v.4.0.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 shows up in the Connection Servers Monitoring Mashup.
14. 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 that Services page, run the WriteToTextFile to verify file creation from the ThingWorx Platform.
5. From the Services page, run GetFileListingWithLinks or GetDirectFileDownloadURL to verify file download capabilities.