ApplicationExperience

Device: Delete Node

The Device: Delete Node allows a Workflow to remove one or more Devices from your Application.

Device: Delete Overview

Node Properties

In the Delete Mode dropdown, you can choose to delete:

Deleting One Device

To delete a single Device by ID, select One Device by ID in the Delete Method dropdown. This will expose a required ID Template field, whose value should be either a specific Device ID or a template resolving to a Device ID on your payload.

Deleting Multiple Devices

To delete multiple Devices by advanced query, select Multiple Devices by query in the Delete Method dropdown. This will expose an advanced query input for defining which Devices to delete.

Note: To prevent accidental deletions, the default query will always return no Devices; the default query must be changed for the node to have any effect on your Application. Also, make sure to change the match operator (“Match ANY / ALL / NONE”) to reflect the Devices you wish to delete.

Result Path

Optionally, you may also store the result of the deletion operation at a path on your payload.

When deleting a single Device by ID, the value at the specified path will be true, indicating that the operation succeeded.

When deleting multiple Devices by query, the value at the specified path will be an object.

  • If the query resolves to a large number of Devices, the object will contain the property jobQueued, indicating that the deletion operation is in progress. Depending on how many Devices the query resolved to, this could take a few seconds or several minutes.
  • If the query resolves to just a few Devices, the object will contain the properties removed (a number indicating how many Devices were deleted) and failed (indicating how many Devices that could not be deleted).

If the operation does not succeed, the node will place an error object at the specified path.

Node Example

There are a number of cases where you may wish to delete one or more Devices via a Workflow.

Inactive Device Pruning

One use case for the Device: Delete Node is to delete a Device from your Application if it has failed to report state for a significant length of time. Depending on your Application, this can mean that the Device is no longer in use, and deleting any such Devices can help keep your organization’s Device count below its resource limit.

Device: Delete Example - Inactive

In this example, a Device: Inactive Trigger fires if any Device matching a tag query fails to report state for 180 days. The triggerId is the ID of the Device that caused the trigger to fire, and we are using that value to know which Device to delete in this Workflow.

Experience User Device Deletion

Another common use for the Device: Delete Node - as well as its related Device manipulation nodes - is to allow Experience Users a method for manipulating the Devices in your Application. They can do so by making an Endpoint request that in turn fires a Workflow.

Device: Delete Example - Experience

In this example, we imagine that an Experience User makes a request to delete a Device in the Application. Though the user is only attempting to delete one Device, we choose to delete multiple Devices by query because we do not want to allow the user to delete a Device not associated with his/her account.

Therefore, the will only delete Devices that match ALL of the following criteria:

Given that Device IDs are unique across your Application, and that we are performing a “Match All” query, this operation will delete a maximum of one Device from your Application per Workflow run.

Node Errors

If Device deletion fails and a result path has been set, an error object will be placed at the specified path. This object will include two properties:

  • type: A single word noting the type of error that occurred
  • message: A human-readable message describing the error that occurred

When deleting a single Device by ID, the most common error is a “NotFound” error. This error will throw when:

  • A template is provided for the ID, and that template fails to resolve to a Device ID
  • An ID is provided either explicitly or through a template, and that Device has either already been deleted or never existed

When deleting multiple Devices by query, “Validation” errors are more common. These most often occur when:

  • Referencing payload values in the query via string templates, and the resolved values lead to an invalid query (for example, referencing a value that does not resolve to a valid ID when the queried property expects an ID)
  • Building an advanced query in “Advanced” mode - that is, defining the query through a JSON template instead of line by line in the interface - and the input does not resolve to a valid query

Failed Deletions

When deleting multiple Devices by query, it is possible for some of the Devices to fail to delete. When storing the result of the operation, the number of Devices that failed to delete will be included in the result object. If a Device fails to delete, it is almost always because you are attempting to delete a System Device that currently has children assigned to it.

To avoid these failures, clear out the Parent ID of any Device that references the Device you wish to delete.

Was this page helpful?

Still looking for help? You can also search the Losant Forums or submit your question there.