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.

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:

• 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.

• 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.
• Advanced Query: You can also form an advanced query to allow more complex device matching than the above methods.

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.

• Metadata: You will also have the option to return metadata in addition to the queried devices.

  • Return just an array of results - The Device: Get Node’s result will be an array of devices.
  • Return an object containing metadata along with results - The Device: Get Node’s result will be an object with keys for metadata properties in addition to an array of devices in the items key.

An example of the Device: Get Node’s metadata can be found in the Node Example.

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.

Return attributes as an object map instead of an array: By default this node will return a standard array of attribute information objects (the same as the Losant API returns):

{
  ...
  "attributes": [
    {
      "name": "flow",
      "dataType": "number",
      "attributeTags": { "unit": "gal/sec" }
    },
    {
      "name": "running",
      "dataType": "boolean",
      "description": "Is the pump currently running"
    }
  ],
  ...
}

However, you can instead ask for the attributes to be in the form of an object map instead of an array. In that case, each attribute name will be a property on the object, and the value of that property will be the attribute information object for that attribute name.

{
  ...
  "attributes": {
    "flow": {
      "name": "flow",
      "dataType": "number",
      "attributeTags": { "unit": "gal/sec" }
    },
    "running": {
      "name": "running",
      "dataType": "boolean",
      "description": "Is the pump currently running"
    }
  },
  ...
}

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 working.deviceResult, the result might look like the following:

{
  "working": {
    "deviceResult": {
      "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"
        }
      }
    },
  },
  "data": {
    "body": {
      "device": "AA00FF",
      ...
    },
    ...
  },
  ...
}

If querying for multiple devices with metadata, the result will look like the following:

{
  "working": {
    "deviceResult": {
      "count": 100, //the number of devices returned
      "query": { ... }, // the query used to find devices
      "findMethod": "query",
      "perPage": 100,
      "page": 0,
      "totalCount": 193, //the number of devices matched by the query
      "sortField": "creationDate",
      "sortDirection": "desc",
      "items": [ ... ] //The resulting events from the query
    }
  },
  ...
}

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:

{
  "working": {
    "deviceResult": null
  },
  "applicationName": "Water Pump",
  "flowName": "Tester",
  "flowId": "5cf6cb469136cc0038c37aa3",
  "relayType": "user",
  "relayId": "574f2ca804554101007ff876",
  "flowVersion": "develop",
  "triggerType": "virtualButton",
  "triggerId": "5cf6cb419136cc0008c37aa3-wnW2xlu7r9q2IxaBZjZ5c",
  "applicationId": "5bbb973892e051000926d195",
  "data": {},
  "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:

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

Related Nodes

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