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 anEntitySelectionPicker
;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 thetype
of the picker is set tostring
.
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.
The ui:fieldName
property must reference a field that is in the same step of the EntitySelectionPicker.
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 anEntitySelectionPicker
;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 thedataproduct
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.
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.
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"}]
.
If the attribute path cannot be resolved in the referenced entity the EntitySelectionPicker will return an undefined value for that.