The Device: Delete Node allows a Workflow to remove one or more Devices from your Application.
In the Delete Mode dropdown, you can choose to delete:
- a single Device by ID.
- multiple Devices using an advanced query.
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.
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.
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.
There are a number of cases where you may wish to delete one or more Devices via a Workflow.
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.
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.
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.
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:
- The Device ID matches the ID passed as a path parameter in the request, AND
- The Device is associated with the Experience User
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.
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
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.