Extension 2.0 Screens - How to add filtering

[Radu]

Use case: Enabling filtering and filter bars to entity lists of screens created from an Extension 2.0 YAML.

Example context: I have an entity type "my:interface" that has a RUNS_ON relationship to an entity type "my:device". I have an Entities List card which already lists all "my:interface" entities I want to filter.

All definitions are given based on schema version 1.239 and may or may not change in the future.

Example 1: I want to filter my list by the interface names.
YAML definition:

filtering:
  entityFilters:
    - displayName: Interface
      filters:
        - type: entityName
          displayName: Name
          freeText: true
          modifier: contains
          defaultSearch: true
          distinct: false
          entityTypes:
            - my:interface

YAML explanation:

• filtering - the block which defines the filtering capability
• entityFilters - the block which defines the groups of filters (these are displayed slightly greyed out in the filtering list)
• filters - the actual filters that are part of this group
  
  • displayName - how this filter is labelled within the UI
    
  • type - must reference an attribute of the entity you are filtering. Note: every entity has entityName as a default attribute.
  • freeText - if true, the user can freely type text; otherwise they must select from a list of suggestions. Note: only default attributes such as entityName are capable of offering list of suggestions.
  • modifier - when freeText is true, this defines how the text should be matched against the attribute. When freeText is false, this must be omitted. Note: all non-default attributes must match as "equals" regardless of this option.
  • defaultSearch - when true, if the user starts typing without selecting a filter first, this filter will be selected by default. Only one filter within the filtering block may have this enabled.
  • distinct - when true, only one instance of this filter can be applied
  • entityTypes - A mandatory list of entity types that this filter applies to. If you omit this, your filtering bar will just show a spinning wheel because of the incomplete definition.

Example 2: Given example 1, I also want to filter by the device these interfaces are running on

YAML definition:

filtering:
  relationships:
    - type(my:device),toRelationships.runsOn($(entityConditions))
  entityFilters:
    - displayName: Interface
      filters:
        - type: entityName
          displayName: Name
          freeText: true
          modifier: contains
          defaultSearch: true
          distinct: false
          entityTypes:
            - my:interface
    - displayName: Related entity
      filters:
        - type: entityName
          displayName: Device name
          freeText: false
          defaultSearch: false
          distinct: true
          entityTypes:
            - my:device          

YAML Explanation:

Most of the definition is the same as above. Changes include:

• filters
  • entityTypes - For the second filter, this is now "my:device". This is because despite filtering a list of interfaces, the filter attribute belongs to devices.
• relationships
  • any entity that is not directly part of the entity list must have a relationship defined to the listed entity for it to be considered. $(entityConditions) here resolves to each of the "my:interface" entities.

[ChadTurner]

Great Tip @Radu 

[patrik_steuer]

Thanks @Radu  for the infos, especially about ommiting the freeText field for equals modifiers is valueable, since I couldn't figure out the reason for the error message 

dtcli.utils.ExtensionValidationError: {"error":{"code":400,"message":"Validation errors for asset node:host:\nGiven property 'modifier' with value: 'equals' should not be set as its precondition is not satisfied\n","constraintViolations":[]}}

However with Schema version 1.263 I now receive following error, indicating that freeText is mandory:

dtcli.utils.ExtensionValidationError: {"error":{"code":400,"message":"Extension validation error","constraintViolations":[{"path":"$.screens[1].entitiesListCards[0].filtering.entityFilters[0].filters[4]","message":"$.screens[1].entitiesListCards[0].filtering.entityFilters[0].filters[4].freeText: is missing but it is required","parameterLocation":"PAYLOAD_BODY","location":null}]}

So it seems that this is a chicken/egg problem do you have an idea how to solve this?

Something I also recognized is that the contains modifier is only suitable for entity names, other attributes can not make use of it. 

[Radu]

I believe freeText must always be present with either true or false value. It cannot be omitted. With relation to modifiers, this still is the case - if freeText = false, then you should not specify modifier.
As for the attributes, it is only the special - entityName, ipAddress (a.k.a. dt.ip_addresses), listenPort (a.k.a. dt.listen_ports), and dnsName (dt.dns_names) - that support suggestions in the UI.

[patrik_steuer]

Another remark, it would be great to have the possibility to filter by health state, so that you can focus on not healthy entities. 

[Radu]

Please post it as a product idea in the dedicated forum here

[patrik_steuer]

Do you know if it is possible to not only use attributes, but also tags for filtering? 

[Radu]

Only attributes are supported currently. Any other suggestions you can post as product ideas on the dedicated forum.

[patrik_steuer]

Currently supported attributes for filtering on generic entities are the same as of other CUSTOM_DEVICES:

- dt.security_context
- entityName
- healthState
- ipAddress
- mzId
- mzName
- softwareTechnologies
- softwareTechnologies.version
- tag

 An endpoint is available under /rest/v2/entities/suggest, which can be used to query the available filters for an entity by providing an entity selector. Copy the request from your browser dev tools and adapt it as needed if you want to check it on your own.