Merge pull request #307921 from dominicbetts/aio-opcua-browse-path

AIO: Resolve dynamic OPC UA node Ids

Author: prmerger-automator[bot]

articles/iot-operations/discover-manage-assets/howto-configure-opc-ua.md

@@ -158,6 +158,8 @@ A dataset defines where the connector sends the data it collects from a collecti
 
     :::image type="content" source="media/howto-configure-opc-ua/create-dataset.png" alt-text="Screenshot that shows how to create a dataset in the operations experience." lightbox="media/howto-configure-opc-ua/create-dataset.png":::
 
+    Use the **Start instance** field to specify the starting node for resolving relative browse paths for data points in the dataset. For more information, see [Resolve nodes dynamically using browse paths](overview-opc-ua-connector.md#resolve-nodes-dynamically-using-browse-paths).
+
 1. Select **Create and next** to create the dataset.
 
 > [!TIP]
@@ -188,6 +190,9 @@ Now you can define the data points associated with the dataset. To add OPC UA da
     | ns=3;s=FastUInt10 | Temperature |
     | ns=3;s=FastUInt100 | Humidity |
 
+    > [!NOTE]
+    > If you're using relative browse paths to resolve dynamic nodes, the **Data source** field contains a relative browse path. For more information, see [Resolve nodes dynamically using browse paths](overview-opc-ua-connector.md#resolve-nodes-dynamically-using-browse-paths).
+
 1. On the **data points** page, select **Next** to go to the **Add events** page.
 
 # [Azure CLI](#tab/cli)
@@ -250,6 +255,9 @@ Now you can define the events associated with the asset. To add OPC UA events:
 
     :::image type="content" source="media/howto-configure-opc-ua/add-event.png" alt-text="Screenshot that shows adding events in the operations experience." lightbox="media/howto-configure-opc-ua/add-event.png":::
 
+    > [!NOTE]
+    > To resolve node IDs dynamically, use the **Start instance** field to specify the starting node ID, and the **Data source** field to specify the relative browse path. For more information, see [Resolve nodes dynamically using browse paths](overview-opc-ua-connector.md#resolve-nodes-dynamically-using-browse-paths).
+
 1. Select **Manage default settings** to configure default event settings for the asset. These settings apply to all the OPC UA events that belong to the asset. You can override these settings for each event that you add. Default event settings include:
 
     - **Publishing interval (milliseconds)**: The rate at which OPC UA server should publish data.

articles/iot-operations/discover-manage-assets/overview-opc-ua-connector-certificates-management.md

@@ -55,7 +55,7 @@ By default, the connector for OPC UA connects to an OPC UA server by using the e
 - Export the public key of the connector for OPC UA application instance certificate from the Kubernetes secret store and then add it to trusted certificates list for the OPC UA server.
 - Export the public key of the OPC UA server's application instance and then add it to trusted certificates list for the connector for OPC UA.
 
-Mutual trust validation between the OPC UA server and the connector for OPC UA is now possible. You can now configure an `AssetEndpointProfile` for the OPC UA server in the operations experience web UI and start working with it.
+Mutual trust validation between the OPC UA server and the connector for OPC UA is now possible. You can now configure a *device* for the OPC UA server in the operations experience web UI and start working with it.
 
 ## Use self-signed OPC UA server application instance certificates
 

articles/iot-operations/discover-manage-assets/overview-opc-ua-connector.md

@@ -37,7 +37,7 @@ As part of Azure IoT Operations, the connector for OPC UA is a native Kubernetes
 
 The connector for OPC UA supports the following features as part of Azure IoT Operations:
 
-- Simultaneous connections to multiple OPC UA servers configured by using Kubernetes `AssetEndpointProfile` custom resources (CRs).
+- Simultaneous connections to multiple OPC UA servers configured by using Kubernetes `device` custom resources (CRs).
 - Publish OPC UA data value changes in OPC UA PubSub format with JSON encoding.
 - Publish message headers as user properties in the MQTT message. The headers in the messages published by the connector for OPC UA are based on the [CloudEvents specification for OPC UA](https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/opcua.md).
 - Publish OPC UA events with predefined event fields.
@@ -47,7 +47,8 @@ The connector for OPC UA supports the following features as part of Azure IoT Op
 - Integrated [OpenTelemetry](https://opentelemetry.io/) compatible observability.
 - OPC UA transport encryption.
 - Anonymous authentication and authorization based on username and password.
-- `AssetEndpointProfile` and `Asset` CRs configurable by using Azure REST API and the operations experience web UI.
+- `device` and `asset` CRs configurable by using Azure REST API and the operations experience web UI.
+- Dynamic resolution of nodes at runtime using the OPC UA `TranslateBrowsePathToNodeId` service.
 
 ## How it works
 
@@ -73,7 +74,7 @@ To write values to a node in a connected OPC UA server, the connector for OPC UA
 
 1. Checks the payload to ensure all data points exist in the target dataset.
 
-1. Writes the values to the OPC UA server, and publishes a success or failure response to the MQTT broker. The changed value is published to the standard telemetry topic associated with the dataset.
+1. Writes the values to the OPC UA server, and publishes a success or failure response to the MQTT broker. The changed value is published to the standard message topic associated with the dataset.
 
 To generate a write request, publish a JSON message to the MQTT topic using MQTT v5 request/response semantics. Specify the dataset name and the values to be written in the payload. Each MQTT message includes metadata that defines system-level and user-defined properties such as `SourceId`, `ProtocolVersion`, and `CorrelationData` to ensure traceability and conformance.
 
@@ -148,6 +149,38 @@ The subject field contains the name of the asset that the message is related to.
 > [!NOTE]
 > For assets created in the operations experience web UI, the subject property for any messages sent by the asset is set to the `externalAssetId` value. In this case, the `subject` property contains a GUID rather than a friendly asset name.
 
+## Resolve nodes dynamically using browse paths
+
+When you configure OPC UA data points or events in an asset, you typically add an OPC UA server node ID in the **Data source** field. This approach assumes that node IDs are stable across server restarts and deployments. However, some OPC UA servers create node IDs dynamically at runtime or on demand. You can't persist these dynamic node IDs in an asset configuration because they might change over time.
+
+To address this scenario, the connector can resolve dynamic nodes at runtime using the OPC UA `TranslateBrowsePathToNodeId` service. This service resolves a target node ID from a starting object and a relative browse path. When you configure a **Start instance** value in a dataset or event configuration, each data point or event requires a valid relative browse path in its **Data source** property. The connector translates the relative browse path to a concrete node ID at runtime.
+
+> [!NOTE]
+> If you don't provide a **Start instance** value, the connector uses the **Data source** property as a fixed node ID.
+
+Example **Start instance** values:
+
+* `i=2555`
+* `nsu=http://microsoft.com/Opc/OpcPlc/;s=FastUInt1`
+* `nsu=http://microsoft.com/Opc/OpcPlc/Boiler;i=5`
+* `ns=10;s=System.Pump1`
+* `ns=1;b=M/RbKBsRVkePCePcx24oRA==`
+
+Example relative browse paths to use in the **Data source** field:
+
+* `/1:SYSTEM/1:PUMP/1:P1`
+* `/2:Block&.Output`
+* `/3:Truck.0:NodeVersion`
+* `<!HasChild>Truck`
+* `<1:ConnectedTo>1:Boiler/`
+
+For more information about the relative browse path syntax, see [OPC Foundation Part 4 A.2](https://reference.opcfoundation.org/Core/Part4/v105/docs/A.2).
+
+The relative browse paths must use numeric OPC UA namespace indexes. There's currently no support for namespace names in string format.
+
+> [!IMPORTANT]
+> Namespace indexes can change within the server. If namespace indexes change, you must reconfigure them in the asset definition.
+
 ## How does it relate to Azure IoT Operations?
 
 The connector for ONVIF is part of Azure IoT Operations. The connector deploys to an Arc-enabled Kubernetes cluster on the edge as part of an Azure IoT Operations deployment. The connector interacts with other Azure IoT Operations elements, such as:

articles/iot-operations/troubleshoot/tips-tools.md

@@ -203,7 +203,7 @@ To view custom resource types other that pods in the cluster:
 
 1. Press **Ctrl-a** to display the list of custom resource types.
 
-1. Select the custom resource type, such as **assetendpointprofiles** and press **Enter**.
+1. Select the custom resource type, such as **devices** and press **Enter**.
 
     > [!TIP]
     > To search for a custom resource type by name, type **/** and then start typing the name of the type you're looking for.