This is an old revision of the document!
Dynamic forms (eav)
Dynamic forms are used for:
- extending standard entity attributes with custom, project specific attributes,
- dynamic configurations - e.g. system connector configurations.
Dynamic forms are supported for selected entities:
SysSystem
- linked to the systemsIdmIdentity
- identitiesIdmIdentityRole
- assigned roles to identities (respectively assigned to identity contracts)IdmIdentityContract
- Contractual relationshipsIdmRole
- rolesIdmTreeNode
- tree structure items.IdmForm
- common formsVsAccountFormValue
- virtual system attributes
Dynamic form instances (values) are saved in the individual tables according to the entity which they are linked to ⇒ which is their owner (e.g. the entity IdmIdentityFormValue
, IdmRoleFormValue
). Form values are not saved, if null
value (by persistent type) is given ⇒ filled values are saved only.
FormService
service for working with the extended attributes on the back-end. FormInstance
utility is useful on BE - contains value transformation to maps by attributes etc..
EavForm
.
Dynamic form attribute supports data types (persistentType
):
CHAR
- one characterTEXT
- strings (long text). Not indexed -SHORTTEXT
usage is preferred.SHORTTEXT
- strings (2000 chars). Indexed.INT
- integerLONG
- longDOUBLE
- saved as bigdecimalBOOLEAN
- true / false / nullDATE
- date (without time)DATETIME
- date with timeBYTEARRAY
- byte[]UUID
- uuid identifier. Indexed.ATTACHMENT
- attachment (~binary file). Read more about attachments.
persistentType
and confidential
is possible only for attributes without persisted values ⇒ when attribute is not used for some values. Data migration, when attribute's persistentType
or confidential
is changed is not supported now.
with properties:
readonly
multi values
- Is represented on the front-end by a textarea, where a line is a value (a new line separates the values). This property is supported for persistent typesCHAR
,TEXT
,INT
,LONG
,DOUBLE
andUUID
.confidential
- .The values are stored in an confidential storage). Stored values of these attributes - substitute characters only - are loaded on the front-end. The value can only be changed and determined whether it is filled in. This property is supported for persistent typesCHAR
,TEXT
,INT
,LONG
,DOUBLE
,UUID
,BYTEARRAY
.required
- value validation, read more.unique
- value validation, read more.min
- value validation, read more.max
- value validation, read more.regex
- value validation, read more.validationMessage
- custom message, when some validation fails, read more.
Dynamic form attribute can be rendered differently on frontend. Face type (faceType) property is used for choosing frontend renderer. Default renderer is chosen by persistent type (e.g. UUID → UUID).
Renderer is frontend component, superclass component AbstractFormAttributeRenderer
is used for all renderer implementations. Renderer is responsible for IdmFormValue ⇔ input value
transformation.
Renderers are registered in module's component-descriptor.js
as single component with attributes:
id
- unique component identifiertype
=form-value
- static component type is used for allform-value
rendererpersistentType
- which persistent type renderer supportsfaceType
- renderer face type ⇒ key. Unique face type should be given (by persistent type). Its optionalpersistentType
is used as default, when nofaceType
is given.component
- renderer implementation (AbstractFormAttributeRenderer
descendant).labelKey
- localization key ⇒ renderer name. Its optional,faceType
is used, when nolabelKey
is given.
All component descriptor features are supported. Read tutorial, how to create custom form attribute renderer.
Adding the support of extended attributes for a new entity
Backend
- Adding an interface implementation
FormableEntity
to the new entity, - creating a manager implementation by inheriting
AbstractFormableService
for the new entity, - creating the entity by inheriting
AbstractFormValue
, which will represent the values of extended attributes for the new entity (owner), - creating a repository by inheriting
AbstractFormValueRepository
for the values of the extended attributes, - creating the manager by inheriting
AbstractFormValueService
for the values of the extended attributes.
Frontend
- issuing a REST endpoint for saving the extended attributes from the FE - e.g.
IdmIdentityController
- controller has to evaluate security to read / save form values by their owner (e.g. by identity), - creating a service and redux manager communicating with REST by inheriting
FormableEntityManager
- e.g.IdentityManager
, - using the component
EavForm
for filling in and sending the values of the extended attributes from the FE to the BE - e.g.IdentityEav
content.
Agenda for working with forms
On the FE, there is an agenda of forms - their definition and attributes. Each definition can contain zero or more attributes. To maintain the integrity, an interface UnmodifiableEntity has been created, which allows adding a flag that the entity has been created by the system and cannot be modified (or some of its attributes) and deleted (this logic now needs to be implemented manually into the relevant controllers), for example in IdmFormAttributeController.
It is necessary to be cautious when editing individual form attributes as the logic linked to this form can be rendered non-functional.
persistentType
or confidential
is changed is not supported now.
Common forms
Common forms is used for saving internal dynamic forms for: - report filters - long running task properties (comming soon) - authorization policiy properties (comming soon)
Form has to have form definition and owner, which can be an entity implementing FormableEntity
interface. One owner can have more forms. When owner is deleted, then all forms have to be deleted to - override owner's service delete method properly. Form can be shared between owners - e.g. report filter can be used as input (properties) for long running task - this is the main reason, why common forms exists, don't use this common forms for storing extended attributes mentioned above (e.g. they will not be shown on frontend).
Localization
For form attributes is possible add localization into cs.json and en.json for each module.
spinal-case
or kebab-case
on frontend).
Example form code eu.bcvsolutions.idm.acc.entity.SysSystem will be transformed into eu-bcvsolutions-idm-acc-entity-syssystem
Read more in tutorial
Validation
For form attribute values is possible to configure prepared validations. Validation are evaluated (on the backend), when form with extended attributes is saved and sent to backend. Simple validations as required
, min
, max
are evaluated on frontend after value is changed.
Required
Value is required.
Unique
Value has to be unique.
BYTEARRAY
and ATTACHMENT
persistent types.
Min, Max
Value has to be greater than (lesser than) or equal given min
(max
) values. Real number (38,4) can be configured.
DOUBLE
, INT
, LONG
persistent types.
Regex
Value has to match given regular expression (java pattern is used).
BYTEARRAY
and ATTACHMENT
persistent types.
- GUI:
^([01]?\d\d?|2[0-4]\d|25[0-5])\.([01]?\d\d?|2[0-4]\d|25[0-5])\.([01]?\d\d?|2[0-4]\d|25[0-5])\.([01]?\d\d?|2[0-4]\d|25[0-5])$
- java:
^([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])$
Validation message
Custom validation message. If message is not defined, then default message by invalid validation type will be shown.
core:validationError.invalid.unique
). Parameters min
, max
, regex
, unique
, required
is available for localization message.
Code lists
Code list can be defined and used on frontend forms → defines options for the select box (e.g. used on role detail for the environment
attribute). Code lists items could have additional extended attributes.
Code list works as decorator only. When whole code list is deleted, then the only impact is raw item codes will be rendered on frontend ⇒ when code list or code list item is not found, then raw value (item's code) is shown instead.
CodeListManager
for creating and providing code lists and items through application on backend (e.g. available for scripts, which could be used in provisioning).
CodeListSelect
and CodeListValue
for rendering code lists on frontend.
environment.development.title
will be localized.
Authorization policies support
Identity form values can be secured by authorization policies - see how to configure authorization policies, when some identity extended attributes have to be secured.
Attachments
Attachments can be uploaded for the attributes with persistent type ATTACHMENT
. Attachment is uploaded immediately after user selects file from his file system - attachment is uploaded as temporary to server and it's identifier is used as extended attribute value. Extended attribute can be saved then (when whole extended form is submitted).
Attachment can be downloaded from frontend. If attachment is picture (~ attachment mime type starts with image/*
), then preview of saved extended attribute's attachment is available directly in extended attribute form.
Download and preview is supported for agendas (entity types): identity, role, tree node, contract and contract slice ⇒ role requests (role lifecycle) and identity roles (parameters for the assigned roles) are
Read more about attachments usage in the application (e.g. how to increase maximum file size).
Future development
- Form value data migration, when persistent type is changed.
- Attachment renderer: support multiple files, validation support (now is validation on input)
- Created deep copy, when form values are copied ⇒ attachment is linked to two form values and is removed, when the first one is deleted.