Entity Selection Picker

Overview

When you need to define a value that is not editable by the user, but is extracted from other values that the user has already selected, you can use the EntitySelectionPicker.

As an example, figure that you need to extract the owner of an entity that the user has already selected using another picker: in this case, you don't want the user to change it, but instead to inherit it from a property of the selected entity.

This picker lets you fetch an entity starting from a value of another picker and get a specific attribute of that entity. To fetch the entity for which the property should be extracted, the source picker should extract an identifier; this picker supports source identifiers with witboost URNs (e.g. urn:dmb:cmp:marketing:asdf:0:impala-cdp-output-port) as well as witboost IDs (e.g. component:marketing.asdf.0.impala-cdp-output-port) .

Configuration

This picker can be used in the following way to extract the development group of a system, by checking its spec.owner field.

developmentGroup:
  title: DevelopmentGroup
  type: string
  description: Dataproduct development group
  ui:field: EntitySelectionPicker
  ui:fieldName: dataproduct
  ui:property: spec.owner
  ui:options:
    allowArbitraryValues: false

Let's review the properties of the picker:

• type: the resulting value that we need to extract is a single string value;
• ui:field: specifies that this picker is an EntitySelectionPicker;
• ui:fieldName: this property tells the picker which other field to use as source for the extraction. In this case, this picker will load the entity identifier selected from the picker used for the field "dataproduct";
• ui:property: this specifies the path of the property that will be extracted from the resolved entity.
• ui:options: allowArbitraryValues: false: 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), this property has effect only if the type of the picker is set to string.

In this example, if the user selects the Data Product "Employees" from the picker defined for the field "dataproduct", this picker will load the entity "Employees" and will fill the "DevelopmentGroup" field with the property spec.owner of the "Employees" entity.

note

The ui:fieldName property must reference a field that is in the same step of the EntitySelectionPicker.

warning

Remember always to change the EntitySelectionPicker type according to the resolved value of ui:property. If the value extracted from the property is a string, the type of the picker should be string as well. Same thing in case the property is an array, an object, etc.

Another possible usage of the EntitySelectionPicker is in the following:

developmentGroup:
  title: DevelopmentGroup
  type: object
  description: Dataproduct development group
  ui:field: EntitySelectionPicker
  ui:fieldName: dataproduct
  mapTo:
    group: spec.owner
  ui:displayLabel: group

Let's review the properties of the picker again:

• type: the resulting value that we need to extract is a single string value;
• ui:field: specifies that the picker to use for the field "DevelopmentGroup" will be an EntitySelectionPicker;
• ui:fieldName: this property tells the picker which other field to use as source for the extraction. In this case, this picker will load the entity identifier selected from the picker used for the field "dataproduct";
• mapTo: that specifies the mapping that is applied to the resolved entities. In this example, every entity loaded from the dataproduct field will be mapped to an object composed of just one attribute called "group" which contains the spec.owner field of the entity.
• ui:displayLabel: that specifies which attribute of the mapped object will be used as a label for the field.

In this example, if the user selects the Data Product "Employees" from the picker defined for the field "dataproduct". This picker will load the entity "Employees" and will fill the "DevelopmentGroup" field with an object with just one field called "group": this filed will contain the value of the field spec.owner of the "Employees" entity.

tip

The mapTo property enables you to put mapping in a regular dot-notation.

You can specify object attribute paths, resolving a sub-field of the referenced object by using the dot-notation, e.g. spec.profile.email if you want to resolve the spec.profile.email attribute from the referenced object.

You can also reference elements inside arrays, e.g. spec.relations[0] if you want to resolve the first value of the relations array.

The two attributes path kinds can be also combined for resolving the value from an object that is in a specific array position, e.g. spec.relations[0].name if you want to resolve the name attribute of an object placed in the first position of the relation array.

caution

To avoid unexpected behaviors, it is not recommended to use the ui:property and the mapTo configurations together in the same field.

Example Use Cases

Let's suppose that a template contains two pickers: EntityPicker and EntitySelectionPicker. The second one reference the first by putting the EntityPicker field name in the source property (ui:fieldName: entityPickerFieldName) and for the mapTo property, it will take the spec.profile.email value. If the value that the user put in the field of the EntityPicker is something like user:name.surname_email.com, the EntitySelectionPicker will take the spec.profile.email field of the object corresponding to the user Entity with ref user:name.surname_email.com, i.e. the object {"email": "name.surname@email.com"}.

Example usage: IdentitiesPicker

Let's suppose that a template contains two pickers: IdentitiesPicker and EntitySelectionPicker. The second one reference the first one by putting the IdentitiesPicker field name in the source property (ui:fieldName: identitiesPickerFieldName) and for the mapTo property, it will take the spec.profile.email value. If the value that the user put in the field of the IdentitiesPicker is something like ["user:name.surname_email.com", "user:name2.surname2_email.com"], the EntitySelectionPicker will take the spec.profile.email field of the objects corresponding to the user Entities with refs user:name.surname_email.com and user:name2.surname2_email.com, i.e. a list of strings with the following values [{"email": "name.surname@email.com"}, {"email": "name2.surname2_email.com"}].

warning

If the attribute path cannot be resolved in the referenced entity the EntitySelectionPicker will return an undefined value for that.