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:

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

  • 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 will be able to input the specific Device ID, Device Name, or the tag key/value pairs to find a device or group of devices.

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:

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": "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"
    ],
    "type": [
      "pump"
    ]
  },
  ...
}

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

Include the most recent composite state reported : 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.

Node Example

For example, if we get a device by the tag sigfox_id where its value is AA00FF, the result will 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",
          "relayId": "56c8967bb8df0f0100d62912",
          "relayType": "flow"
        },
        "humidity": {
          "time": Thu Aug 16, 2018 10:10:36 GMT-04:00,
          "value": "0.67",
          "relayId": "56c8967bb8df0f0100d62912",
          "relayType": "flow"
        }
      }
      ...
    },
    ...
  },
  ...
}

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"
}