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.

Once you are familiar with these concepts, see the tutorials on creating device filters in Portal or using attributes and filters through the APIs to put them into practice.

Attributes

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

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

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.

Filters

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.

Filter requirements

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. Location is distinct from location.
• 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 true and false.

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 Cambridge, Royston and 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 True.

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 Cambridge or Camridge in the same Location key.