ApplicationExperience

Device: Get Node

The Device: Get Node allows a workflow to retrieve one or more Devices from the current application and add them to the current workflow payload.

Get Device Node

Node Properties

The configuration for the Device: Get Node requires a query method and parameters to find a device connected to Losant.

Query Method

The first step is selecting a query method to use to find a device or group of devices. The Device: Get Node has many query options:

Get Device Node Query Methods

  • Device ID: You can input a specific device’s ID to retrieve it or use a value on the payload. The ID can be hardcoded in the workflow editor or derived from a property on the current payload.
  • Device Name: You can input a specific device’s name to retrieve it or use a value on the payload. The name can be hardcoded in the workflow editor or derived from a property on the current payload.
  • Tag Query (deprecated): This has been deprecated, if your node was using ‘Tag Query’ please view the section ‘Match All Tags Query’, and your node will have updated properly. There is no difference in behavior from ‘Tag Query’ to ‘Match All Tags Query’, this is just a change in name to allow users to ‘Match Any Tags Query’ without confusion.
  • Match All Tags Query: You can set specific tag key/value pairs to retrieve one or more devices. Any device(s) returned will match all tags in the query. The key/value can be hardcoded or derived from a property on the current payload.

    You may also query by key only or value only. If a key is set without a value, any device that has that key set regardless of the value will be returned. If a value is set without a key, any device that has that value set regardless of the key will be returned.

  • Match Any Tags Query: You can set specific tag key/value pairs to retrieve one or more devices. Any device(s) returned will match any tags in the query. The key/value can be hardcoded or derived from a property on the current payload.

    You may also query by key only or value only. If a key is set without a value, any device that has that key set regardless of the value will be returned. If a value is set without a key, any device that has that value set regardless of the key will be returned.

  • Parent System ID: You can input a System Parent ID to retrieve any devices which are children of a particular System or of no parent Systems. The ID can be hardcoded in the workflow editor or derived from a property on the current payload.
  • Experience Group ID: You can input an Experience Group ID to retrieve any devices associated with that group or any of its children. The ID can be hardcoded in the workflow editor or derived from a property on the current payload.
  • Experience User ID or Email: You can input an Experience User ID or email to retrieve any devices that the user is associated with by their Experience Groups. The ID or email can be hardcoded in the workflow editor or derived from a property on the current payload.

Configuration

Depending on the query method selected, you are able to input the specific Device ID, Device Name, or the tag key/value pairs to find a device or group of devices.

Results Configuration

For each query method aside from Device ID an extra set of properties will appear beside the tags input:

  • Return multiple devices?: If you want to return multiple devices from this query, check this box. This also alters the return type of the result. If checked and nothing is found, an empty array will be returned instead of null. If checked and one or more devices have been found they will be returned as an array.
  • Results Per Page: This templatable input is the maximum number of devices to return with one query. The max number of devices that can be returned at once is 1000. The default is 100.
  • Page Number: This is a templatable input that resolves to a number. This number must be greater than 0, and the default is 0. This defines the number of results to skip by multiplying this number by the Results per Page field.
  • Sort Field: This is the field on the group to sort the results by. By default, this field is name. The following are the valid sort fields: name, id, creationDate or lastUpdated.
  • Sort Direction: This is the field that tells the sort field which direction to sort in. By default, this field is Ascending.

NOTE: Sorting options affect the result — even when returning a single device.

Result Path

It is required you specify where on the payload path you want the device or group of devices to be stored.

There are also options to change the format of the output data:

Composite State To Include: You can ask for a composite of the last known state of each attribute of the device to be included as well, which will be added to the device under the compositeState field. The valid options for this are:

  • Include no attributes: This is the default, and means no composite state will be returned.
  • Include all attributes: This will return composite state for every attribute on the device.
  • Include the following attributes: This will return composite state for the specifically selected attributes.

Return tags as an object map instead of an array: By default this node will return a standard array of key/value pairs (the same as the Losant API returns):

{
  ...
  "tags": [
    {
      "value": "pump",
      "key": "type"
    },
    {
      "value": "Model #2088-554-144",
      "key": "part_id"
    },
    {
      "value": "2088-554-144",
      "key": "part_id"
    },
    {
      "value": "5bbfc10322f6f70008ae6b97",
      "key": "supplier_id"
    }
  ],
  ...
}

However, you can instead ask for the tags to be in the form of an object map, where the tags property will be an object. In that case, each tag key will be a property on the object, and the value of that property will be an array of all the tag values for that key on the device.

{
  ...
  "tags": {
    "supplier_id": [ "5bbfc10322f6f70008ae6b97" ],
    "part_id": [ "Model #2088-554-144", "2088-554-144" ],
    "type": [ "pump" ]
  },
  ...
}

This is often an easier form to work with inside of workflows.

Node Example

For example, if we get a single device by the tag sigfox_id where its value is AA00FF, with the tags set to return in object form, with composite state set to include the attributes temp and humidity, and the result path set to data.losantDevice, the result might look like the following:

{
  "data": {
    "body": {
      "device": "AA00FF",
      ...
    },
    "losantDevice": {
      "id": "56c794a06895b00100cbe84c",
      "name": "Sigfox Device",
      "deviceClass": "standalone",
      "tags": {
        "sigfox_id": ["AA00FF"]
      },
      "attributes": [
        { "name": "temp", "dataType": "number" },
        { "name": "humidity", "dataType": "number" }
      ],
      "compositeState": {
        "temp": {
          "time": Thu Aug 16, 2018 10:17:36 GMT-04:00,
          "value": "15.6"
        },
        "humidity": {
          "time": Thu Aug 16, 2018 10:10:36 GMT-04:00,
          "value": "0.67"
        }
      }
      ...
    },
    ...
  },
  ...
}

Node Errors

For the Device ID and Device Name queries, the result will either be the device object or null if no device is found. Here is an example of an empty result for this case:

{
  "applicationName": "Water Pump",
  "flowName": "Tester",
  "flowId": "5cf6cb469136cc0038c37aa3",
  "relayType": "user",
  "relayId": "574f2ca804554101007ff876",
  "flowVersion": "develop",
  "triggerType": "virtualButton",
  "triggerId": "5cf6cb419136cc0008c37aa3-wnW2xlu7r9q2IxaBZjZ5c",
  "applicationId": "5bbb973892e051000926d195",
  "data": {
    "device": null
  },
  "time": "2019-06-04T19:58:08.340Z"
}

For the Match All Tags Query, Match Any Tags Query, Experience Group ID or Experience User ID or Email queries, if the return multiple device? checkbox is unchecked the results will either be the device object or null if no device is found. Otherwise if the return multiple device? checkbox is checked then the results will either be an array of objects or an empty array. Here is an example of an empty result for this case:

{
  "applicationName": "Water Pump",
  "flowName": "Tester",
  "flowId": "5cf6cb469136cc0038c37aa3",
  "relayType": "user",
  "relayId": "574f2ca804554101007ff876",
  "flowVersion": "develop",
  "triggerType": "virtualButton",
  "triggerId": "5cf6cb419136cc0008c37aa3-wnW2xlu7r9q2IxaBZjZ5c",
  "applicationId": "5bbb973892e051000926d195",
  "data": {
    "device": []
  },
  "time": "2019-06-04T19:58:08.340Z"
}