Device: Update Node

The Device: Update Node allows a workflow to update an existing Device inside the current application, and optionally add the updated device to the current workflow payload.

Node Properties

To find the device to update, the node requires the device ID. This field is templatable, and so supports finding a device based on the current workflow payload. The example below is doing exactly that, and is referencing the field data.body.deviceId on the workflow payload.

Configuration

There are three different ways to configure input data for the Device: Update Node - “JSON Template”, “Payload Path”, and “Individual Fields”. The first two are more complicated to use, but are very powerful because they give you full control over the device being updated, while the third choice is the more common option for simple situations.

JSON Template & Payload Path

For “JSON Template”, the input must be a JSON template string that can be parsed into a JSON object that validates against the Device Patch schema. For “Payload Path”, the input must be a payload path that points to an object on the current workflow payload that, again, validates against the Device Patch schema.

Both of these methods will only update any top-level properties included in the input object. For example, given the following device …

{
  "name": "My Device",
  "deviceClass": "standalone",
  "tags": [{ "key": "myTagKey", "value": "My Tag Value" }],
  "attributes": [{ "name": "myNumberAttribute", "dataType": "number" }]
}

… and a Device: Update Node with a JSON template input (or a payload path referencing an input object) of …

{
  "name": "My Updated Device",
  "tags": [{ "key": "aDifferentTagKey", "value": "My Different Tag Value" }]
}

… the resulting device after the update will be …

{
  "name": "My Updated Device",
  "deviceClass": "standalone",
  "tags": [{ "key": "aDifferentTagKey", "value": "My Different Tag Value" }],
  "attributes": [{ "name": "myNumberAttribute", "dataType": "number" }]
}

Note that the name property changed, and the array of tags completely replaced the original array - as in, all of the device’s tags were replaced with the tags included in the input object. The same behavior would occur if an attributes array were passed in the request.

Individual Fields

For “Individual Fields”, the most common method to use and the one shown in the example above, the device is broken into multiple fields that can be filled in using individual string templates. In this case, none of the fields are required - leaving a field blank will just not update that field on the device. In the example above, the node is just changing the description on the device and leaving the other fields alone. “Parent System ID” can be edited or optionally removed by selecting the checkbox.

The “Individual Field” configuration also allows you to modify the device attributes. You can add or remove attributes on the device while leaving other existing attributes intact. For removing attributes, the configuration just takes a templatable attribute name. In the example above, we are removing the attribute tempF from the device. If the attribute name to remove is not found on the device being updated, the removal does nothing. For adding an attribute, the configuration takes both the attribute name, the data type, and an optional content type (which are all templatable). The content type field will only appear if data type is blob or a template. Content type is only required for attributes whose data type is blob. If the attribute name already exists on the device, the existing data type is modified, otherwise the new attribute name with the given data type is added to the existing device attributes. If more detailed control is needed for modifying attributes, the “JSON Template” or “Payload Path” methods of entry should be used.

Finally, the “Individual Field” configuration also allows you to modify tags. You can add, change, and remove tags on the device while leaving other existing tags intact. For removing tags, the configuration just takes a templatable tag key, and all tags that match the given key are removed. In the example above, we are removing the tag reportsF from the device. If the tag key to remove is not found on the device being updated, the removal does nothing. For modifying or adding a tag, the configuration takes both the key and the value (which are both templatable). If tags already exist on the device with the given key, they are removed, and the new value for that tag key is added. If more detailed control is needed for modifying tags, the “JSON Template” or “Payload Path” methods of entry should be used.

Result Path

Optionally you can provide a payload path in the “Result Path” field so that the updated device can be placed at that path on the current workflow payload. In the case of a successful device update operation, this will be the updated device object. In the case of a failed device update, this will be an object of the errors that occurred trying to update the device.

In addition, you have the option of changing the form of the attributes and/or tags on the device result. By default, attributes and tags are returned in the standard API format as an array of objects, but you can instead ask for them to be in the form of an object map. The Device: Get Node’s documentation describes each format in detail.

Node Example

For instance, given the example node configuration in the screenshots above, this is a possible result for a successful device update:

{
  "data": {
    "body": {
      "deviceId": "589de7d2a1975a00017b227f",
      "newDescription": "My example description",
      ...
    }
  },
  "deviceUpdateResult": {
    "name": "My Device",
    "description": "My example description",
    "attributes": [
      { "name": "tempC", "dataType": "number" }
    ],
    "tags": {
      "reportsC": ["true"]
    },
    "deviceClass": "standalone",
    "applicationId": "56c794a06895b00100cbe84c",
    "creationDate": "2017-04-06T19:28:37.284Z",
    "lastUpdated": "2017-06-15T16:56:36.348Z",
    "deviceId": "589de7d2a1975a00017b227f",
    "id": "589de7d2a1975a00017b227f",
    "connectionInfo": {
      "connected": null
    }
  },
  ...
}

Node Errors

And again, given the example above, this is a possible result for a failed update, in this case where the device was not found:

{
{
  "data": {
    "body": {
      "deviceId": "589de7d2a1975a00017b227f",
      "newDescription": "My example description",
      ...
    },
    ...
  },
  "deviceUpdateResult": {
    "error": {
      "type": "NotFound",
      "message": "Device was not found"
    }
  },
  ...
}

Related Nodes

• Device: Create
• Device: Update
• Device: Delete