Bosch IoT Device Management

Using sorting fields via REST API

In the previous page Options when listing devices we covered the options Bosch IoT Manager provides when listing devices and groups. Here we are going to get into more detail on how to use the sorting fields in the Manager REST API, how to set up search index fields and the appropriate mapping that needs to be done for successful sorting operations.

Sorting devices and groups

The REST API for sorting of devices/gateways and groups can be used as part of these methods:

Open the method of interest and scroll down to reach the option parameter which allows you to define sorting and paging operations .

images/confluence/download/attachments/2212379576/bidm-sortingApi.png

As you already know, devices/gateways and all types of groups (directories, filter entries or tags) in the Device management layer (Bosch IoT Manager) are represented as things in the digital twin layer (Bosch IoT Things - see Devices and their digital twins).

Currently, the thing structure and the device/group structure are not identical. In particular, the device/group structure in Bosch IoT Manager has some additional elements further to the Things-related fields. There are also some differences in the naming of the fields. Here is the essential information to get your sorting operations working:

Search index fields

Each namespace has an individual search index. The search index contains the fields that should be indexed for your things of this namespace. Thus, search queries can be filtered by these fields.

The default indexable fields for Bosch IoT Device Management are:

  • _created

  • _modified

  • _revision

  • attributes

  • definition (thing definition)

  • features/*/properties/status/agentName

  • features/*/properties/status/softwareModuleType

  • policyId

  • thingId

You can set the search index fields when you create your namespace and change them at a later moment, if necessary:

images/confluence/download/attachments/2212379576/bidm_searchIndexing_namespace.png

Click the + icon to add further search index fields.

So before you perform a sorting operation, you should index the specific field that you are going to use for sorting criteria.

The indexing is happening on the Bosch IoT Things side, so if you want to sort via a device or group-related field, you should follow the mapping below and in fact, index the things translation of the specific field.

Mapping between the fields in Bosch IoT Manager and IoT Things

The search index fields that are pre-selected when creating a new namespace are typical for the thing structure.
This is why you need to consider the following mapping in order to know which things fields you need to index in order to be able to search for specific device/group fields via the Manager REST API.

This is a temporary workaround until the two structures are harmonized.

The differences that we outlined until now require a conversion between the fields in the Device management layer (Bosch IoT Manager) and the Digital twin layer (Bosch IoT Things).

The table below depicts how the mapping of fields between the two layers looks like:

Bosch IoT Manager

Bosch IoT Things

Device sorting


features/{{ feature.id }}/definitions

features/{{ feature.id }}/definition

id

thingId

identifier

thingId

identifier/id

thingId

gatewayId

attributes/Info/gatewayId

isGateway

attributes/Info/gateway

created

_created

revision

_revision

modified

_modified

Groups sorting


name

attributes/$name

path

attributes/Info/groupPath

filter

attributes/$filter

For example, sorting by isGateway in the Manager REST API is actually translated automatically to sorting by attributes/Info/gateway in Bosch IoT Things. This means that if you want to sort devices by isGateway in the Manager REST API you should add attributes/Info/gateway in the search index fields of your namespace.

images/confluence/download/attachments/2212379576/bidm-sortingApi-addIsGateway-to-namespace.png