Live Objects - complete developer guide

Search API

REST Endpoint

POST /api/v1/deviceMgt/explorer/search

Filter queries

The queries are entirely detailed in common filters.

The format of a search query matches the following pattern:

{
    "query": "...",
    "filters": {...},
    "sort": [...],
    "bookmark": [...],
    "size": ...
}

The global request uses the following description :

JSON Params	Description
query	Optional. partial search allows to find devices by indicating partial values. It is searched among the following fields: id, name, group.path, tags, properties.key, properties.value. It is a string format, case-insensitive and if there are multiple words they are filtered with the OR operator. At least 3 characters are needed to find words of more than 3 characters. Smaller words can be found by indicating their complete value. 256 characters maximum
filters	Optional. identical criteria described in common filtering chapter
size	Optional. maximum number of devices to return
sort	Optional. array of sort elements which accepts "group.path", "name", "interfaces.status", "interfaces.enabled", "interfaces.lastContact", "lastCommunication", "created", "updated", "relevance", "network.lora.lostMessagesRatio", "id". "id" must be set at the end. Per default, when array is empty or the "id" is not set, the sort will be done by ascending "id". More over to indicate a sort on reverse way, a "-" must be set in front of element (Ex: "-id").
bookmark	Optional. array of indexes of the last research (compatible with the sort list in number and order). When it is using, the bookmark corresponding to the "id" must always be set (even if not set in the sort list or sort list is empty).

JSON Params

Description

query

Optional. partial search allows to find devices by indicating partial values. It is searched among the following fields: id, name, group.path, tags, properties.key, properties.value. It is a string format, case-insensitive and if there are multiple words they are filtered with the OR operator. At least 3 characters are needed to find words of more than 3 characters. Smaller words can be found by indicating their complete value. 256 characters maximum

filters

Optional. identical criteria described in common filtering chapter

size

Optional. maximum number of devices to return

sort

Optional. array of sort elements which accepts "group.path", "name", "interfaces.status", "interfaces.enabled", "interfaces.lastContact", "lastCommunication", "created", "updated", "relevance", "network.lora.lostMessagesRatio", "id". "id" must be set at the end. Per default, when array is empty or the "id" is not set, the sort will be done by ascending "id". More over to indicate a sort on reverse way, a "-" must be set in front of element (Ex: "-id").

bookmark

Optional. array of indexes of the last research (compatible with the sort list in number and order). When it is using, the bookmark corresponding to the "id" must always be set (even if not set in the sort list or sort list is empty).

If "query" and "filters" fields are present, they are processed with AND operator. "bookmark" is used to optimize the search when consecutive requests are made one after the other, in executing the search from the last found device.

According to the internal model, a typical response would look like this:

{
    "bookmark": [
            "/grp1",
            "ONLINE",
            true,
            "2019-08-20T15:05:58.047Z",
            "urn:lo:nsid:myNs:myId"
    ],
    "devices": [
      {
         "id": "urn:lo:nsid:sensor:temp001",
         "name": "mySensor001",
         "description": <<some description>>,
         "activities": [
            {
             "ruleId": "e26309b1-3bb1-4ac6-929b-50d364188c7e",
             "state": "SILENT"
            }
         ],
         "aggregatedActivityState": "SILENT",
         "tags": ["Lyon", "Test"],
         "properties" : {
             <<key>>: <<value>>
         },
         "group": {
             "id": <<id>>,
             "path": <<myPathId>>
         },
         "interfaces": [
               {
                 "connector": <<myConnector>>,
                 "nodeId": <<interface Id>>,
                 "enabled": <<true/false>>,
                 "status": <<the status of the interface>>,
                 "lastContact": <<date>>,
                 "definition": {
                       ........to learn more, see the "Device interface representation" section
                 },
                 "activity": {},
                 "capabilities": {
                       "command": {
                          "version" : <<versionNumber>>,
                          "available": <<true/false>>
                       },
                       "configuration": {
                          "available": <<true/false>>
                       },
                       "resources": {
                          "available": <<true/false>>
                      }
                  }
               }
           ],
           "lastCommunication": <<date>>,
           "created": <<date>>,
           "updated": <<date>>,
           "location": {
               "lat": <<Latitude value>>,
               "lon": <<Longitude value>>,
               "alt": <<Altitude value>>,
               "accuracy":<<accuracy value>>,
               "provider":<<provider value>>,
               "lastUpdate": <<date>>
            },
           "network": {
               "lora": {
                   "lostMessagesRatio": <<float value>>
               }
           }
       }
    ]
}

The response contains lists of :

bookmarks : representing the indexes of the last research. These indexes follow the elements set in the sort in number and order. For example, if sort=["created","id"] then bookmark will return [<last index of created>, <last index of id>]
inventory devices with the following model description :

JSON Params	Description
id	device unique identifier (Cf. device identifier)
description	Optional. detailed description of the device
name	Optional. name of the device
tags	Optional. list of additional information used to tag device messages
properties	Optional. map of key/value string pairs detailing device properties
group	group to which the device belongs. The group is defined by its id and its path
interfaces	Optional. list of device network interfaces (Cf. interface object model)
lastCommunication	Optional. last communication date of the device. Latest date between data message created and interface last contact
created	creation date of the device
updated	last update date of the device
activities	Optional. device activities with state of its activity rule
aggregatedActivityState	Optional. device aggregated activity state of 'activities' field (Cf. aggregated activity state)
location	Optional. the last location of the device returned by data after data message enrichment process.
network	Optional. the last network traffic information relative to the device

JSON Params

Description

device unique identifier (Cf. device identifier)

description

Optional. detailed description of the device

name

Optional. name of the device

tags

Optional. list of additional information used to tag device messages

properties

Optional. map of key/value string pairs detailing device properties

group

group to which the device belongs. The group is defined by its id and its path

interfaces

Optional. list of device network interfaces (Cf. interface object model)

lastCommunication

Optional. last communication date of the device. Latest date between data message created and interface last contact

created

creation date of the device

updated

last update date of the device

activities

Optional. device activities with state of its activity rule

aggregatedActivityState

Optional. device aggregated activity state of 'activities' field (Cf. aggregated activity state)

location

Optional. the last location of the device returned by data after data message enrichment process.

network

Optional. the last network traffic information relative to the device

And for each interface the model is :

JSON Params	Description
connector	connector identifier
nodeId	interface unique identifier
enabled	define if the interface is enabled or disabled
status	interface status
definition	interface definition. The definition depends on connector.
lastContact	Optional. last contact date of the connectivity
activity	interface activity. The activity depends on connector.
capabilities	interface capabilities.
created	registration date of the interface
updated	last update date of the interface

JSON Params

Description

connector

connector identifier

nodeId

interface unique identifier

enabled

define if the interface is enabled or disabled

status

interface status

definition

interface definition. The definition depends on connector.

lastContact

Optional. last contact date of the connectivity

activity

interface activity. The activity depends on connector.

capabilities

interface capabilities.

created

registration date of the interface

updated

last update date of the interface

For more information on each connector definition, activity and status, see the appropriate section:

LoRa®, see the following section LoRa® connector.
SMS, see the following section SMS connector.
MQTT, see the following section MQTT connector.
External connector, see the following section MQTT External connector.