Bulk Device Actions

Bulk device actions provide an easy way to perform a number of actions on multiple devices at once. Access to all bulk action options can be found in the “Bulk Device Actions” menu on the Devices page in the application.

Update Devices

You may provide one or more update operations to perform on multiple devices in a single request by choosing “Update Devices” from the device list dropdown menu.

Select Devices

First, select the devices to update in the “Select Devices” section. Select either “Update all devices in the application” or choose to query a subset of devices. By default, the bulk-update device query matches the query applied to the Devices List when the “Update Devices” option was selected. Confirm the number of devices being updated at the bottom of the page before submitting the form.

Configure Operations

Once the devices to be updated have been selected, choose at least one operation to perform on those devices in the “Update Properties” section. Details of each available operation are listed below.

Note: Some operations may only be applied once per bulk update request - for example, Device Class: Set. Similarly, some operations cannot be applied to a property / attribute if a previous operation is applied to the same property / attribute. For example, an Attribute: Remove operation targeting a “temperature” attribute canot be followed by an Attribute: Rename operation also targeting a “temperature” attribute.

Device Tag: Remove

Removes a tag key from all devices in the query. Devices included in the query that do not have a matching tag will not be affected. Note that the tag key must be unique across all Device Tag: Remove and Device Tag: Set Value operations.

Device Tag: Set Value

Sets a tag value for all devices in the query. If the tag already exists on a device, its value will be overwritten. Note that the tag key must be unique across all Device Tag: Remove and Device Tag: Set Value operations.

Attribute: Remove

Removes the attribute selected from all devices in the query. Devices included in the query that do not have a matching attribute will not be affected. This applies systems and non-systems alike.

Attribute: Add (Non-System)

Adds the attribute specified to all devices in the query that are not system devices. Validation for the attribute specified is the same as all device attributes.

Attribute: Add (System)

The same as the Attribute: Add operation, but for system devices only. The operation includes additional settings required to configure a system-type attribute.

Attribute Tag: Remove

Removes the attribute tag specified from any attribute matching the name. Devices included in the query that do not have a matching attribute or tag on that attribute will not be affected.

Attribute Tag: Set

Sets an attribute tag value on a given attribute name for all devices in the query. If the tag already exists on the attribute, its value will be overwritten.

Attribute: Rename

Given an attribute name, provide a new name for the attribute. Blob-type attributes will be ignored. If a matching device already has an attribute of the new name, the operation will fail. (Note: Renaming device attributes can cause breaking changes in your application. Take care when performing this operation.)

Attribute Content Type: Set

Given an attribute name for a Blob-type attribute, set the content type for the attribute. Devices that do not have the attribute defined, or that have an attribute matching the name but not of the Blob type, will not be affected.

Attribute Description: Remove

Removes the description from an attribute for all devices in the query. Devices included in the query that do not have a matching attribute will not be affected.

Attribute Description: Set

Sets the description for an attribute for all devices in the query. All descriptions already set on the selected attribute will be overwritten.

Device Class: Set

Updates the device class for all devices in the query. Devices of the system class will not be affected, and you may not choose to set the device class to system. Only one Device Class: Set operation is allowed at a time, and Gateway ID: Set operations are not allowed in conjunction with it.

If you choose to set the device class to peripheral, you must also be sure to choose either to choose to scope it to any gateway device or a specific gateway device. If you choose to scope it to a specific gateway device, you must choose that device from the dropdown provided.

Gateway ID: Set

Sets the gateway ID for all peripheral devices in your query. Only one Gateway ID: Set operation is allowed at a time, and Device Class: Set operations are not allowed in conjunction with it.

Parent ID: Remove

Removes the parent ID from all devices in your query, thus dissociating them from your system hierarchy. Only one Parent ID: Remove operation is allowed at a time.

Parent ID: Set

Sets the parent ID for all devices in your query, with the exception of any that may cause a circular dependency. Only one Parent ID: Set operation is allowed at a time.

System Interval: Set

Sets the system interval for all system devices in your query. Only one System Interval: Set operation is allowed at a time.

System Keep Duplicates: Set

Sets the Keep Duplicates for all system devices in your query. Only one System Keep Duplicates: Set operation is allowed at a time.

Export Devices

To export a list of application’s devices, select the “Export Devices” item from the “Bulk Device Actions” dropdown menu in the top right corner of the list. Then, enter an email address and/or a callback URL for where to send the resulting export file. You may choose to export the device metadata in either a CSV format or in a JSON format.

Note: Device exports filter devices based on the advanced query applied to the devices list. To export a different set of devices, update the query applied to the table behind the modal.

When selecting CSV format, each row in the file corresponds to a single device returned by the device query. The file will have the following columns:

• ID: Values within this column correspond to the alphanumeric IDs of the devices returned within your query.
• Name: These are the human-readable names given to the devices corresponding to the IDs in the previous column.
• Description: If a description was provided for a device, it will appear in this column.
• Class: This corresponds to the device type set for each device.
• Gateway ID: If the row represents a peripheral device, this column provides the ID of the gateway associated with the peripheral.
• Parent ID: If the device has a parent system, this column provides the ID of that parent.

• Connection Info Status: This column provides one of four values, corresponding to the device’s connection status at the time of the export:

  • connected: The device is connected to Losant’s MQTT broker or has been marked as “connected” through our API.
  • disconnected: The device is not connected to Losant MQTT broker or has been marked as “disconnected” through our API.
  • unknown: The device has never connected to Losant.
  • invalid: The device is incapable of connecting to Losant’s MQTT broker (such as a system device).
• Connection Info Time: If the device is connected or disconnected, this value is an ISO 8601 timestamp for when the last connection or disconnection event occurred.
• tag-[TAG_KEY]: For each unique tag across all the devices returned in the query, there will be a column corresponding to that tag. If a device has a value defined for that key, the value will appear in its respective column. Note: If any of your devices has more than one value set for a specific key, there will be additional “tag” column(s) matching the maximum number of values of that tag on any one device. For any device that does not have multiple values for such a tag, the extra column(s) will be blank.

When selecting JSON format, the output is a JSON array whose values are objects for each device returned by the query. The format of each object is similar to the device schema, except that tags and attributes are returned as objects instead of arrays, keyed by the tag key or attribute name respectively.

Note: Attribute configuration, including attribute tags and descriptions, is only provided in the JSON format.

If you provide a callback URL, Losant will make a POST request to the provided URL once the export is ready. The body of the request will be a JSON object with the following properties:

• applicationId: The ID of the application where the request was made.
• dataType: The type of request this callback is serving. In this case the value will always be “DevicesMetadata”.
• downloadUrl: A signed URL where the export file can be downloaded. This URL is valid for 7 days.
• jobId: A unique ID for this export request.

Request Data Export

To request a telemetry (state) data export for devices, select “Request Data Export” from the “Bulk Device Actions” dropdown menu. By default, data will be exported for all devices matching the query under the following settings …

• Email the exported CSV to the address of the user making the request.
• Export all data from the current time back to the application owner’s data retention limit.
• Provide links to download Blob attribute data (versus providing Base64-encoded Blob data in the CSV). This setting is only applicable if the device(s) being exported include Blob attributes.
• Export all attributes across all devices matching the query.
• Include the “ISO Date” column in the CSV (in addition to the “Timestamp” column).
• Include the “Device ID” column in the CSV.
• Concatenate all device data into a single CSV (versus generating a single CSV per device and a reference CSV mapping device IDs to links to each device’s file).

To change any of these settings, click the “Make changes” link to display form fields for modifying the request. For example …

• The export result can be sent to a callback URL.
• Data can be exported only within a certain range (including any future-reported data from up to 24 hours beyond the current time).
• Blob attribute data can be provided inline in the result CSV - though this can lead to excessively large files, possibly resulting in a failed request.
• Only specific attributes can be exported.
• Devices can be exported as individual files per device.

After requesting the export, the recipient email address and/or callback URL request will receive a link to a CSV file containing the exported device data. (This link expires after 7 days.) Depending on the number of devices and the time range requested, it could take a few hours before the email is received.

Handling Failed Requests

If the size of the CSV file for the export exceeds 10GB, the export will terminate and the recipient email address and/or callback URL will receive a notice about the failure termination. If that occurs, there are several modifications you can make to reduce the export file size to fit within the limits …

• Shorten the range of data being exported.
• Only export the attributes needed for your use case.
• Exclude the “ISO Date” column from the result.
• Choose to export a single file per device.

Send Command

To send a command to many devices at once, select “Send Command” from the “Bulk Device Actions” dropdown menu. Within the modal, provide a command name and optionally a command payload. To send, click “Send Command”.

Delete Data

To delete device data, select “Delete Data” from the “Bulk Device Actions” dropdown menu. By default, all device attribute state data, all device command history, and all device connection logs will be deleted. Within the modal, you can optionally configure deletion settings giving you more granular control over what gets deleted. To delete, acknowledge the confirmation checkbox, then click “Delete Data”. Note: This action is permanent and cannot be undone.

Delete Devices

To delete devices, select “Delete Devices” from the “Bulk Device Actions” dropdown menu. To perform, acknowledge the confirmation checkbox, then click “Delete Devices”. Note: This action is permanent and cannot be undone.