3 articles

Author: v-thepet

articles/iot-hub-device-update/import-concepts.md

@@ -1,23 +1,23 @@
 ---
-title: Understand Device Update for IoT Hub importing
-description: Key concepts for importing a new update into Device Update for IoT Hub.
+title: Azure Device Update for IoT Hub import manifest
+description: Understand the important concepts and sections in the Azure Device Update for IoT Hub import manifest.
 author: andrewbrownmsft
 ms.author: andbrown
-ms.date: 06/27/2022
+ms.date: 12/31/2024
 ms.topic: concept-article
 ms.service: azure-iot-hub
 ms.subservice: device-update
 ---
 
-# Importing updates into Device Update for IoT Hub
+# Azure Device Update for IoT Hub import manifest
 
-In order to deploy an update to devices from Device Update for IoT Hub, you first have to import that update into the Device Update service. The imported update will be stored in the Device Update service and can be deployed from there to devices. This article provides an overview of some important concepts to understand when it comes to importing updates.
+To deploy an update to devices using Azure Device Update for IoT Hub, you first import the update into the Device Update service, which stores the imported update and deploys it to devices. Along with the update payload, you submit a JSON import manifest file that defines important information about the update. This article describes the important concepts and sections in the import manifest JSON file.
 
-## Import manifest
+## The import manifest file
 
-An import manifest is a JSON file that defines important information about the update that you're importing. You submit both your import manifest and associated update file or files (such as a firmware update package) as part of the import process. The metadata that is defined in the import manifest is used to ingest the update. Some of the metadata is also used at deployment time - for example, to validate if an update was installed correctly.
+You submit a import manifest JSON file along with the associated update files, such as a firmware update package, as part of the import process. The metadata defined in the import manifest is used both to ingest the update and at deployment time for functions like validating whether the update installed correctly.
 
-For example:
+The following JSON code shows an example import manifest file:
 
 ```json
 {
@@ -60,15 +60,15 @@ For example:
 }
 ```
 
-The import manifest contains several items that represent important Device Update for IoT Hub concepts. These items are outlined in this section. For information about the full import schema, see [Import manifest JSON schema](./import-schema.md).
+The sections of the import manifest file represent important Device Update concepts, as described in the following sections. For information about the full import manifest schema, see [Import manifest JSON schema](./import-schema.md).
 
 ### Update identity
 
-The *update identity* or *updateId* is the unique identifier for an update in Device Update for IoT Hub. It's composed of three parts:
+The *update identity* or `updateId` provides the unique identifier for an update in Device Update, and contains the following properties:
 
-- **Provider**: entity who is creating or directly responsible for the update. It will often be a company name.
-- **Name**: identifier for a class of updates. It will often be a device class or model name.
-- **Version**: a version number distinguishing this update from others that have the same provider and name.
+- `provider` is the entity that creates or is responsible for the update, often a company name.
+- `name` identifies an update class, often a device class or model name.
+- `version` is a number that distinguishes this update from others with the same provider and name.
 
 For example:
 
@@ -83,13 +83,13 @@ For example:
 ```
 
 > [!NOTE]
-> UpdateId is used by the Device Update service only, and may be different from the identities of actual software components on the device.
+> The `updateId` is used only by the Device Update service, and might be different from the software component identities on the devices.
 
 ### Compatibility
 
-*Compatibility* defines the criteria of a device that can install the update. It contains device properties that are a set of arbitrary key value pairs that are reported from a device. Only devices with matching properties will be eligible for deployment. An update may be compatible with multiple device classes by having more than one set of device properties.
+The `compatibility` section defines the devices that can install an update by using one or more arbitrary key-value pairs. Only devices that report properties matching the `compatibility` values are eligible to deploy the update. You can make an update compatible with multiple device classes by including more than one set of device compatibility properties.
 
-Here's an example of an update that can only be deployed to a device that reports *Contoso* and *Toaster* as its device manufacturer and model.
+The following example shows an update that can only be deployed to devices that report *Contoso* and *Toaster* as their device manufacturer and model.
 
 ```json
 {
@@ -104,7 +104,7 @@ Here's an example of an update that can only be deployed to a device that report
 
 ### Instructions
 
-The *Instructions* part contains the necessary information or *steps* for device agent to install the update. The simplest update contains a single inline step. That step executes the included payload file using a *handler* registered with the device agent:
+The `instructions` section contains the necessary information or `steps` for the device agent to install the update. The simplest update contains a single inline step that executes the update payload file using a `handler` registered with the device agent. The following example shows a single-step `instructions` section.
 
 ```json
 {
@@ -121,10 +121,10 @@ The *Instructions* part contains the necessary information or *steps* for device
 }
 ```
 
-> [!TIP]
-> `handler` is equivalent to `updateType` in import manifest version 3.0 or older.
+> [!NOTE]
+> The `handler` property is equivalent to the `updateType` property in import manifest version 3.0 or older.
 
-An update may contain more than one step:
+An update and an import manifest `steps` section can contain more than one step, as in the following example:
 
 ```json
 {
@@ -152,7 +152,7 @@ An update may contain more than one step:
 }
 ```
 
-An update may contain *reference* steps that instruct the device agent to install another update with its own import manifest altogether, establishing a parent and child update relationship. For example, an update for a toaster may contain two child updates:
+An update and `steps` section can also contain `reference` steps that instruct the device agent to install a different update along with its own import manifest, establishing a parent and child update relationship. The following example update for a toaster contains two child update steps. An update can contain any combination of inline and reference steps.
 
 ```json
 {
@@ -179,31 +179,30 @@ An update may contain *reference* steps that instruct the device agent to instal
 }
 ```
 
-> [!NOTE]
-> An update may contain any combination of inline and reference steps.
 
 ### Files
 
-The *Files* part contains the metadata of update payload files like their names, sizes, and hash. Device Update for IoT Hub uses this metadata for integrity validation during the import process. The same information is then forwarded to the device agent to repeat the integrity validation prior to installation.
+The `files` section of the import manifest contains update payload file metadata like `name`, `size`, and `hash`. Device Update uses this metadata for integrity validation during the import process, and forwards the same information to the device agent for integrity validation before installation.
 
 > [!NOTE]
-> An update that contains only reference steps won't have any update payload file in the parent update.
+> A parent update that contains only reference steps doesn't define any update payload files.
 
 ## Create an import manifest
 
-While it's possible to author an import manifest JSON manually using a text editor, the Azure Command Line Interface (CLI) simplifies the process greatly. When you're ready to try out the creation of an import manifest, you can use the [How-to guide](create-update.md#create-a-basic-device-update-import-manifest).
+Once you understand the structure of an import manifest, create an import manifest to describe your update. You can author a JSON import manifest manually using a text editor, but the Azure CLI [az iot du init v5](/cli/azure/iot/du/update/init#az-iot-du-update-init-v5) command simplifies the process. For more information and instructions, see [Prepare an update to import into Device Update](create-update.md).
 
 > [!IMPORTANT]
-> An import manifest JSON filename must end with `.importmanifest.json` when imported through Azure portal.
+> To import into the Azure portal, an import manifest JSON filename must end with *.importmanifest.json*.
 
 > [!TIP]
-> Use [Visual Studio Code](https://code.visualstudio.com) to enable autocomplete and JSON schema validation when creating an import manifest.
+> You can use [Visual Studio Code](https://code.visualstudio.com) to enable autocomplete and JSON schema validation when you create an import manifest.
 
-## Limits on importing updates
+## Update import limits
 
-Certain limits are enforced for each Device Update for IoT Hub instance. If you haven't already reviewed them, see [Device Update limits](./device-update-limits.md).
+Certain limits are enforced for Device Update instances, including import limits. For more information, see [Device Update limits](./device-update-limits.md).
 
-## Next steps
+## Related content
 
-- To learn more about the import process, see [Prepare an update to import](./create-update.md).
-- Review the [Import manifest schema](./import-schema.md).
+- [Import manifest schema](import-schema.md).
+- [Prepare an update to import](create-update.md).
+- [Import an update](import-update.md)