Entity Search Picker

Overview

The Entity Search Picker is a highly configurable tool designed to facilitate the selection of entities within the platform. This picker allows users to select one or more entities based on configurable criteria, making it a versatile component in various applications. This documentation outlines the configuration options, functionality, and internal workings of the Entity Picker to assist developers and template editors in implementing and utilizing the tool effectively.

Configuration

The following configuration must be set in order to start using the EntitySearchPicker:

singleEntitySearchPicker:
  title: Entity Search Picker
  ui:field: EntitySearchPicker
  ui:options:
    entities:
      - type: Domain
        displayName: Domain
        displayField: '{{spec.mesh.name}}'

The Entity Search Picker offers several configuration options that enable customization based on specific use cases:

Selection Mode

• Single Selection: The picker returns the returnField of a single selected entity.

  

  

• Multiple Selection: The picker allows the selection of multiple entities, returning a list of entity URNs.

  

  

It's possible to return the entity ref or full entity object, instead of URN, by changing the returnField in the configuration.

It is also possible to define under ui:options parameter an attribute called allowArbitraryValues, that if set to false, prevents the users from typing arbitrary values outside the list of roles. This specifies if the field can be edited manually by the user. If omitted, by default it will be false (not editable by the user).

Entity Types

The picker can be configured to allow the selection of these entities by default.

• Domains
• Systems
• Resources
• Consumable Interface

Choose your entities under the ui:options parameter with entities attribute: you can select more than one entity type, and for each one, you can define a specific configuration.

Entities Configuration

For each entity type that can be used in the picker, specific configurations are defined in the code. These include:

1. Display name

A string that defines the label shown as a prefix when an entity is selected and it's used as the name on the entity kind selector (pluralized), inside the dialog. The entity kind is used as a fallback.

2. Display field

Define which properties is shown for the selected entities. This property is processed as a Nunjucks value, so it can contain variables and expressions. It represents which label is shown for selected entities.

displayField: '{{spec.mesh.name}}'

When not defined, the field entity.spec.mesh.name is used, and in case it is not defined, the fallback value is entity.metadata.name.

3. Return field

With this configuration, you can choose which value is returned for the selected entities:

• urn: the Witboost global URN (this is the default value) e. g.: urn:dmb:dmn:finance
• ref: entity reference used inside the Builder module e. g.: domain:default/finance
• full: all properties of the object e .g.:

  {
    "apiVersion": "backstage.io/v1alpha1",
    "kind": "Domain",
    "metadata": {
      "name": "finance",
      "description": " Everything related to finance",
      "links": [
        {
          "url": "http://example.com/domain/finance",
          "title": "Finance Domain"
        }
      ]
    },
    "spec": {
      "owner": "group:datameshplatform",
      "mesh": {
        "name": "Finance"
      }
    }
  }

warning

For Consumable Interface entity type, you cannot return an entity reference, because it does not exist. If ref is selected, the Witboost global URN will be given.

4. Pre-Filtering

Usually, you will find yourself limiting the values that can be selected by the user. This can be done by defining a pre-filter for the entity type. This is useful when you want to choose among particular kinds of systems, as defined in the Practice Shaper, or among domains that are instances of a particular domain type. This is done by defining a filter object under the entity configuration.

Every entity type has its own filter options:

Domain

When you want the users to select a domain instance entity (kind: Domain) you can refine what set of domains the user can choose from. The following table describes the filter options available for Domains:

Option	Type	Description
kind	string	One of:
		- compatibleWithType - See below.
		- instanceOf - See below.
		- compatibleWithCurrentTemplate - Takes the SystemType/ComponentType reference, which is the target of the generates relation of the current creation template, and applies the same logic of compatibleWithType.
compatibleWithType	string	(Required when kind is compatibleWithType) Accepts the reference of a Practice Shaper entity type (e.g., SystemType, ComponentType). Filters domain instances whose DomainType (spec.instanceOf property) is the parent domain (directly or transitively) of the provided type.
instanceOf	string	(Required when kind is instanceOf) Reference of a DomainType in the Practice Shaper. Filters domain instances that are instances of the provided type.

Example:

filter:
  practiceShaper:
    kind: instanceOf
    instanceOf:
      - domaintype:default/department
      - domaintype:default/business-domain

System

When you want the users to select a system instance entity (kind: System) you can refine what set of systems the user can choose from. The following table describes the filter options available for Systems:

Option	Type	Description
kind	string	One of:
		canBeParentOfType - See below.
		instanceOf - See below.
		canBeParentOfCurrentInstance (Default) - Takes the ComponentType reference, target of the generates relation of the current creation template, and applies the same logic of canBeParentOfType.
canBeParentOfType	string	Accepts the reference of a ComponentType. Filters system instances whose SystemType (spec.instanceOf property) is the target of a partOf relation having as a source the provided ComponentType.
instanceOf	string	Reference of a SystemType in the Practice Shaper. Filters system instances that are instances of the provided type.

Example:

filter:
  practiceShaper:
    kind: canBeParentOfCurrentInstance

Consumable Interface

When you want the users to select a consumable interface instance entity (kind: ConsumableInterface) you can refine what set of component the user can choose from. The following table describes the filter options available:

Option	Type	Description
kind	string	One of:
		canBeReadFrom - See below.
		canBeReadFromCurrentInstance (Default) - Takes the ComponentType reference, target of the the generates relation of the current creation template, and applies the same logic of canBeReadFrom
canBeReadFrom	string	Accepts the reference of a ComponentType. Filters consumable components and subcomponents whose type is one among the resource types readable from the provided component type, based on the Practice Shaper.

Example:

filter:
  practiceShaper:
    kind: canBeReadFromCurrentInstance

5. Filters Usable by End Users

These are the filters that end users can apply to refine their selection within the user interface. The template developer can choose which filters to make available to end users. Common filters include:

• search: filter element matching user string with spec.mesh.name and/or metadata.name

Example:

userFilters:
  - search

Additionally when selecting a System, these filters are also available:

• domain: choose one domain from all Catalog domains
• type: choose one type from Practice Shaper resource types

warning

By default, no filters are shown, if not specified.

6. Displayable Columns in the Selection Table

Template developers can choose to display a set of columns in the entity selection table. This customization enhances the user's ability to view pertinent information. You can show any number of additional columns by referencing fields of the selected entity (even using Nunjucks to perform transformations).

To define the additional columns, you can leverage the following configuration fields:

• name to define the column name displayed in the table.
• path to define which value to show. The values in double brackets will be resolved with the values from the entity using Nunjucks. It is important to enforce the string type for this field inside the yaml by using the single quotes as shown to avoid errors.
• value that can be used as an alternative to path to choose among two default values: name and description. These are shortcuts for the most common fields to display.

Example:

columns:
  - name: name
    path: '{% if spec.mesh.name %}{{spec.mesh.name}}{% else %}{{metadata.name}}{% endif %}'
  - name: description
    value: description
  - name: owner
    path: '{{spec.owner}}'
  - name: tags
    path: '{% for tag in spec.mesh.tags %}{{tag.tagFQN}}{{', ' if not loop.last }}{% endfor %}'

Example Use Cases

Here are a few examples illustrating how the Entity Search Picker can be configured and utilized in real-world scenarios:

Single Selection

In this example, it's possible to select one entity among Domain, Resource, and System.

singleEntitySearchPicker:
  title: Entity Search Picker
  description: single entity search
  ui:field: EntitySearchPicker
  ui:options:
    multiSelection: false
    entities:
      - type: Domain
        displayName: Domain
        displayField: '{{spec.mesh.name}}'
        returnField: urn
        userFilters:
          - search
        columns:
          - name: name
            path: '{{spec.mesh.name}}'
          - name: description
            value: description
      - type: Resource
        displayName: Resource
        displayField: '{{spec.mesh.name}}'
        returnField: urn
        userFilters:
          - search
        columns:
          - name: name
            path: '{{metadata.name}}'
      - type: System
        displayField: '{{spec.mesh.name}}'
        returnField: ref
        filter:
          practiceShaper:
            kind: canBeParentOfCurrentInstance
        userFilters:
          - search
          - domain
          - type
        columns:
          - name: name
            path: '{{spec.mesh.name}}'
          - name: owner
            path: '{{spec.owner}}'

Multiple Selection

In this example, it's possible to select more entities between Domain and System.

multipleEntitySearchPicker:
  title: Multiple Entity Search Picker
  description: multiple Entity Search
  ui:field: EntitySearchPicker
  ui:options:
    multiSelection: true
    entities:
      - type: Domain
        displayName: Domains
        displayField: '{{spec.mesh.name}}'
        returnField: ref
        filter:
          practiceShaper:
            kind: instanceOf
            instanceOf:
              - domaintype:default/department
              - domaintype:default/business-domain
        userFilters:
          - search
      - type: System
        displayName: Systems
        displayField: '{{spec.mesh.name}}'
        returnField: full
        userFilters:
          - type
        columns:
          - name: name
            value: name
          - name: tags
            path: '{% for tag in spec.mesh.tags %}{{tag.tagFQN}}{{", " if not loop.last }}{% endfor %}'