Bosch IoT Rollouts Documentation

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:

    • == : Filters Targets where the specified field matches the given value.

    • != : Filters Targets where the specified field does not match the given value.

      For Metadata/Attribute fields (Map)

      Example: attribute.MY_CUSTOM_ATTRIBUTE != MY_CUSTOM_VALUE

      Will be included only these Targets       attribute.MY_CUSTOM_ATTRIBUTE exists And value is not equal to the query value.
             Targets that do not have attribute.MY_CUSTOM_ATTRIBUTE at all, will not be included.


    • =in= : Filters Targets where the specified field matches any value from the provided list.

    • =out= : Filters Targets where the specified field is not in the provided value list

      For Metadata/Attribute fields (Map)

      Example: attribute.MY_CUSTOM_ATTRIBUTE =out= (MY_CUSTOM_VALUE1, MY_CUSTOM_VALUE2

      Will be included only these that have attribute.MY_CUSTOM_ATTRIBUTE And value is not in the provided value list
      Targets that do not have attribute.MY_CUSTOM_ATTRIBUTE at all, will not be included

    • =is=null : Filters Targets that given field is missing

    • =not=null : Filters Targets that given field is present with some value

  • <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 that 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 that a name starting with ‘CCU’ and in ‘pending’ state.

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

Gives all targets that 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 that are not overdue (i.e. were online recently).

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

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

tag=in=(test,qa)

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

tag=out=(test,qa)

Gives all targets that are not tagged with ‘test’ or 'qa'.

Includes Targets that do not have tag at all

tag=is=null

Gives all targets that do not have any tags.

tag=not=null

Gives all targets that have at least one tag.

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.

attribute.isoCode==CN

Gives all targets which have a controller attribute 'isoCode' with the value 'CN'

attribute.isoCode!=CN

Gives all targets which have a controller attribute 'isoCode' with value different than 'CN'

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

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

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

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

attribute.isoCode=is=null

Gives all targets that does not have a controller attribute 'isoCode' at all.

attribute.isoCode=not=null

Gives all targets that have a controller attribute 'isoCode' with any value.

metadata.hw.rev==1.0

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

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.

metadata.mode==debug

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

metadata.mode!=debug

Gives all targets that have the metadata parameter with key ‘mode’ and value is different than ‘debug’.

metadata.mode=in=(debug,trace)

Gives all targets that have the metadata parameter with key 'mode' and value is either 'debug' or 'trace'

metadata.mode=out=(debug,trace)

Gives all targets that have the metadata parameter with key 'mode' and value is different than 'debug' or 'trace'

metadata.mode=is=null

Gives all targets that have the do not have metadata parameter with key 'mode' at all

metadata.mode=not=null

Gives all targets that have the metadata parameter with key 'mode' with some value.