ThingWorx Azure IoT Hub Connector 4.2.0 Release Notes
The ThingWorx Azure IoT Hub Connector enables devices that are running agents developed using the Microsoft Azure IoT SDKs for Edge devices to interact with the ThingWorx Platform. It also supports the ThingWorx Azure Industrial Internet of Things (IIoT) OPC UA integration. Customers running ThingWorx Kepware Servers can connect their servers through Microsoft Azure IIoT to ThingWorx Platform.
As of v.4.1.0 of the Connector, support is provided for communicating with ThingWorx Platform running in single-server mode and in High Availability Clustering mode. As of v.4.2.0, the Connector supports ThingWorx Platform v.9.0.x, v.9.1.x, and v.9.2.0. In addition, versions 9.1.x and 9.2.0 of the ThingWorx Platform and versions 4.1.x and 4.2.0 of the Connector run on Oracle JDK 11 and Amazon Corretto 11. Note that, as of v.9.2.0 of the platform and 4.2.0 of the Connector, Java 8 is no longer supported.
The following sections provide important information about v.4.2.0 of the ThingWorx Azure IoT Hub and the ThingWorx Microsoft Azure Industrial IoT (IIoT) integration. Click the title of a section to display its content. To hide the content, click the title again.
Components of the Distribution Bundle
The ThingWorx Azure IoT Hub Connector distribution bundle includes the following components:
• The core connection server and the Azure IoT Hub Protocol Adapter, configured to support Azure IoT Hubs, Azure IoT Edge Devices and Edge Modules, and Azure Blob Storage Containers connected to an Azure IoT Hub. For users of the ThingWorx Azure IIoT OPC UA integration the protocol adapter component translates messages from the OPC UA format into ThingWorx AlwaysOn format and vice versa.
• The Azure IoT Hub Extension must be imported into ThingWorx Platform to support Azure IoT entities. This extension provides entities to support Azure IoT Devices and Azure IoT Edge Devices, Azure IoT Edge Modules, Azure IoT Edge Runtime, an Azure IoT Hub, and Azure Blob Storage Containers. For the Azure OPC UA integration, it provides mashups to support the IIoT entities.
• Another extension, called Connection Services Extension (CSE), manages communication between ThingWorx Platform and the Azure IoT Hub Connector.
Together, these components provide the following features:
• Scalable connectivity between ThingWorx Platform and Azure IoT Hubs, Azure Blob Storage Containers, Azure IoT Devices and Edge Devices, and the Microsoft Azure Industrial IoT (IIoT) Stack for OPC UA.
• Horizontal scalability by adding instances of the ThingWorx Azure IoT Hub Connector and setting up partitions on the Azure IoT Hub to handle increased load. Note that only one Azure IoT Hub is supported for a single Connector.
 |
The Azure IIoT OPC UA integration requires a Publisher module on an IoT Edge Runtime device for each OPC UA Server. All messages from this Publisher module come from the same device, so all messages are sent to the same partition in the IoT Hub. They go through a single Azure IoT Hub Connector. Adding more than one Azure IoT Hub Connector does not help with horizontal scale if all of your data comes from one OPC UA Server. However, multiple Connectors can help if either of the following are true:
• The customer has more than one OPC UA Publisher sending data.
• Other devices are sending data through the IoT Hub in addition to the OPC UA Publisher.
|
• A health check service, logging, and metrics collection enable you to monitor the health of the connection to the ThingWorx Platform in either single-server or clustering mode, as well as the traffic that the platform or cluster is handling. The logging feature provides detailed logs to help in troubleshooting.
• Configuration file to tune settings for the Connector.
• Security for connections to ThingWorx Platform and to Azure IoT and Azure IIoT.
Security
This release of the ThingWorx Azure IoT Hub Connector includes security-related updates, as follows:
• Fixed potential security issues, including items proactively identified by vulnerability scanning software or PTC Quality Assurance testing. Please upgrade as soon as possible to take advantage of these important improvements.
• See this
technical support article for important recommendations regarding the use and update of third-party software for ThingWorx.
Planning an Upgrade Using PTC Release Advisor
PTC
Release Advisor is a new tool that helps customers plan an upgrade of a PTC product, while considering other PTC products they use, and key variables in their environment such as Database and Operating Systems.To learn about PTC Release Advisor, log in to the PTC Support site and go to
the Technical Support article, "How to plan an upgrade using PTC Release Advisor".
|
|
Since PTC Release Advisor is new, information specific to upgrading the ThingWorx Azure IoT Connector and the Microsoft Azure Industrial IoT (IIoT) stack are still provided in this help center. Once customers have had time to experience Release Advisor as the PTC upgrade planning tool, Release Advisor will become the single source for this information and the help center will no longer provide the information. If any critical piece of information is missing from Release Advisor, please contact Technical Support.
|
Extensions Required for the ThingWorx Azure IoT Hub Connector v.4.2.0
The following table shows the required versions of the extensions for this release of the ThingWorx Azure IoT Hub Connector. These versions are provided in the Connector distribution bundle:
|
Extension
|
Version
|
Notes
|
|---|---|---|
|
ThingWorx Connection Services Extension (CSE)
|
2.2.4
|
This version of the CSE is required for use with v.4.2.0 of the Connector and v.9.2.0 of the ThingWorx Platform.
|
|
ThingWorx Azure IoT Hub Connector Extension
|
4.2.0
|
This version of the Azure IoT Extension is required for v.4.2.0 of the Connector and v.9.2.0 of the ThingWorx Platform.
|
Additional Software Requirements
The following table lists the additional, required software for this release of the ThingWorx Azure IoT Hub Connector:
|
Required Product
|
Required Version
|
||||
|---|---|---|---|---|---|
|
Java Development Kit (JDK)
|
The compatible versions of the Java Development Kit for this release follow:
• Oracle JDK 11
• Amazon Corretto 11 (Open JDK)
|
||||
|
Linux 64-bit operating system or Windows 64-bit operating system
|
Tested on Linux 64-bit version of Ubuntu 20.04.2 LTS
|
||||
|
ThingWorx Platform
|
9.2.0
|
If you are using the ThingWorx Azure IIoT OPC UA integration and you are not a PTC Cloud Services customer, you can find all the required software and versions in the table, "Prerequisites", in the topic,
Step 1. Required Resources, of the section, ThingWorx Azure IoT Hub Connector for Azure IIoT OPC UA, in this help center.
What’s Changed in ThingWorx Azure IoT Hub Connector, v. 4.2.0
ThingWorx Azure IoT Hub Connector v.4.2.0 provides the following new features for the ThingWorx Azure Industriall IoT (IIoT) OPC/UA integration:
• Upgrade of the Microsoft Azure IIoT stack to the latest approved version. Instructions for upgrading the Azure IIoT Stack are provided in the topic,
Upgrading the Azure IIoT Stack.
• Optimized OPC/UA batch telemetry processing.
• By default, the ThingWorx Platform automatically manages the publishing and unpublishing of OPC UA nodes to the Azure IoT Hub. When a property in ThingWorx is bound to a tag, the OPC UA node is published and its data is available to multiple consumers. However, when a property that is bound to a tag is deleted, the Connector unpublishes the OPC UA node from the Azure IoT Hub and therefore no longer available to other consumers.
To provide a way for multiple consumers to access data from one or mode nodes that may be deleted by ThingWorx, the v.4.2.0 release of the Connector provides an enhancement. This enhancement allows administrators to disable the automatic publishing/unpublishing of OPC UA nodes by ThingWorx. When automatic publishing/unpublishing is disabled, an OPC/UA node continues to be accessible via the IoT Hub by other applications such as Azure Data Lake if that node is deleted in ThingWorx. For details, refer to
Support for Multiple Consumers of IoT Hub Data.
The following table describes the enhancements and documentation additions for the ThingWorx Azure IoT Hub Connector and for the ThingWorx Azure IIoT OPC UA integration as well as issues fixed in this release:
|
ID (SFID)
|
Description
|
|---|---|
|
Enhancements
|
|
|
AZX-1004
|
Optimized OPC UA batch telemetry processing.
|
|
AZX-1087
|
The Azure IoT Hub Connector has been certified to work with the ThingWorx Platform, v.9.2.0.
|
|
AZX-1128
|
Upgraded the Azure Industrial IoT (IIoT) Stack to the latest approved version. This upgrade is separate from the upgrade of the Azure IoT Hub Connector and should be performed before you upgrade the Connector. If you are not using the ThingWorx Azure Industrial IoT (IIoT) OPC UA integration, you do not need to perform any upgrade for Azure.
|
|
AZX-1194
|
PTC SaaS (Cloud Services) customers can now use ThingWorx Platform in High Availability (HA) Clustering mode with the ThingWorx Azure IIoT OPC UA integration.
|
|
AZX-1269
|
Multiple applications, such as Azure Data Lake, can subscribe to an OPC UA node connected to an Azure IoT Hub that is also connected to ThingWorx, even if the node is deleted on the ThingWorx side.
The current and default behavior is that if an OPC UA node is deleted from ThingWorx, the Connector "unpublishes" the node from the Azure IoT Hub. To enable other applications to continue to access an OPC UA node that has been deleted in ThingWorx, this release provides the following enhancements:
• Added a configuration parameter to the AzureIotHubTemplate Thing to enable or disable automatic node publishing/unpublishing. Called EnableAutoNodePublishing, this parameter defaults to true.
• To publish and unpublish nodes when automatic publishing and unpublishing are disabled, added the services, PublishUANodes and UnpublishUANodes on the AzureIotHubTemplate Thing.
|
|
AZX-1283
|
Updated the Microsoft Azure Industrial IoT (IIoT) stack to the latest approved version. Updated documentation to include upgrade instructions and the change in version.
|
|
AZX-1284
|
Documented how to set up the Azure IoT Hub Connector in firewalled environments. The new topic is
Installing the Connector in Firewalled Environments.
|
|
AZX-1511
|
Updated the Azure IoT Hub Connector smoke test to parse the Connector's configuration option, transport.websockets.connections.verifyHostName. The smoke test can now determine if host name verification should be enabled or disabled when establishing a TLS connection with the ThingWorx Platform.
|
|
Issues Fixed in This Release
|
|
|
AZX-1205
|
Fixed the issue where a restart of all ThingWorx Platform instances in a High Availability (HA) cluster caused the industrial connections and Remote Things to disconnect. This issue is fixed in version 2.2.4 of the Connection Services Extension (CSE).
|
|
AZX-1518
|
Fixed the issue where floating point values on incoming OPC UA data were correct in Microsoft Visual Code but appeared truncated in ThingWorx Composer.
|
For more information about the Microsoft Azure IoT Hub features, refer to the Microsoft Azure IoT Hub developer guide at
https://docs.microsoft.com/en-us/azure/guides/developer/azure-developer-guide.
Known Issues
The following table describes the known issues, and where possible, a workaround:
|
The Azure IoT Hub Connector does not currently support Azure IoT Hub Failover.
CAUSE: If a failover is initiated for an Azure IoT Hub, the ThingWorx Azure IoT Hub Connector checkpointing does not work. Consequently, for the Azure IIoT OPC UA integration with ThingWorx, telemetry stops working.
WORKAROUND: If this unlikely event occurs, delete the checkpoint files. It is likely that some data loss will occur, but this action will get your Connector running again.
|
|
When using the Microsoft Azure SQL database as the ThingWorx Persistence Provider in the ThingWorx Microsoft IIoT OPC UA integration, property bindings do not work. The cause of this issue is the limitation of index size on Microsoft Azure SQL.
The following error message in the ApplicationLog indicates that the ThingWorx AzureOpcUaPropertyMapDataTable data table is present and the index exceeds the Microsoft Azure SQL limitation on indexes:
Unable to add data table entry because com.thingworx.common.exceptions.DataAccessException: [1,018] Data store unknown error: [Error occurred while accessing the data provider.] Unable to dispatch [ uri = /Things/AzureOpcUaPropertyMapDataTable/Services/AddOrUpdateDataTableEntries/]: Unable to Invoke Service AddOrUpdateDataTableEntries on AzureOpcUaPropertyMapDataTable : java.lang.RuntimeException: com.thingworx.common.exceptions.DataAccessException: [1,018] Data store unknown error: [Error occurred while accessing the data provider.] WORKAROUND: Delete both indexes under configuration on the ThingWorx AzureOpcUaPropertyMapDataTable data table. This deletion requires that you restart the ThingWorx Platform for changes to take effect. For more complete information, refer to
Errors When Using Microsoft Azure SQL Database as the ThingWorx Persistence
Provider in the topic,
Troubleshooting the Azure IIoT OPC UA Integration.
|
|
Message ordering is not preserved for a single device.
Although messages are retrieved synchronously from the Azure Event Hub endpoint, messages are dispatched to ThingWorx Platform asynchronously, leading to potential out-of-order application.
|