Upgrading the Azure IoT Hub Connector from v.2.0.x to 3.0.0
Upgrading the Azure IoT Hub Connector from v.2.0.x to 3.0.0
This topic explains how to upgrade an Azure IoT Hub Connector from version 2.0.x to 3.0.0, including upgrading the Azure IoT Hub Extension.
Upgrading the Extensions
Assuming that you have completed all the Azure IoT setup required, download the distribution for the new Connector. For details, refer to Step 2. Download and Install the Azure IoT Hub Connector.
First, upgrade the extensions by importing the new extensions. It is safe to import both extensions, one after the other, starting with the CSE:
1. Assuming that you are upgrading from v.1.4.2 of the CSE, import the new version of the extension, 1.5.5 for v.3.0 of the Azure IoT Hub Connector. Importing the new extension queues the upgrade for the next restart of the ThingWorx Platform.
2. Assuming that you are upgrading from v.2.0.x to v.3.0.0 of the Connector and this extension, import the new Azure IoT Extension. This import queues the upgrade for the next restart of the ThingWorx Platform.
* 
This import generates a warning that can be ignored:

A major version change is detected for extension
Azure_ExtensionPackage. Check extensions and
entities that depend on it for compatibility.
If you want to install an eMessage Connector and connect it to the same ThingWorx Platform as your Azure IoT Hub Connector, follow the instructions in Connecting an Azure IoT Hub Connector and an eMessage Connector to the Same ThingWorx Platform.
Upgrading the Connector
Upgrading the Connector from 2.0.x to 3.0.0 requires you to make configuration changes, and create new Things to model your Azure IoT Hub, and Azure blob storage. In v.3.0.0 the Connector relies on configuration in the ThingWorx Platform more than in previous versions. This communication relays Azure IoT Hub secrets from the platform to the Connector, so you must also set up encryption. After configuring the Connector, you can also encrypt the configuration file.
Migrate the Connector Configuration
To migrate the connector configuration from v.2.0.x to v.3.0.0 follow these instructions:
Encrypt the Azure IoT Hub Secrets
Starting with v.3.0.x, the Connector queries the ThingWorx Platform for all of the Azure IoT Hub, Azure IoT Event Hub, and Azure blob connection strings, or secrets. All of this information is encrypted on the platform before being transferred to the Azure IoT Hub Connector. To ensure the success of the encryption and decryption process, you must use the ThingWorx Security Manager tool to set up a keystore and keys on both the platform and the Connector. Refer to Step 7. Set Up Encryption for Azure IoT Hub Credentials for details.
* 
When upgrading the Connector and creating the encryption configuration file, leave the keystore as .jks. Otherwise a new keystore is created as named but the old keys are not migrated. If you leave the extension as .jks, a new keystore is created and all the old keys are migrated.
Encrypt the Configuration File
With version 3.0.x of the Connector you can encrypt the configuration file of the Connector to protect the ThingWorx application key. After updating the configuration file of the Connector to work with the 3.0.x version, encrypt it by following the steps in Step 8. Encrypt the Configuration File.
Updating Things
All existing Things in your ThingWorx Platform need to be upgraded. Follow these steps:
1. Log in to ThingWorx Composer.
2. Navigate to each Thing that communicates with Azure IoT.
3. For each Thing, set the gatewayThing property to the name of the new Azure IoT Hub Thing that you created when setting up your Connector on the platform.
By setting the gatewayThing property on each Azure IoT Thing you are allowing incoming and outgoing messages to be routed to the Connector.
* 
The status of the connection to the ThingWorx Platform of the AzureIotHub Thing determines the connection status for all the AzureIotThings that have their gatewayThing property set to the name of that AzureIotHub Thing. It is possible for a device to actually be disconnected but have its isConnected and isReporting properties showing that it is connected.
Updating the Environment Variables for the Connector
With the new encryption options, you must create a configuration file for the Security Management Tool and then update the environment variables for the Connector. To tell the Security Management Tool where to find its configuration file, set secret.management.config.file to the path to that configuration file, encryption.conf. This configuration file is used by the Connector for decrypting the encrypted Azure IoT Hub credentials from the ThingWorx Platform, as well as for decrypting its own encrypted configuration file. For example:
On Linux:

export AZURE_IOT_OPTS="-Dsecret.management.config.file=
<your-encryption.conf-path>/encryption.conf
-Dconfig.file=<your-connector-config-path>/azure-iot.conf.encrypted
-Dlogback.configurationFile=<your-connector-config-path>/logback.xml"
On Windows:

set AZURE_IOT_OPTS=-Dsecret.management.config.file=
<your-encryption.conf-path>/encryption.conf
-Dconfig.file=<your-connector-config-path>\azure-iot.conf.encrypted
-Dlogback.configurationFile=<your-connector-config-path>\logback.xml
* 
In the command-line examples above, line feeds have been added for publishing purposes. If you want to copy/paste the commands, first paste them into a text editor and remove the line feeds. Then copy into your shell or Command Prompt window. There should be a space between the end of a -D entry and the beginning of the next one.
If You Use an Unencrypted Connector Configuration File
If you choose to leave your connector configuration file unencrypted, you must add the config.plaintext=true option before starting the Connector, as shown in the following examples in this font:
On Linux

export AZURE_IOT_OPTS="-Dsecret.management.config.file=
<your-connector-config-path>/encryption.conf
-Dconfig.plaintext=true
-Dconfig.file=<your-connector-config-path>/azure-iot.conf
-Dlogback.configurationFile=<your-connector-config-path>/logback.xml"
On Windows

set AZURE_IOT_OPTS=-Dsecret.management.config.file=<your-connector-config-path\encryption.conf
-Dconfig.plaintext=true
-Dconfig.file=<your-connector-config-path>/azure-iot.conf
-Dlogback.configurationFile=<your-connector-config-path>\logback.xml
* 
In the command-line examples above, line feeds have been added for publishing purposes. If you want to copy/paste the commands, first paste them into a text editor and remove the line feeds. Then copy into your shell or Command Prompt window. There should be a space between the end of a -D entry and the beginning of the next one.
Additional Steps
If you have not already, follow these procedures for your environment:
Running the Smoke Test
Before starting up the Azure IoT Hub Connector, it is recommended that you run the v.3.0.0 smoke test first to verify your configuration is correct. To run the smoke, test, it is strongly recommended that you set the AZURE_IOT_SMOKETEST_OPTS environment variable to the settings for AZURE_IOT_OPTS:

AZURE_IOT_SMOKETEST_OPTS=$AZURE_IOT_OPTS
export AZURE_IOT_SMOKETEST_OPTS
./azure-iot-smoketest
For instructions on running the smoke test, refer to Running the Smoke Test.
If all is configured correctly, the following output appears:

2019-09-09 16:41:04.910 INFO
Finished test 1/5: Validate connection to ThingWorx Platform result=SUCCESS
2019-09-09 16:41:05.345 INFO
Finished test 2/5: Validate the Azure IoT Connector configuration file result=SUCCESS
2019-09-09 16:41:05.382 INFO
Finished test 3/5: Validate that the ConnectionServicesHub Thing exists result=SUCCESS
2019-09-09 16:41:06.119 INFO
Finished test 4/5: Validate creating test Thing on the Thingworx Platform result=SUCCESS
2019-09-09 16:41:09.728 INFO
Finished test 5/5: Validate sending telemetry data (properties) to Azure IoT Hub device
result=SUCCESS
2019-09-09 16:41:09.926 INFO Overall test result=SUCCESS,
5 tests completed, 0 failed, 0 skipped