Merge pull request #204951 from JimacoMS4/update-custom-allocation-topics-dps

Refactor custom allocation topics

Author: 19BMG00

.openpublishing.redirection.json

@@ -29139,6 +29139,11 @@
             "redirect_url": "/azure/iot-dps/quick-enroll-device-tpm",
             "redirect_document_id": false
         },
+        {
+            "source_path_from_root": "/articles/iot-dps/how-to-use-custom-allocation-policies.md",
+            "redirect_url": "/azure/iot-dps/tutorial-custom-allocation-policies",
+            "redirect_document_id": false
+          },          
         {
             "source_path_from_root": "/articles/app-service/environment/app-service-app-service-environment-web-application-firewall.md",
             "redirect_url": "/azure/app-service/environment/integrate-with-application-gateway",

articles/iot-dps/concepts-custom-allocation.md

@@ -58,7 +58,7 @@ Depending on the scenario, a device could send a request to a provisioning servi
 * **Never re-provision**: The device is never reassigned to a different hub. This policy is provided for managing backwards compatibility.
 
 > [!NOTE]
-> DPS will always call the custom allocation webhook regardless of re-provisioning policy in case there is new [ReturnData](how-to-send-additional-data.md) for the device. If the re-provisioning policy is set to **never re-provision**, the webhook will be called but the device will not change its assigned hub.
+> DPS will always call the custom allocation webhook regardless of re-provisioning policy in case there is new [ReturnData](concepts-custom-allocation.md#use-device-payloads-in-custom-allocation) for the device. If the re-provisioning policy is set to **never re-provision**, the webhook will be called but the device will not change its assigned hub.
 
 When designing your solution and defining a reprovisioning logic there are a few things to consider. For example:
 

articles/iot-dps/concepts-device-reprovision.md

@@ -40,7 +40,7 @@ The service-level setting that determines how Device Provisioning Service assign
 
 * **Static configuration via the enrollment list**: specification of the desired IoT hub in the enrollment list takes priority over the service-level allocation policy.
 
-* **Custom (Use Azure Function)**: A [custom allocation policy](how-to-use-custom-allocation-policies.md) gives you more control over how devices are assigned to an IoT hub. This is accomplished by using custom code in an Azure Function to assign devices to an IoT hub. The device provisioning service calls your Azure Function code providing all relevant information about the device and the enrollment to your code. Your function code is executed and returns the IoT hub information used to provisioning the device.
+* **Custom (Use Azure Function)**: A [custom allocation policy](concepts-custom-allocation.md) gives you more control over how devices are assigned to an IoT hub. This is accomplished by using custom code in an Azure Function to assign devices to an IoT hub. The device provisioning service calls your Azure Function code providing all relevant information about the device and the enrollment to your code. Your function code is executed and returns the IoT hub information used to provisioning the device.
 
 ## Enrollment
 

articles/iot-dps/concepts-service.md

@@ -35,11 +35,11 @@ sections:
       - question: |
          How does the health of an IoT hub affect device provisioning? 
         answer: |
-         Currently DPS doesn't check the health of an IoT hub before assigning devices. DPS will continue to try to assign devices to an IoT hub that is down based on its configured allocation policy. For example, if the configured allocation policy is *Lowest latency* and DPS has a linked IoT hub in region A (hub A) and one in region B (hub B), it will assign a device trying to provision from region A to hub A, even if hub A is down. To factor in IoT hub health when provisioning devices, you can implement a custom allocation policy with your own monitoring logic based on [IoT Hub diagnostics](../iot-hub/monitor-iot-hub.md) or your own user-defined metrics. To learn more about custom allocation policies, see [How to use custom allocation policies](how-to-use-custom-allocation-policies.md).
+         Currently DPS doesn't check the health of an IoT hub before assigning devices. DPS will continue to try to assign devices to an IoT hub that is down based on its configured allocation policy. For example, if the configured allocation policy is *Lowest latency* and DPS has a linked IoT hub in region A (hub A) and one in region B (hub B), it will assign a device trying to provision from region A to hub A, even if hub A is down. To factor in IoT hub health when provisioning devices, you can implement a custom allocation policy with your own monitoring logic based on [IoT Hub diagnostics](../iot-hub/monitor-iot-hub.md) or your own user-defined metrics. To learn more about custom allocation policies, see [Understand custom allocation policies](concepts-custom-allocation.md).
       - question: |
          Can multiple DPS instances provision devices to the same IoT hub? 
         answer: |
-         Yes; however, built-in allocation policies apply to each DPS instance individually, so load balancing across multiple IoT hubs is not possible when using the built-in DPS policies. Instead, you can use a custom allocation policy to implement load balancing when using multiple DPS instances. To learn more about custom allocation policies, see [How to use custom allocation policies](how-to-use-custom-allocation-policies.md).
+         Yes; however, built-in allocation policies apply to each DPS instance individually, so load balancing across multiple IoT hubs is not possible when using the built-in DPS policies. Instead, you can use a custom allocation policy to implement load balancing when using multiple DPS instances. To learn more about custom allocation policies, see [Understand custom allocation policies](concepts-custom-allocation.md).
       - question: |
          How can I get an authorization token to use for REST service operations? 
         answer: |

articles/iot-dps/dps-faq.yml

@@ -3,61 +3,71 @@ title: How to transfer a payload between device and Azure Device Provisioning Se
 description: This document describes how to transfer a payload between device and Device Provisioning Service (DPS)
 author: kgremban
 ms.author: kgremban
-ms.date: 12/03/2021
+ms.date: 09/21/2022
 ms.topic: conceptual
 ms.service: iot-dps
 services: iot-dps
 ---
 
 # How to transfer payloads between devices and DPS
 
-Sometimes DPS needs more data from devices to properly provision them to the right IoT Hub, and that data needs to be provided by the device. Vice versa, DPS can return data to the device to facilitate client-side logic.
+Devices that register with DPS are required to provide a registration ID and valid credentials (keys or X.509 certificates) when they register. However, there may be IoT solutions or scenarios in which additional data is needed from the device. For example, a custom allocation policy webhook may use information like a device model number to select an IoT hub to provision the device to. Likewise, a device may require additional data in the registration response to facilitate its client-side logic. DPS provides the capability for devices to both send and receive an optional payload when they register.
 
 ## When to use it
 
-This feature can be used as an enhancement for [custom allocation](./how-to-use-custom-allocation-policies.md). For example, you want to allocate your devices based on the device model without human intervention. In this case, you can configure the device to report its model information as part of the [register device call](/rest/api/iot-dps/device/runtime-registration/register-device). DPS will pass the device’s payload to the custom allocation webhook. Then your function can decide which IoT hub the device will be provisioned to based on the device model information. If needed, the webhook can return data back to the device as a JSON object in the webhook response.  
+Common scenarios for sending optional payloads are:
+
+* [Custom allocation policies](concepts-custom-allocation.md) can use the device payload to help select an IoT hub for a device or set its initial twin. For example, you may want to allocate your devices based on the device model. In this case, you can configure the device to report its model information when it registers. DPS will pass the device’s payload to the custom allocation webhook. Then your webhook can decide which IoT hub the device will be provisioned to based on the device model information. If needed, the webhook can also return data back to the device as a JSON object in the webhook response. To learn more, see [Use device payloads in custom allocation](concepts-custom-allocation.md#use-device-payloads-in-custom-allocation).
+
+* [IoT Plug and Play (PnP)](../iot-develop/overview-iot-plug-and-play.md) devices *may* use the payload to send their model ID when they register with DPS. You can find examples of this usage in the PnP samples in the SDK or sample repositories. For example, [C# PnP thermostat](https://github.com/Azure-Samples/azure-iot-samples-csharp/blob/main/iot-hub/Samples/device/PnpDeviceSamples/Thermostat/Program.cs) or [Node.js PnP temperature controller](https://github.com/Azure/azure-iot-sdk-node/blob/main/device/samples/javascript/pnp_temperature_controller.js).
+
+* [IoT Central](../iot-central/core/overview-iot-central.md) devices that connect through DPS *should* follow [IoT Plug and Play conventions](..//iot-develop/concepts-convention.md) and send their model ID when they register. IoT Central uses the model ID to assign the device to the correct device template. To learn more, see [Device implementation and best practices for IoT Central](../iot-central/core/concepts-device-implementation.md).  
 
 ## Device sends data payload to DPS
 
-When your device is sending a [register device call](/rest/api/iot-dps/device/runtime-registration/register-device) to DPS, The register call can be enhanced to take other fields in the body. The body looks like the following:
+When your device calls [Register Device](/rest/api/iot-dps/device/runtime-registration/register-device) to register with DPS, it can include additional data in the **payload** property. For example, the following JSON shows the body for a request to register using TPM attestation:
 
 ```json
 { 
     "registrationId": "mydevice", 
     "tpm": { 
-        "endorsementKey": "stuff", 
-        "storageRootKey": "things" 
+        "endorsementKey": "xxxx-device-endorsement-key-xxxx", 
+        "storageRootKey": "xxx-device-storage-root-key-xxxx" 
     }, 
     "payload": { A JSON object that contains your additional data } 
 } 
 ```
 
+The **payload** property must be a JSON object and can contain any data relevant to your IoT solution or scenario.
+
 ## DPS returns data to the device
 
-If the custom allocation policy webhook wishes to return some data to the device, it will pass the data back as a JSON object in the webhook response. The change is in the payload section below.
+DPS can return data back to the device in the registration response. Currently, this feature is exclusively used in custom allocation scenarios. If the custom allocation policy webhook needs to return data to the device, it can pass the data back as a JSON object in the webhook response. DPS will then pass that data back in the **registrationState.payload** property in the [Register Device response](/rest/api/iot-dps/device/runtime-registration/register-device#registrationoperationstatus). For example, the following JSON shows the body of a successful response to register using TPM attestation.
 
 ```json
-{ 
-    "iotHubHostName": "sample-iot-hub-1.azure-devices.net", 
-    "initialTwin": { 
-        "tags": { 
-            "tag1": true 
-        }, 
-        "properties": { 
-            "desired": { 
-                "prop1": true 
-            } 
-        } 
-    }, 
-    "payload": { A JSON object that contains the data returned by the webhook } 
-} 
+{
+   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
+   "status":"assigned",
+   "registrationState":{
+      "registrationId":"my-tpm-device",
+      "createdDateTimeUtc":"2022-08-31T22:02:50.5163352Z",
+      "assignedHub":"sample-iot-hub-1.azure-devices.net",
+      "deviceId":"my-tpm-device",
+      "status":"assigned",
+      "substatus":"initialAssignment",
+      "lastUpdatedDateTimeUtc":"2022-08-31T22:02:50.7370676Z",
+      "etag":"xxxx-etag-value-xxxx",
+      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"},
+      "payload": { A JSON object that contains the data returned by the webhook }
+   }
+}
 ```
 
-## SDK support
+The **payload** property must be a JSON object and can contain any data relevant to your IoT solution or scenario.
 
-This feature is available in C, C#, JAVA and Node.js client SDKs. To learn more about the Azure IoT SDKs available for IoT Hub and the IoT Hub Device Provisioning service, see [Microsoft Azure IoT SDKs]( https://github.com/Azure/azure-iot-sdks).
+## SDK support
 
-[IoT Plug and Play (PnP)](../iot-develop/overview-iot-plug-and-play.md) devices use the payload to send their model ID when they register with DPS. You can find examples of this usage in the PnP samples in the SDK or sample repositories. For example, [C# PnP thermostat](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/iothub/device/samples/solutions/PnpDeviceSamples/Thermostat/Program.cs) or [Node.js PnP temperature controller](https://github.com/Azure/azure-iot-sdk-node/blob/main/device/samples/javascript/pnp_temperature_controller.js).
+This feature is available in C, C#, JAVA and Node.js client SDKs. To learn more about the Azure IoT SDKs available for IoT Hub and IoT Hub Device Provisioning service, see [Microsoft Azure IoT SDKs]( https://github.com/Azure/azure-iot-sdks).
 
 ## IoT Edge support
 
@@ -87,4 +97,6 @@ The payload file (in this case `/home/aziot/payload/json`) can contain any valid
 
 ## Next steps
 
-* To learn how to provision devices using a custom allocation policy, see [How to use custom allocation policies](./how-to-use-custom-allocation-policies.md)
+* For an overview of custom allocation policies, see [Understand custom allocation policies](./concepts-custom-allocation.md)
+
+* To learn how to provision devices using a custom allocation policy, see [Use custom allocation policies](./tutorial-custom-allocation-policies.md)