Many features within the Losant Platform require users to provide a list of devices to interact with. For example:
- Dashboard blocks can visualize data from one or many devices
- Workflows can trigger commands to one or more devices
- Access keys can limit access to specific devices within your application
This list is provided in the form of a device query. In short, a device query is a list of device IDs and device tags. Queries are generally inclusive, meaning that if any condition in the query returns true, the device ID or tagged devices are returned.
When prompted by a component to provide a device, a device tag, or a combination of the two, select the input and begin typing. You will then see a list of devices or tags that match your current search parameter.
Once you have found the device / tag you would like to add to your query, either click the item to add it to the query, or toggle your keyboard arrows down to the item you’d like to add and press enter.
When creating a device, you are prompted to give your new device a name; and immediately after creation, that device is assigned an ID by Losant. When searching for a device to add to your query, you may enter any part of the device’s name or ID to find it.
You may provide just a single ID to interact with one device, or you may provide a list of as many device IDs as you would like to interact with multiple specific devices.
Some components in the Losant Platform only accept one device at a time, in which case you will only be able to select one device.
Querying by device can also be dynamic in certain situations. Certain workflow nodes allow you to template the device ID, allowing you to query or access a specific device dynamically. In dashboards, you can do dynamic device queries using device ID context variables.
Queries may also be built against the tags you assign to your devices. Tags may be added, edited or deleted from a device at any time, which allows you to easily add or remove devices from dashboard visualizations, workflows and security groups without having to individually edit those components.
To add a tag to a device query, start typing any key or value that has been assigned to a device within your currently selected application. You will see a list of suggestions and, just like with devices, you may then add that tag to your query. Any device that matches the provided tag will then be returned by your query.
Note that you will see wildcard options in your tag searches; selecting one of these options (either a
key=* or a
value=* option) will return all devices within your application that have either that provided key or value assigned to it, regardless of the other value.
Querying by device tags can also be dynamic in certain situations. Certain workflow nodes allow you to template the device tags, allowing you to query or access a set of devices dynamically. In dashboards, you can do dynamic device queries using device tag context variables.
In certain locations in the platform, you can query for the devices associated with an experience user. In these cases, an experience user is actually resolved to any associated device IDs/tags (through their experience groups) - and then the query proceeds as a normal device ID/tag query. The most common place for this type of query is in a dashboard using an experience user context variable.
You can also mix an experience user query with other tag or ID filters, like the above. Be aware that in the general case, device queries are match any queries, and so a query like the one above would return devices that match any of those above filters (not just the devices associated with the experience user). In the example screenshot above, that device query would return all of the following:
- The specific device
- Any devices that have a tag of
sourcewith a value of
- Any devices that match any of the IDs or tags associated with any of the groups (or child groups) that the experience user in the
experienceUser-0context variable is a member of
Items can be removed from the query at any time. If the query only accepts one value, click the “x” to the right to delete the device / tag.
If the query takes multiple items, you may remove a single item by clicking the “x” in the item’s box …
… or you may delete all of your entries by clicking the “x” to the right.
Many areas of the platform also support returning devices through an advanced query. The following properties are supported within advanced device queries:
- ancestorId: An ID comparison for returning the direct or deep children of a given system device.
- attributeName: A string comparison for returning devices that do - or do not - have a specific attribute by name.
- connectedAt: A date comparison for the timestamp at which the device connected to Losant. Will only ever match against currently connected devices.
connectionStatus: An enumeration comparison for returning devices that match the given connection status. The valid values are as follows:
connectedwill match devices currently connected to Losant.
disconnectedwill match devices that have previously connected and are currently disconnected from Losant.
unknownwill match devices that can connect to Losant but whose current status is not determined (for example a device that has never connected at all).
invalidwill match devices that cannot connect to Losant (for example, system or peripheral devices).
- creationDate: A date comparison for the timestamp at which the device was created.
- deviceClass: An enumeration comparison for the device’s class.
- disconnectedAt: A date comparison for the timestamp at which the device disconnected from to Losant. Will only ever match against currently disconnected devices.
- experienceGroupId: An ID comparison for returning devices associated with a given Experience Group. NOTE: This field is not available when building an advanced query to associate devices with an Experience Group.
- experienceUserId: An ID comparison for returning devices associated with a given Experience User. This query compares Experience Group device associations with Experience Users assigned to those Experience Groups. NOTE: This field is not available when building an advanced query to associate devices with an Experience Group.
- gatewayId: An ID comparison for returning peripheral devices associated with a particular gateway device.
- id: An ID comparison for the unique ID assigned to the device upon creation.
- lastUpdated: A date comparison for the timestamp at which the device was last updated.
- name: A string comparison for the name of the device.
- parentId: An ID comparison for returning the direct children of a given system device.
- tags: A tag comparison for returning devices that have a specific tag key, value, or key/value pair.