Skip to main content

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 Entity Search Picker configurations are defined under ui:options field. Within this last field, you can define the entities property which is a list of objects that are used to configure the Entity Providers.

The root configuration to use is the following:

entitySearchPicker:
title: Entity Search Picker
ui:field: EntitySearchPicker
ui:options:
entities:
# the list of Entity Providers goes here

Entity Provider

The Entity Provider is a component used in the EntitySearchPicker that is responsible to fetch, filter and render all the data of a specific kind. The generic configuration you can use to define an Entity Provider is the following:

multiSelection: true # see "Selection Mode" section
kind: ${ENTITY_KIND} # the kind of data the Entity Provider is handling (see "Entity Types" section below)
displayField: ${OBJECT_PROPERTY} # the property of the object to show in the EntitySearchPicker after a selection (see "Entities Configuration" section)
returnField: ${RETURNING_FIELD} # "urn", "ref" or "full", it corresponds to the value to be saved in the final catalog-info.yaml file
userFilters: ${FILTERS_LIST} # a list of filters that can be used in the EntitySearchPicker to filter values
filter:
practiceShaper:
kind: ${PRE_FILTER} # it contains a string value used to pre-filter data before rendering the EntitySearchPicker. This value depends on the selected Entity Provider (see "Pre-filtering" section under "Entity Configurations")
columns: # a list of objects describing the columns to display in the table (see "Displayable Columns in the Selection Table" section)

Selection Mode

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

    EntitySearchPicker single selection field

    EntitySearchPicker single selection dialog

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

    EntitySearchPicker multiple selection field

    EntitySearchPicker multiple selection dialog

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 selectable items. 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 Provider Types

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

  • Domains
  • Systems
  • Resources
  • Consumables

It is possible to choose your entities under the ui:options parameter with entities attribute. There you can set 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 window. The entity kind is used as a fallback. For example:

displayName: Consumables

EntitySearchPicker single selection field

  1. Display field

It defines which property 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 or name for Consumable Provider.

  1. Return field

With this configuration, it is possible to 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"
    }
    }
    }

    or for Consumable object:

    {
    "_computedInfo": {
    "urn": "urn:dmb:cmp:sub-domain-a:dpwithimpala:0:s3-cdp-output-portasdasd-6",
    "domain": {
    "id": "urn:dmb:dmn:subdomaina",
    "name": "sub-domain-A"
    },
    "system": {
    "id": "urn:dmb:dp:sub-domain-a:dpwithimpala:0",
    "name": "DPWithImpala"
    }
    },
    "id": "urn:dmb:cmp:sub-domain-a:dpwithimpala:0:s3-cdp-output-portasdasd-6",
    "kind": "outputport",
    "name": "S3 CDP Output Portasdasd 6",
    "tags": [],
    "text": "",
    "title": "S3 CDP Output Portasdasd 6",
    "domain": "sub-domain-A",
    "version": "0.0.0",
    "location": "urn:dmb:cmp:sub-domain-a:dpwithimpala:0:s3-cdp-output-portasdasd-6",
    "platform": "CDP on AWS",
    "specific": {
    "acl": {
    "users": [],
    "owners": []
    },
    "bucket": "asdasd",
    "folder": "asdasd",
    "cdpEnvironment": "asdasd"
    },
    "dependsOn": [],
    "startDate": "2023-09-28T11:02:24.233Z",
    "documentId": "urn:dmb:cmp:sub-domain-a:dpwithimpala:0:s3-cdp-output-portasdasd-6:dev",
    "sampleData": {},
    "technology": "S3",
    "description": "asdasd",
    "environment": "dev",
    "creationDate": "2023-09-28T11:02:24.233Z",
    "dataContract": {
    "SLA": {
    "upTime": null,
    "timeliness": null,
    "intervalOfChange": null
    },
    "schema": [],
    "endpoint": null,
    "termsAndConditions": null
    },
    "outputPortType": "Files",
    "semanticLinking": [],
    "deploymentUnitId": "urn:dmb:dp:sub-domain-a:dpwithimpala:0",
    "useCaseTemplateId": "urn:dmb:utm:aws-cdp-outputport-s3-template:0.0.0",
    "fullyQualifiedName": null,
    "processDescription": null,
    "dataSharingAgreements": {
    "billing": null,
    "purpose": null,
    "security": null,
    "lifeCycle": null,
    "limitations": null,
    "intendedUsage": null,
    "confidentiality": null
    },
    "infrastructureTemplateId": "urn:dmb:itm:aws-cdp-outputport-s3-provisioner:0"
    }
warning

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

  1. Pre-Filtering

Usually, you would like to limit the values that the user can select. 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 the ones defined in the Practice Shaper, or among domains that are instances of a particular DomainType. 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:

OptionTypeDescription
kindstringOne 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.
compatibleWithTypestring[](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.
instanceOfstring[](Required when kind is instanceOf) Reference of a DomainType in the Practice Shaper. Filters domain instances that are instances of the provided type.

Examples:

  • compatibleWithCurrentTemplate pre-filter:

    Let's imagine the Domain Entity Provider is used in a template that generates an Output Port (generates: componenttype:default/outputport). If no pre-filter is present or only the compatibleWithCurrentTemplate pre-fillter is set, the end user will see only the domain the Output Port is binded to, or, if no domain is found for that Output Port, it will be showed only the domain binded to the Output Port's system.

    The pre-filter to set will be the following:

    filter:
    practiceShaper:
    kind: compatibleWithCurrentTemplate
  • compatibleWithType pre-filter:

    If you want to specify a ComponentType or SystemType the domain must be binded to, you can do it by using the following configuration:

    filter:
    practiceShaper:
    kind: compatibleWithType
    compatibleWithType:
    - componenttype:default/outputport
    - systemtype:default/project

    In this way, there will be shown only the domain instances binded to the 'Output Port' component type and 'Project' system type.

  • instanceOf pre-filter:

    If you want to specify a list of DomainTypes to be instantiated by domain instances, you can do it with the following configuration:

    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:

OptionTypeDescription
kindstringOne 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.
canBeParentOfTypestring[]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.
instanceOfstring[]Reference of a SystemType in the Practice Shaper. Filters system instances that are instances of the provided type.

Examples:

  • canBeParentOfCurrentInstance pre-filter:

    Let's imagine the System Entity Provider is used in a template that generates an Output Port (generates: componenttype:default/outputport). If no pre-filter is present or just the canBeParentOfCurrentInstance pre-filter is set, the end user will see only the system the Output Port is binded to.

    filter:
    practiceShaper:
    kind: canBeParentOfCurrentInstance
  • canBeParentOfType pre-filter:

    If you want to specify a ComponentType the system must be binded to, you can do it by using the following configuration:

    filter:
    practiceShaper:
    kind: canBeParentOfType
    canBeParentOfType:
    - componenttype:default/project-component
  • instanceOf pre-filter:

    If you want to specify a list of SystemTypes the systems must be instance of, you can do it with the following configuration:

    filter:
    practiceShaper:
    kind: instanceOf
    instanceOf:
    - systemtype:default/dataproduct

Consumable

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

OptionTypeDescription
kindstringOne 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
canBeReadFromstringAccepts 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:

  • canBeReadFromCurrentInstance pre-filter:

    Let's imagine the Consumable Entity Provider is used in a template that generates an Output Port (generates: componenttype:default/outputport). If no pre-filter is present or just the canBeReadFromCurrentInstance pre-fillter is set, you will see only the components/sub-components instances the Output Port can read from.

    filter:
    practiceShaper:
    kind: canBeReadFromCurrentInstance
  • canBeReadFrom pre-filter:

    If you want to specify a ComponentType from which component instances can read, you can do it by using the following configuration:

    filter:
    practiceShaper:
    kind: canBeReadFrom
    canBeReadFrom: componenttype:default/outputport

    In the above example, the componenttype:default/outputport reads from two other ComponentTypes: componenttype:default/workload and componenttype:default/storage. Consequently, you will see in the EntitySearchPciker only the components that are instances of the before-mentioned types and that are consumable too.

  1. 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 elements matching with spec.mesh.name, metadata.name or name; this filter is available to all the Entity Providers. EntitySearchPicker search filter
  • domain: filter elements matching the domain property; this filter is available to System and Consumable Entity Providers. EntitySearchPicker single selection field
  • type: filter elements matching the type property; this filter is available only to System Entity Provider. EntitySearchPicker single selection field
  • system: filter elements matching the selected system URN property; this filter is available only to Consumable Entity Provider. EntitySearchPicker single selection field
  • environment: filter elements matching the environment property; this filter is available only to Consumable Entity Provider. EntitySearchPicker single selection field
warning

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

  1. 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 %}'

Migration

This section is intended to help you in migrating the current instances of the ReadsFromPicker and EntityPicker to the new EntitySearchPicker. Consider also to migrate the before-mentioned pickers also in the edit-template to be consistent.

Entity Picker - Domain field

The EntityPicker used with domain type can be replaced safely with the following configuration:

domain:
title: Domain
type: string
description: The Domain of the Data Product.
ui:field: EntitySearchPicker
ui:options:
multiSelection: false
entities:
- type: Domain
displayName: Domain
displayField: '{{spec.mesh.name}}'
returnField: ref
userFilters:
- search
filter:
practiceShaper:
kind: compatibleWithType
compatibleWithType:
- systemtype:default/dataproduct
columns:
- name: name
path: '{{metadata.name}}'
- name: description
value: description

Entity Picker - System field

The EntityPicker used with system type can be replaced safely with the following configuration:

dataproduct:
title: Data Product
description: Data Product
ui:field: EntitySearchPicker
ui:options:
multiSelection: false
entities:
- type: System
displayField: '{{spec.mesh.name}}'
returnField: ref
filter:
practiceShaper:
kind: instanceOf
instanceOf:
- systemtype:default/dataproduct
userFilters:
- search
- domain
- type
columns:
- name: name
path: '{{spec.mesh.name}}'
- name: owner
path: '{{spec.owner}}'

ReadsFrom Picker

The readsFrom Picker can be replaced with the following configuration:

readsFrom:
title: Reads from
type: array
ui:field: EntitySearchPicker
ui:options:
multiSelection: true
entities:
- type: Consumable
displayField: '{{name}}'
returnField: urn
filter:
practiceShaper:
kind: canBeReadFrom
canBeReadFrom: componenttype:default/outputport
userFilters:
- search
- domain
- system
- environment
columns:
- name: name
path: '{{name}}'
- type: Resource
displayName: Resource
displayField: '{{spec.mesh.name}}'
returnField: urn
userFilters:
- search
columns:
- name: name
path: '{{metadata.name}}'