Bosch IoT Rollouts

Target filtering

Target filters help to manage devices by grouping them according to a query. They can be used in the creation of a rollout in order to select a large number of devices which will receive the update.

How to filter

The basic syntax to filter is:

field<basic_operator>value <composite_operator> field<basic_operator>value <...>

  • field: is the name of the resource field.
    To see on which target fields filtering is possible, see Entity definitions and have a look to the column “Filter Parameter” of the common and target table.

  • value: is the value of the target field

    • Use * for wildcard matches.

  • <basic_operator>: Are operators to do simple queries.
    Supported basic operators are:

    • == : equal

    • != : not equal

  • Use =IN= for 'in' parameter.(Example: name=IN=(target1,target2).

  • <composite_operator>: Are operators to join simple queries.
    Supported composite operators are:

    • and

    • or

If you are using Bosch IoT Rollouts as part of your Bosch IoT Device Management subscription, you will not be able to filter your targets by update status, description and by some other filtering criteria. There are also some differences in the way how the query has to be constructed.
For details, please read here.

Virtual property replacement

Some properties relevant for building filter queries do not have a representation in the database.

They have to be specified as placeholders (e.g. ${SOME_PLACEHOLDER}) and will be expanded on Java-side before the filter query is passed to the database.

The syntax is '${' + 'theNameOfTheVirtualProperty' + '}'. It is possible to escape a placeholder with another leading '$': $${SOME_PLACEHOLDER} would prevent the expand-mechanism.

Currently, the following virtual properties are available:

  • NOW_TS: The current UTC system time in milliseconds since Unix epoch.

  • OVERDUE_TS: The latest point in time a targets poll message is (or was) expected to be not overdue (in milliseconds since Unix epoch). The calculation rule is as follows:

    • OVERDUE_TS = NOW_TS - POLL_INTERVAL - POLL_OVERDUE_INTERVAL (POLL_INTERVAL and POLL_OVERDUE_INTERVAL are configured per tenant)

Examples

Custom query

Description

name==*

Gives all targets.

updatestatus==error

Gives all targets in ‘error’ state.

controllerId!=192.168.2.42

Gives all targets that don’t have the controllerId 192.168.2.42.

name==*CCU*

Gives all targets which contain the term ‘CCU’ in their name.

name==*CCU* or description==*CCU*

Gives all targets that either have the term ‘CCU’ in their name or description.

name==*SHC* and description==*SHC*

Gives all targets that have the term SHC in their name and description.

name==CCU* and updatestatus==pending

Gives all targets with a name starting with ‘CCU’ and in ‘pending’ state.

(assignedds.name==‘ECU-DS’ and description==test) or updatestatus!=error

Gives all targets which are either assigned to ‘ECU-DS’ and have description equals to ‘test’ or which are not in error status.

(updatestatus!=In_sync or updatestatus!=error) and name==*SHC1*

Gives all targets that don’t have the updatestatus In_sync or error and that contain the term SHC1 in their name.

(updatestatus!=error or updatestatus!=pending) and (name==*CCU* or description==*CCU*)

Gives all targets that either have the term ‘CCU’ in their name or description and that either have the update status not in state error or pending.

lastControllerRequestAt=le=${OVERDUE_TS}

Gives all targets that are overdue.

lastControllerRequestAt=ge=${OVERDUE_TS}

Gives all targets which are not overdue (i.e. were online recently).

installedds.name==MyDS and installedds.version==1.0.0

Gives all targets which have distribution set ‘MyDS’ with version ‘1.0.0’ installed.

attribute.isoCode=in=(CN,DE,US)

Gives all targets which have a controller attribute ‘isoCode’ with the value ‘CN’, ‘DE’, or ‘US’.

attribute.hw.rev==1.0

Gives all targets which have a controller attribute ‘hw.rev’ with the value ‘1.0’.

Please note that everything after ‘attribute.’ is treated as the name of the attribute key. Therefore a ‘*’ or ‘.’ right after ‘attribute.’ would search for a attribute key with name ‘*’ or ‘.’ and especially ‘*’ is not treated as wildcard in key names but as part of the name instead.

tag=in=(test,qa)

Gives all targets which are tagged with ‘test’ or ‘qa’.

tag=out=test

Gives all targets which are not tagged with ‘test’.

metadata.mode==debug

Gives all targets which have the metadata parameter with key ‘mode’ and value ‘debug’.

metadata.hw.rev==1.0

Gives all targets which have the metadata parameter with key ‘hw.rev’ and value ‘1.0’.

Please note that everything after ‘metadata.’ is treated as the name of the metadata key. Therefore a ‘*’ or ‘.’ right after ‘metadata.’ would search for a metadata key with name ‘*’ or ‘.’ and especially ‘*’ is not treated as wildcard in key names but as part of the name instead.