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.