Target filters view
Table of contents:
Purpose
Custom target filter overview and filter management.
Features explained
Custom target filters allow the user to filter targets by a defined custom query.
Displays a custom target filter list that can be searched by the user for any particular filter.
Create, update and delete operations are supported for target filters.
User can auto assign distribution sets to a target filter.
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. |
Auto assignment
Every target filter can have an associated distribution set for auto assignment. If auto assignment is enabled for a filter, all matching targets will get the corresponding distribution set automatically assigned. This applies to targets that are currently registered in the system as well as to new registered targets later on.
The list of custom target filters contains the column “Auto assignment”. For a target filter it can display none or name and version of the selected distribution set (in case of forced autoassignment the thunderbolt icon is shown on the left handside, and the download icon in the case of download only assignments).
Clicking on the cell text will show the “Select auto assignment distribution set” window. It allows the user to enable auto assignment, select the action type (Forced, Soft, or Download Only) and one of the valid (having the required software modules assigned and not soft deleted) distribution sets from the dropdown list. In addition, a dropdown list supports filtering in order to facilitate the search of the distribution set for auto-assignment.
If the user consent flow feature has been enabled for the tenant, this window will show an additional checkbox for Confirmation required, activated by default. Find more details about such a scenario here.
When the user has enabled auto assignment, chosen a distribution set together with action type and has clicked on save, a confirmation dialog appears, telling the user how many targets are going to be assigned with the selected distribution set.
How auto assignment works
A scheduler is running in the background that checks all target filters that have auto assignment enabled. As soon as a matching target is found which never had the distribution set assigned before, it will retrieve a new assignment to the distribution set defined by the filter.
Be aware: In case multiple target filters with different distribution sets will match the same targets, the order of distribution set assignments is unpredictable. But for sure there will be multiple assignments taking place until all different distribution sets were assigned to the target once. This might result in unexpected target updates. It is not recommended to have multiple target filters with auto assignment that match the same targets.
If the user consent flow feature has been enabled for the tenant, the triggered assignments will become RUNNING only after the end user of the targets has confirmed his or her consent to proceed with the update. Read more here.
Permissions
You need the following permissions to see the Target Filters view in:
read-only access mode: READ_TARGET, READ_REPOSITORY
full access mode: READ_TARGET, CREATE_TARGET, UPDATE_TARGET, DELETE_TARGET, READ_REPOSITORY, READ_TARGET_SEC_TOKEN
The cloud user has full access by default for all available service plans.
See Authentication and authorization for further information about available roles and their included permissions.
Auto assignment with enabled user consent flow
If the user consent flow feature has been enabled for the tenant, the “Select auto assignment distribution set” window (explained above) will show an additional field called Confirmation required with a check-mark selected by default.
In that case, every time a distribution set is auto-assigned to a target matching the target filter, the end user of the device (target) will be asked to confirm that he or she wants to proceed with the update.
Therefore, the corresponding action will be assigned a WAIT_FOR_CONFIRMATION state until such a confirmation is granted. After confirmation is granted, the action will move to a RUNNING state and will proceed according to the default behavior. Find out more in Action state machine.
The Confirmation required check-mark can also be removed for the respective auto-assignment.
In that case the confirmation will still be required and not skipped, as the user consent flow feature is enabled for the whole tenant. However, the action will be treated as directly confirmed by the operator (the current user), and the action will move from WAIT_FOR_CONFIRMATION state to a RUNNING state automatically.
A use case for removing this check-mark could be a test assignment or a confirmation granted remotely to the operator in a phone call with the end user of the respective devices.
When the auto-assignment is enabled and the confirmation required check-mark is selected, there is an additional green user icon to indicate that a confirmation is pending.
When the auto-assignment is enabled and the confirmation required check-mark is removed, there is an additional red user icon to indicate that this is an exception and a confirmation is not required because it is treated as granted by the user who initiated the auto-assignment.
Then, the confirmation required or respectively granted by the current user will be reflected in the action history messages for each target.
