Entity Picker

Overview

An EntityPicker allows you to select a value amongst the available options, as shown below.

Configuration

Entity Picker options are fetched from the Witboost catalog kinds and can be filtered by kind, thus specifying the allowedKinds option under ui:options

By default, the picker is always enable, but in some use cases (associated for example with the customUrlPicker), may be necessary to have the value in the context without giving the user the possibility to modify it. In this case you could act on the ui:disabled by setting it to true.

witboost integrates a property inside EntityPicker that enables to filter the catalog entities based on the value of other fields. This property is called ui:filter and it is placed under EntityPicker or a custom picker that wraps it, in the following way:

domain:
  title: Domain
  type: string
  description: the domain this output port belongs to
  ui:field: EntityPicker
owner:
  title: Domain
  type: string
  description: the owner this output port belongs to
  ui:field: EntityPicker
dataproduct:
  title: Data Product
  type: string
  description: the Data Product this output port belongs to
  ui:field: EntityPicker
  ui:filter:
    - fieldName: domain
      entityPath: spec.domain
    - fieldName: owner
      entityPath: spec.owner
  ui:options:
    allowedKinds:
      - System

It is an array of objects which have two sub-fields:

• fieldName which indicates the name of the field from which EntityPicker is depending
• entityPath which indicates the attribute of the entity for which EntityPicker has to filter the results

These two sub-fields are mandatory to let everything works. If they are missing, EntityPicker will have its ordinary behavior and an error alert will appear.

For each object below the ui:filter property, EntityPicker just takes the values of the field name and entityPath and adds them as parameters of CatalogApi.getEntities method and so it makes a filter by using their values in AND.

The ui:filter parameters enables also reset the value of a field to which this parameter belongs to when the fields on which ui:filter depends change. This functionality works fine ONLY IF the ui:filter dependent fields and the field to which it belongs to are on the same step.

You can also exclude hardcoded values from displaying in the dropdown menu like:

domain:
  title: Domain
  type: string
  description: the Domain of the Data Product
  ui:field: EntityPicker
  ui:options:
    allowedKinds:
      - Domain
    excludeValues:
      - domain:DPU
      - domain:it

warning

If there is no data on the entity picker a warning message will be displayed to inform the user that he might be missing some permissions ('There are no results for this picker. Please make sure you have the required permissions').

Restrict the displayed users and groups

If you use the EntityPicker to select users and/or groups, you can choose to restrict the visibility of the users and groups displayed. When setting among the ui:options the value showOnlyUserOwnGroups: true, when using the template the user will see:

• only groups he/she belongs to if the allowedKinds contains the Group value
• only users that are members of the groups the current user belongs to, if the allowedKinds contains the User value

An example of the showOnlyUserOwnGroups could be:

dataProductOwnerFiltered:
  title: Data Product Owner
  type: string
  description: User who owns the Data Product
  ui:field: EntityPicker
  ui:options:
    showOnlyUserOwnGroups: true
    allowArbitraryValues: false
    allowedKinds:
      - User

In this case, the user can select as data product owner, only users that are members of groups he/she belongs to.

Use together with DescriptorPicker

In case you want to let the users select an entity from a list and then present the users with a list of options derived from that choice, you can leverage the EntityPicker to load a descriptor into the context, so that the DescriptorPicker uses it.

To do so, just configure the EntityPicker to store a full descriptor when users select an option, like this:

# in your template.yaml
spec:
  parameters:
    - title: Step one
      properties:
        # other fields goes here...
        sourceDescriptor:
          type: object # note that this is not anymore 'string' but 'object'
          title: Source Descriptor
          description: A source descriptor to be stored in the formContext
          ui:field: EntityPicker
          ui:options:
            # other options
            storeRawEntity: true # this is the key property that does the magic

Then, with the DescriptorPicker you can present options to users in this way:

# in your template.yaml
spec:
  parameters:
    - title: Step one
      properties:
        sourceDescriptor:
          type: object
          title: Source Descriptor
          description: A source descriptor to be stored in the formContext
          ui:field: EntityPicker
          ui:options:
            # other options
            storeRawEntity: true

        # other fields goes here...
        profile:
          type: object
          ui:field: DescriptorPicker
          title: Profile
          description: Select the profile associated to your user account
          sourceType: field
          source: sourceDescriptor # this is referring to the field above
          optionsAt: spec.mesh.profiles
          optionsDisplayNameAt: name

tip

If you just want to grab a value from the descriptor, that the user just loaded into the context, instead of presenting options to users, just use nunjucks!

With nunjucks you can manipulate the descriptor that is present in the formContext as you wish. In this example we are configuring a template to take the development group of a data product selected by the user:

# in your template.yaml
spec:
  steps:
    - id: template
      name: Fetch Skeleton + Template
      action: fetch:template
      input:
        # other input fields of the fetch:template scaffolder action...
        values:
          # other values we want to pass...
          developmentGroup: '{{ parameters.dataproduct.spec.mesh.devGroup }}'