Device management and interaction
After you have registered your devices as IoT devices, readings from those devices are captured and communicated back to Azure IoT Hub. When a device raises an exception, it's sent back to Dynamics 365 as an alert. For example, consider a scenario where your organization manages smart trash bins. The trash bin constantly sends trash level readings to IoT Hub. When a reading that is outside a defined range is detected, an alert needs to be raised. Then, an IoT alert record is created in Dynamics 365 through an automation such as a Power Automate flow or an app from Logic Apps.
Frequently, when the system has received an IoT alert, its first step is to attempt remotely interacting with the device and to potentially send commands to the device. Several record types are available for you to use to remotely manage and interact with these devices.
Key record types that you can use for device management and interaction include:
Device category - Use this record type to group multiple devices by the type of device. You can use device categories for reporting purposes, management, and simplifying device interactions. For example, you might create temperature and humidity categories to separate temperature-related IoT devices or commands from humidity-focused IoT devices or commands.
Command - These record types represent the actual action or command that should be run against a specific IoT device. They typically consist of different JSON properties that are passed to the device that does something to the device. For example, if you want to set the temperature and humidity of a device to specific values, you would pass the following JSON script to the device by using a command record.
{"CommandName":"Set Values","Parameters":{"Reading":{"Temperature":"60","Humidity":"40"}}}Command definition - This record type represents a predefined command that you can add to a command record. It contains multiple preconfigured properties that you can modify to the process of sending to devices. After you have created a command, you can select a command definition. Properties in the definition are populated with default values, but you can override those values. For example, you could create a command definition called set values. In the command definition, you could predefine the parameters, such as reading, temperature, and humidity. When you select the command definition, it auto populates the command, and you can manually change parameters as needed.
Property definition - Use this record type to define the specific properties that are available and can be passed as part of a command definition. For example, if you created the set values command definition (as discussed previously), each parameter, such as reading, temperature, and humidity, would have a property definition defined for them that was associated with the set values command definition.
Command definitions
Periodically, you have several IoT devices that do the same thing or have similar properties that are reported back and potentially need to be interacted with. While generated IoT alerts are device-specific, common properties often exist between devices that need to be interacted with. Each command specifies which of those different properties are being used for that specific device. For example, consider a scenario where you want to send a message back to a device that lets the device know (or the display on the device) that a technician was dispatched to resolve the issue. Whenever this situation occurs, you would need to create a command in Connected Customer Service that includes the following JSON message:
{"CommandName":"Notification","Parameters":{"Message":"Technician has been dispatched"}}
The preceding example contains three specific components that are being sent to the device as part of the message:
CommandName - This component represents the name of the command that is being set to the device. In the preceding command, the command name is Notification.
Parameters - Use this component to declare the specific properties that are being interacted with as part of the command. These parameters include all properties that the command is interacting with. In the preceding command, everything that follows "Parameters" (in this case, "Message") represents properties that are being interacted with as part of this command.
Property - Represents the specific property to be interacted with and the value that should be pushed to the property. Properties are typically defined as name/value pairs. For example, “Message” represents the message property that you can use to send a message to the device. The “Technician has been dispatched” value is being passed to the "Message" property.
While you can manually define the JSON for each command by using the format that is defined in the preceding section, the reality is that you're likely defining multiple commands that are basically doing the same thing. This situation is when using a command definition is beneficial. Essentially, a command definition is a wrapper that predefines the command name and parameters that you want to use in a command. By predefining parameters that are set in a specific command, you help save time for users and/or automation processes. Because they only need to modify the property values that are relevant to what the command is trying to do. When a command is created, the user/process can select the command definition that they want to use.
The following image represents a command definition named Notification that automatically generates the same JSON from the original example.
You can associate each defined command definition with one or more property definition(s). A property definition represents a specific parameter that is being used as part of a command. Parameters that are defined for a command definition are auto populated with default values that were defined for the specific property definition that is being used. Those values can be used as is overwritten at the time that the actual command is created.
Property definitions
Property definitions help simplify your task of predefining specific properties that are associated with IoT devices.
A property definition contains the following information:
Name - The name of the specific property. In the previous example, Message would be set as the name because it's the property that you want to define.
Type - Defines the type of property.
Parent Property - Specifies that the property is a child property of another.
Editable - Specifies if the property is editable when you use it in a command definition.
Visible - Specifies if the property is hidden and shouldn't be shown in the command definition.
Additional Properties - Extra items that are specific to the property type that you can define, such as a default text string that you use with a Message property.
The following table describes six different types of property definitions that you can choose from.
| Type | Description | Other properties and examples |
|---|---|---|
| String | Use when the value that you want to pass to a property is a text-based value. | Max length and default value. Example - A message property would use the string type because the contents of the message are text. |
| Date and Time | Use when the value to pass to a property is date and/or time-based. | Minimum and maximum values. |
| Boolean | Use when you want to pass one of two possible values to a property. | Display name for true, display name for false, and default value. |
| Whole Number | Use when you want to pass a whole number to the property. | Minimum, maximum, and default value. |
| Decimal Number | Use when you want to pass a decimal number to the property. | Minimum, maximum, default value, and decimal position. |
| Object | Use when the item that you want to pass is an object. | Example - A reading property might contain a temperature and a humidity property. By setting the reading property to a type of Object, you can define specific sub properties for it. |
Use property definitions in command definitions
When you examine the data that is being sent as part of an IoT alert, or if you're sending a remote command to a device, several properties are associated with the alert data or the message to be sent. The properties represent a name/value pair that displays or provides relevant parameters that are related to the event, for example:
A temperature-related IoT device alert might include the device ID, type of reading, the actual reading, or the threshold that was exceeded.
A command that you're returning to an IoT device might include the message to be sent or a specific value that you want to set a property to.
You can use command definitions to create predefined commands that have the specific parameters that you want to work with. To complete this task, create property definitions and then associate those property definitions with specific command definitions. A property definition defines specific details about the property that is being passed to the command, as shown in the following example command:
{"CommandName":"Notification","Parameters":{"Message":"Technician has been dispatched"}}
The parameters are specific properties that you want to include in the command. The Message property indicates that you want to send a message to the device, and the text is the message that you want to include in the message. The message property in the preceding command is good example of where to use property definitions.
Work with parent properties
Frequently, a property has multiple sub properties that make up the entire property definition. In this case, you can use parent properties to relate a property to multiple sub properties.
The following command is an example reading that would be considered the parent property for temperature and humidity.
{"CommandName":"Set Values","Parameters":{"Reading":{"Temperature":"30","Humidity":"30"}}}
In this command, you would set the Reading type to Object. This setting indicates that the Reading property should be considered an object and it might contain other properties that make up the overall value. The Temperature and Humidity property definitions would have the Reading property definition set as the parent property.
| Parameter name | Type | Parent property |
|---|---|---|
| Reading | Object | None |
| Temperature | Text | Reading |
| Humidity | Text | Reading |
When you create a command definition that needs to use the Reading property, you only need to include a reference to the Reading property definition. Because Reading has a type of Object, and both Temperature and Humidity have Reading as the parent property, it ensures that when the Reading property is used, both Temperature and Humidity properties are also included.
Command definitions help simplify your task of streamlining the process of building commands to send to devices. Additionally, property definitions help make it easier for you to use Power Automate to identify and manipulate specific values that you want to pass in a command.
Device categories
As mentioned previously, device categories are used to help organize and manage devices. Based on your organizational needs you can categorize devices different ways. For example, you might categorize devices by the commands they support, the type of device, or by devices that break down more often.
Once you have defined a device category, you can specify details related to the category that can make device management for devices assigned to this category easier. For example, you might create a device category called temperature. You could then specify temperature related commands to be available.
Device categories are created in the Customer Service admin center app. They're available by go to Miscellaneous and choosing Manage next to Device categories.
Once you have created and saved a device category, you can specify:
Devices: Specifies which IoT Devices are associated with this category.
Command Definitions: Specifies the command definitions that can be sent to devices of this category.
Device Properties: Specifies which property definitions are displayed for devices assigned to this category.
Device Tags: Specifies which property definitions are used as device tags and displayed for devices assigned to this category.
To learn more about device categories, see Device categories.