Merge pull request #112636 from dominicbetts/central-template-versioning

Refresh template versioning article

Author: megvanhuygen

articles/iot-central/core/howto-version-device-template.md

@@ -3,7 +3,7 @@ title: Understanding device template versioning for your Azure IoT Central apps
 description: Iterate over your device templates by creating new versions and without impacting your live connected devices
 author: sarahhubbard
 ms.author: sahubbar
-ms.date: 12/09/2019
+ms.date: 04/24/2020
 ms.topic: how-to
 ms.service: iot-central
 services: iot-central
@@ -14,58 +14,111 @@ manager: peterpr
 
 *This article applies to solution builders and device developers.*
 
-Azure IoT Central allows rapid development of IoT Applications. You can quickly iterate over your device template designs by adding, editing, or deleting device capabilities, views, and customizations. Once you have published your device template, the device capability model shows as **Published** with lock icons next to the model. In order to make changes to the device capability model, you will need to create a new version of the device template. Meanwhile the cloud properties, customizations, and views can all be edited at any time without needing to version the device template. Once you have saved any of these changes, you can publish the device template to make the latest changes available for the operator to view in Device Explorer.
+A device template includes a schema that describes how a device interacts with IoT Central. These interactions include telemetry, properties, and commands. Both the device and the IoT Central application rely on a shared understanding of this schema to exchange information. You can only make limited changes to the schema without breaking the contract, that's why most schema changes require a new version of the device template. Versioning the device template lets older devices continue with the schema version they understand, while newer or updated devices use a later schema version.
+
+The schema in a device template is defined in the device capability model (DCM) and its interfaces. Device templates include other information, such as cloud properties, display customizations, and views. If you make changes to those parts of the device template that don't define how the device exchanges data with IoT Central, you don't need to version the template.
+
+You must publish any device template changes, whether or not they require a version update, before an operator can use it. IoT Central stops you from publishing breaking changes to a device template without first versioning the template.
 
 > [!NOTE]
 > To learn more about how to create a device template see [Set up and manage a device template](howto-set-up-template.md)
 
-## Add customizations to the device template without versioning
+## Versioning rules
+
+This section summarizes the versioning rules that apply to device templates. Both DCMs and interfaces have version numbers. The following snippet shows the DCM for an environmental sensor device. The DCM has two interfaces: **DeviceInformation** and **EnvironmentalSensor**. You can see the version numbers at the end of the`@id` fields. To view this information in the IoT Central UI, select **View identity** in the device template editor.
+
+```json
+{
+  "@id": "urn:contoso:sample_device:1",
+  "@type": "CapabilityModel",
+  "implements": [
+    {
+      "@id": "urn:contoso:sample_device:deviceinfo:1",
+      "@type": "InterfaceInstance",
+      "name": "deviceinfo",
+      "schema": {
+        "@id": "urn:azureiot:DeviceManagement:DeviceInformation:1",
+        "@type": "Interface",
+        "displayName": {
+          "en": "Device Information"
+        },
+        "contents": [...
+        ]
+      }
+    },
+    {
+      "@id": "urn:contoso:sample_device:sensor:1",
+      "@type": "InterfaceInstance",
+      "name": "sensor",
+      "schema": {
+        "@id": "urn:contoso:EnvironmentalSensor:2",
+        "@type": "Interface",
+        "displayName": {
+          "en": "Environmental Sensor"
+        },
+        "contents": [...
+        ]
+      }
+    }
+  ],
+  "displayName": {
+    "en": "Environment Sensor Capability Model"
+  },
+  "@context": [
+    "http://azureiot.com/v1/contexts/IoTModel.json"
+  ]
+}
+```
+
+* After a DCM is published, you can't remove any interfaces, even in a new version of the device template.
+* After a DCM is published, you can add an interface if you create a new version of the device template.
+* After a DCM is published, you can replace an interface with a newer version if you create a new version of the device template. For example, if the sensor v1 device template uses the EnvironmentalSensor v1 interface, you can create a sensor v2 device template that uses the EnvironmentalSensor v2 interface.
+* After an interface is published, you can't remove any of the interface contents, even in a new version of the device template.
+* After an interface is published, you can add items to the contents of an interface if you create a new version of the interface and device template. Items that you can add to the interface include telemetry, properties, and commands.
+* After an interface is published, you can make non-schema changes to existing items in the interface if you create a new version of the interface and device template. Non-schema parts of an interface item include the display name and the semantic type. The schema parts of an interface item that you can't change are name, capability type, and schema.
+
+The following sections walk you through some examples of modifying device templates in IoT Central.
+
+## Customize the device template without versioning
 
 Certain elements of your device capabilities can be edited without needing to version your device template and interfaces. For example, some of these fields include display name, semantic type, minimum value, maximum value, decimal places, color, unit, display unit, comment, and description. To add one of these customizations:
 
 1. Go to the **Device Templates** page.
 1. Select the device template you wish to customize.
 1. Choose the **Customize** tab.
-1. All of the capabilities defined in your device capability model will be listed here. All of the fields you can edit here can be saved and used across your application, without needing to version your device template. If there are fields you wish to edit that are read-only, you will need to version your device template to change these. Select a field you wish to edit and enter in any new values.
-1. Click **Save**. Now these values will override anything that was initially saved in your device template and will be used across the application.
+1. All the capabilities defined in your device capability model are listed here. You can edit, save, and use all of these fields without the need to version your device template. If there are fields you wish to edit that are read-only, you must version your device template to change them. Select a field you wish to edit and enter in any new values.
+1. Click **Save**. Now these values override anything that was initially saved in your device template and are used across the application.
 
-## Versioning a device template
+## Version a device template
 
-Creating a new version of your device template will create a draft version of the template where the device capability model can be edited. Any published interfaces will remain published until they are individually versioned. In order to modify a published interface, you must first create a new device template version.
+Creating a new version of your device template creates a draft version of the template where the device capability model can be edited. Any published interfaces remain published until they're individually versioned. To modify a published interface, first create a new device template version.
 
-The device template should only be versioned when you are trying to edit a part of the device capability model that you can not edit in the customizations section of the device template. 
+Only version the device template when you're trying to edit a part of the device capability model that you can't edit in the customizations section.
 
-In order to version a device template:
+To version a device template:
 
 1. Go to the **Device Templates** page.
-1. Select the device template you are trying to version.
-1. Click the **Version** button at the top of the page and give the template a new name. We have suggested a new name for you which can be edited.
+1. Select the device template you're trying to version.
+1. Click the **Version** button at the top of the page and give the template a new name. IoT Central suggests a new name, which you can edit.
 1. Click **Create**.
-1. Now your device template is in draft mode. You will see your interfaces are still locked and must be individually versioned to be edited. 
+1. Now your device template is in draft mode. You can see your interfaces are still locked. Version any interfaces you want to modify.
 
-### Versioning an interface
+## Version an interface
 
-Versioning an interface allows you to add, update, and remove the capabilities inside the interface you had already created. 
+Versioning an interface allows you to add, update, and remove the capabilities inside the interface you had already created.
 
-In order to version an interface:
+To version an interface:
 
 1. Go to the **Device Templates** page.
 1. Select the device template you have in a draft mode.
 1. Select the interface that is in published mode that you wish to version and edit.
-1. Click the **Version** button at the top of the interface page. 
+1. Click the **Version** button at the top of the interface page.
 1. Click **Create**.
-1. Now your interface is in draft mode. You will be able to add or edit capabilities to your interface without breaking existing customizations and views. 
-
-> [!NOTE]
-> Standard interfaces published by Azure IoT can not be versioned or edited. These standard interfaces are used for device certification.
-
-> [!NOTE]
-> Once the interface has been published, you can not delete any of it's capabilities even in a draft mode. Capabilities can only be edited or added to the interface in draft mode.
+1. Now your interface is in draft mode. You can add or edit capabilities to your interface without breaking existing customizations and views.
 
+## Migrate a device across versions
 
-## Migrate a device across device template versions
-
-You can create multiple versions of the device template. Over time, you will have multiple connected devices using these device templates. You can migrate devices from one version of your device template to another. The following steps describe how to migrate a device:
+You can create multiple versions of the device template. Over time, you'll have multiple connected devices using these device templates. You can migrate devices from one version of your device template to another. The following steps describe how to migrate a device:
 
 1. Go to the **Device Explorer** page.
 1. Select the device you need to migrate to another version.
@@ -76,4 +129,6 @@ You can create multiple versions of the device template. Over time, you will hav
 
 ## Next steps
 
+If you're an operator or solution builder, a suggested next step is to learn [how to manage your devices](./howto-manage-devices.md).
+
 If you're a device developer, a suggested next step is to read about [Azure IoT Edge devices and Azure IoT Central](./concepts-iot-edge.md).