Device Queries

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/or device tags and, in the case of dashboards, specific context variables. In many cases, the IDs and tags may utilize string templates to reference values from, for example, a workflow payload or an experience endpoint request.

Queries are inclusive, meaning that if any condition in the query returns true, the device ID or tagged devices are returned.

Constructing Device Queries

In most cases where a device query is warranted, the interface will first provide an input for selecting a single device. In the case of dashboard blocks, for example, the majority of device queries target (display data for) a single device at a time.

To instead target multiple devices, click the link that appears beneath the device selector to open a modal where you may select one or more specific devices; one or more device tags; and, if applicable, one or more device tag / experience user context variables. (If you previously had a single device selected, it will automatically populate the device selector within the modal.)

Once you have finished building your query, click “Update Query” to apply your selection and close the modal. You may also click “Cancel” to revert your changes and return to the previous value, or click “Reset to Default” to clear all selections.

You may update the query at any time by clicking the “Edit” (pencil) icon in the component showing the current query. You may clear the query value by clicking the “Reset” (circle arrow) icon.

Querying by Devices

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 the full device 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 if you would like to interact with multiple specific devices.

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.

Note: 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 and will have the option to select multiple devices. This includes, for example, choosing a single gateway device to associate with a peripheral device.

Querying by Device Tags

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, click the “Select multiple devices” link that appears beneath the single device selector to enter the query builder modal. In the “Tag Key” / “Tag Value” inputs, enter keys and/or values that have been assigned to a device within your 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.

To return all devices that have a given tag key defined, regardless of its value, enter the name of the tag in the “Tag Key” input and leave the “Tag Value” input blank.

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 based on values in the payload. In dashboards, you can do dynamic device queries using device tag context variables as described below.

Querying by Tag / User Context Variables

When constructing multi-device queries in dashboard blocks, any device tag or experience user context variables configured for the dashboard will appear as selectable checkboxes beneath the modal’s tag inputs. Selecting these variables will add them to the query and return any matching devices for each selected variable, along with any devices or device tags included above them.

Note: Device ID context variables are added to the query by entering them in the device selector.

Advanced Queries

Many areas of the platform that take a device IDs / tags query also support returning devices through an advanced query. If so, the mode selector dropdown at the top of the modal will be enabled with options for building an advanced query.

When switching between the different query modes, Losant will attempt to match the previous query to the new rule set if possible; if not, the query will reset to an empty state.

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:

  • connected will match devices currently connected to Losant.
  • disconnected will match devices that have previously connected and are currently disconnected from Losant.
  • unknown will match devices that can connect to Losant but whose current status is not determined (for example a device that has never connected at all).
  • invalid will 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.