Device attributes and filters
This page explains the concepts of device attributes and filters, and links to tutorials on applying these concepts in Device Management Portal and the APIs.
An attribute is a piece of information related to a device, and consists of a name and value. Devices have two types of attributes:
Built-in attributes: Information the device provides to Device Management, such as manufacturer, serial number and model. You can view this information in Device Management, but Device Management doesn't manage it.
Custom attributes: Information you provide to Device Management (specifically, the Device Directory service). This information is not on the device - the device doesn't provide it and doesn't store it. If you want to use custom attributes on a group of devices, or a large-scale deployment, add these attributes as early as possible.
You can use both attribute types to filter devices.
Built-in attributes are stored on the device, and include, but are not limited to:
Device ID: A name internal to Device Management, and globally unique. This is the only way to reference a device when trying to use the APIs. Device Management automatically generates this ID when the device first connects to the service.
Endpoint name: A name you can give your device in the factory. Because it may not be globally unique, the APIs cannot use it to identify the device.
Tip: If you did not give your device an endpoint name (for example, because you are using a developer certificate rather than a factory process), the system will use the Device ID as the endpoint name.
Serial number: Read only; it is populated from the device's firmware.
Vendor ID: Read only; it is populated from the device's firmware.
Device class: The type ID of the device. The field is read only; it is populated from the device's firmware.
See a full table of all built-in attributes and filter operators. You can also work with custom attributes.
For a full explanation of how you and the Device Management APIs can interact with these attributes, see the Device Directory API documentation.
Custom attributes let you create specific filters, which can make device management and firmware update easier. Without custom attributes, you can filter only based on what's available in Device Directory device data.
Device Management does not provide or limit the types of custom attributes you can add; you can create whichever attributes you need. For example:
- Distinguish between test and deployment devices.
- List the OS full version.
- Indicate factory name.
- Identify device location, such as city or street.
You can assign up to five custom attributes to one device, and up to ten custom attributes to a device group.
Note: Device group custom attributes apply only to the group, and are not passed down to the devices within the group. This is true in both Portal and the APIs.
Custom attributes are stored in Device Directory, not on the device. This means that the client running on the device can't see these attributes on the device itself; if you want the client to be aware of a custom attribute, you need to give the device a Resource with this attribute.
Device filters let you view a set of devices, according to attributes you specify.
A filter consists of an operator (for example,
__eq or is equal to),and at least one attribute.
These requirements are true for Device Management Portal and the APIs.
When you construct a filter, it must be:
- Complete: Partial fields will return no results.
- Exact: If you misspell a value, either when assigning it to an attribute or creating a filter, the filter will not include the applicable device. Filters are also case-sensitive because they work for exact matches.
Locationis distinct from
- A string: Filters only accept strings (which can include numbers). Leaving the filter blank will return only devices that have no value for that attribute. You can also filter by Boolean values
Combining attributes in a filter
When you create a filter with more than one attribute, the relationship between them is
and. If you want to filter by
or, you will need to create an attribute specifically for that.
For example, you have devices with the custom attribute key
Location and the values
Ely. You want to create a single filter for devices that are in Cambridge or Royston. If you filter for Cambridge and Royston, the filter will search for a device that has both values in the
Location key; no device matches this filter.
To find these devices, you could create a custom attribute with the key
Not Ely, and give all Cambridge and Royston devices the value
An implication of this is that if you misspell a value (such as
Camridge), you cannot run a filter that will find all devices that have either
Camridge in the same