9.1:documentation:application_configuration:dev:dynamic-forms

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 systems
  • IdmIdentity - identities
  • IdmIdentityContract - Contractual relationships
  • IdmRole - roles
  • IdmTreeNode - tree structure items.
  • IdmForm - common forms
  • VsAccountFormValue - 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..
On the front-end, the editing of dynamic forms is done by the component EavForm.

Dynamic form attribute supports data types (persistentType):

  • CHAR - one character
  • TEXT - strings (long text). Not indexed - SHORTTEXT usage is preferred.
  • SHORTTEXT - strings (2000 chars). Indexed.
  • INT - integer
  • LONG - long
  • DOUBLE - saved as bigdecimal
  • BOOLEAN - true / false / null
  • DATE - date (without time)
  • DATETIME - date with time
  • BYTEARRAY - byte[]
  • UUID - uuid identifier. Indexed.

with properties:

  • required
  • 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 types CHAR, TEXT, INT, LONG, DOUBLE and UUID.
  • 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 types CHAR, TEXT, INT, LONG, DOUBLE, UUID, BYTEARRAY.

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 identifier
  • type = form-value - static component type is used for all form-value renderer
  • persistentType - which persistent type renderer supports
  • faceType - renderer face type ⇒ key. Unique face type should be given (by persistent type). Its optional persistentType is used as default, when no faceType is given.
  • component - renderer implementation (AbstractFormAttributeRenderer descendant).
  • labelKey - localization key ⇒ renderer name. Its optional, faceType is used, when no labelKey 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.

Data migration, when attribute's 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.

Beware, form type, form code and attribute code is used for compose key for localization and in the string will by replaced all special characters (white spaces, dots, colons etc.) by dash (spinal-case or kebab-case on frontend).
New tab on form definition detail can be used for creating localization.

Example form code eu.bcvsolutions.idm.acc.entity.SysSystem will be transformed into eu-bcvsolutions-idm-acc-entity-syssystem

Read more in tutorial

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.

Only identity extended attribute values support authorization policies. Support for other entities can be added in future.

Future development

  • API for saving the owner and the eav form in one transaction (⇒ save IdmFormInstance).
  • Attribute properties validation - by supported persistent type (see above).
  • Form value data migration, when persistent type is changed.
  • #1140 Add module into form definition table - now is module resolved dynamically by owner, but this cannot be overriden by module - e.g. when reg module adds new form for identity, localization is searched by owner in core module ⇒ and cannot be found.