Target Filters View
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 manage auto assign distribution set of 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, go to 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
- <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
- Use =IN= for ‘in’ parameter.(Example: name=IN=(target1,target2).
- Use * for wildcard matches.
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 there name. |
| name==*CCU* or description==*CCU* | Gives all targets that either have the term ‘CCU’ in there name or there description. |
| name==*SHC* and description==*SHC* | Gives all targets that have the term SHC in there name and there description. |
| name==CCU* and updatestatus==pending | Gives all targets with there 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 contains the term SHC1 in there name. |
| (updatestatus!=error or updatestatus!=pending) and (name==*CCU* or description==*CCU*) | Gives all targets that either have the term ‘CCU’ in there name or there 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’. |
| 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’. |
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, dropdown list supports filtering in order to facilitate the search of the distribution set for auto-assignment.
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.
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 the security chapter for further information about available roles and their included permissions.