Dynamo: Reference documentation

The entity model supports several attributes that define how the entity itself is represented. These include:

Every entity model consists of a number of attribute models. By default, an attribute model is created for every valid property of the entity. e.g., if you have an entity Person with properties “name” and “age”, then the attribute model for the Person entity will contain two attribute models, one for “name” and one for “age”.

The following rules apply when constructing the attribute models:

An attribute model has a name attribute that is equal to the name of the property. This name can be used to retrieve the attribute model from the entity model:

For a nested attribute model, the name of the model consists of the concatenation of the names of the non-nested models separated by periods. e.g., if you have a Person entity that has an attribute address of type Address, then the houseNumber attribute model of the address has the path address.houseNumber.

This should all make sense as it corresponds to the paths that are used in e.g., JPQL queries and for data binding in Angular.

The entity model generation is based on sensible defaults and metadata: e.g., the value of the type setting of an attribute model is directly taken from the Java type of the property. Also, certain other aspects such as whether the attribute is visible in a grid or can be used in a search form are derived from this type (e.g., by default a complex attribute will not be visible in a grid).

In addition to this, the entity model generation process will take certain JSR-303 annotations (e.g., @NotNull, @Size) into account. A detailed explanation for each setting will be given below.

If the default values are not sufficient, you can override them by using annotations:

The @Model annotation can be used like this:

The @Attribute annotation can be placed either directly on the property, or on its getter method. Annotations placed on the getter method override those placed on the property, to easily allow you to override default behaviour in subclasses. Within a single entity class, you can use both access types interchangeably.

The annotation override mechanism is quite powerful, but it has some drawbacks. e.g., it hard-codes certain String values (display name, description) into your application, and it does not directly allow for internationalization. It also only allows you to override the behaviour of the “default” entity model that is based directly on the class, and not the behaviour of any derived entity models.

If you need to override the behaviour of a derived entity model, you can use the message bundle mechanism to achieve this. Message bundle overrides must be placed in the src/main/resources/META-INF/entitymodel.properties file (create a locale-specific version of this file if you need to; the normal Java message bundle mechanic is supported).

Message bundle entries in general have the following structure:

Where:

The [AttributeModelName] part must be omitted when you want to directly set an attribute of the entity model itself.

Some examples:

Sets the display name of the Organization entity to “Criminal Organization”.

Sets the display name for Person in the Person2 entity model to “Gang Member”.

Sets the visibility of the “name” attribute model to true.

Sets the “read only” setting of the address.street attribute model (a nested attribute model) to false.

Please remember the following:

In message bundle:

This setting can be used to specify the extensions of the files that are accepted by the file upload component that is generated for a LOB property. By default, its value is empty, which means there are no restrictions on the file type.

The value can be set to a comma-separated list of supported extensions, e.g., bmp,jpg,png.

On the @Attribute annotation, you can use an array of String values instead of a comma-separated String. Extensions are not case-sensitive, and you must not include the “.” character.

The attributeType setting is a classification of the type of the property. It is determined automatically during the entity model generation process and can have the following values:

The attribute type in combination with the Java type determines how a certain attribute will be displayed on-screen in an edit form:

Inside a search form the rendering is a slightly different:

The attributeType setting also determines whether the property will be visible by default:

E.g.:

In message bundle:

The autofillInstructions setting can be used to define the attribute-specific instructions for automatically filling a form based on an AI service (Large Language Model). This is covered in more detail in the section FormFillEnabled.

In message bundle:

The booleanFieldMode setting can be used to change the type of user interface component that is used to modify an attribute of type Boolean.

The default value for this setting is derived from the value of the system property dynamoframework.defaults.boolean-field-mode. It defaults to CHECKBOX but can be changed to TOGGLE (a toggle button) or SWITCH (an on/off switch).

This only affects the component that is used inside an edit form. Inside a search form, the framework will always use a tri-state checkbox (i.e. a component that can have the values true, false, or undefined).

In message bundle:

The cascade setting can be used to define “cascading search” for selection components. Cascading search means that when you select a value in a certain component, the available values in another component change based on this choice. e.g., suppose that you are editing or searching for an Organization and you have selection fields for a country and for a list of members of the organization– choosing a country from the list will limit the values in member list to the people that originate from that country.

To set up cascading, you can define one or more @Cascade annotations as part of the @Attribute annotation. Each @Cascade annotation takes three parameters:

Setting up cascading in a message bundle is a bit more involved. You can do so by defining two or three messages like this:

The cascade message defines the property to apply the cascading to – the cascadeFilterPath is the property path to filter on and the optional cascadeMode determines when to apply the cascading. Each message must end with a number that is used to group the messages together. The numbering starts at 1 and must use increments of 1, so if for example you want to define another cascade for the same attribute, that would look like this:

In message bundle:

This setting can be used to specify that a numeric field (currently only supported for BigDecimal properties) contains a currency value. If this setting is changed to a valid ISO 4217 currency code, then a currency symbol will be displayed in front of the value of the property.

If the specified currency code corresponds to a symbol (e.g., “$” for US dollar) then this symbol will be used instead of the code.

In message bundle:

The dateType setting can be used to determine how an attribute of type LocalTime, LocalDate, LocalDateTime or Instant will be managed:

The allowed values are:

By default, the value of the dateType setting is derived from the Java type of the property. You do not normally have to manually override it.

Dynamo does not support the legacy Java date types (java.util.Date and java.sql.Date).

In message bundle:

The defaultSearchValue setting can be used to set the default value that appears inside an input component inside a search form. This is only supported for simple attributes like strings and number, not for entities. It is only used when a single UI component is rendered for searching (as opposed to two components for specifying an upper or lower bound; in that case use defaultSearchValueFrom and defaultSearchValueTo)

You always specify this setting as a string; if the value must be converted to a decimal number, use the period (“.”) as the decimal separator. For enumeration values, use the upper-case String representation of the desired value.

For date attributes, use the String representations according to the system properties dynamoframework.defaults.date-format (dd-MM-yyyy), dynamoframework.defaults.time-format (HH:mm:ss), dynamoframework.defaults.date-time-format (dd-MM-yyyy HH:mm:ss).

In message bundle:

The defaultSearchValueFrom setting can be used to set the default value that appears as the lower bound inside a user interface component inside a search form. This is only supported for simple attributes like strings and number, not for entities. It is only used when two input components (upper and lower bound) are rendered for the search, e.g., in case of a numeric value or date range.

You always specify this setting as a String; if the value must be converted to a decimal number, use the period (“.”) as the decimal separator. For enumeration values, use the upper-case String representation of the desired value.

For date attributes, use the String representations according to the system properties dynamoframework.defaults.date-format (dd-MM-yyyy), dynamoframework.defaults.time-format (HH:mm:ss), dynamoframework.defaults.date-time-format (dd-MM-yyyy HH:mm:ss).

In message bundle:

The defaultSearchValueTo setting can be used to set the default value that appears as the upper bound inside a user interface component inside a search form. This is only supported for simple attributes like strings and number, not for entities. It is only used when two input components (upper and lower bound) are rendered for the search, e.g., in case of a numeric value or date range.

You always specify this setting as a String; if the value must be converted to a decimal number, use the period (“.”) as the decimal separator. For enumeration values, use the upper-case String representation of the desired value.

For date/time attributes, use the String representations according to the system properties dynamoframework.defaults.date-format (dd-MM-yyyy), dynamoframework.defaults.time-format (HH:mm:ss), dynamoframework.defaults.date-time-format (dd-MM-yyyy HH:mm:ss).

In message bundle:

The defaultValue setting can be used to set the default value that appears inside a user interface component when creating a new entity. This is only supported for simple attributes like Strings and numbers, not for entities.

You always specify this setting as a String; if the value must be converted to a decimal number, use the period (“.”) as the decimal separator. For enumeration values, use the upper-case String representation of the desired value.

For date/time attributes, use the String representations according to the system properties dynamoframework.defaults.date-format (dd-MM-yyyy), dynamoframework.defaults.time-format (HH:mm:ss), dynamoframework.defaults.date-time-format (dd-MM-yyyy HH:mm:ss).

In message bundle:

The description setting determines the value of the tooltip that the user will see when hovering over the input field for the property.

If not explicitly set, it will default to the value of the displayName setting.

This setting supports localization.

In message bundle:

The displayFormat setting indicates how date/time values will be formatted. It is supported for attributes of a Java 8 date/time type (LocalDate, LocalTime, etc).

The value of the displayFormat attribute must be a valid Java data/time formatting pattern, e.g., dd-MM-yyyy, but you can use different separators like dd/MM-yyyy or use formats like yyyy-MM-dd.

If you do not explicitly specify a displayFormat for an attribute, the framework will default to the value of the dynamoframework.defaults.date-format, dynamoframework.defaults.time-format, dynamoframework.defaults.date-time-format, or system variables depending on the dateType of the attribute model.

This setting supports localization.

In message bundle:

The displayName setting determines how the attribute will be named onscreen. By default, it is derived from the name setting, replacing CamelCase notation by spaces and then capitalizing individual words, e.g., mininumAge will be translated to “Minimum Age”. You can use the system property dynamoframework.capitalize-property-names and set it to false so that only the first word will be capitalized.

This setting supports localization.

In message bundle:

The downloadAllowed setting indicates whether it is allowed to download files that were uploaded using the file upload functionality. It defaults to false.When set to true, a “download” button will show up next to the preview of the image in a file upload component.

In message bundle:

The editableType setting specifies when an attribute can be edited. The default value EDITABLE means that the attribute can be edited both when creating a new entity or when editing an existing one. CREATE_ONLY means that the attribute can only be edited when creating a new entity. READ_ONLY means that the property is read-only and cannot be edited in the user interface.

The special value HIDDEN can be used in cases in which an attribute must be filled with a value that is not directly entered inside the edit form but depends on another non-constant value. e.g., you are in detail screen and have a reference to a parent object which must be set on the new entity.

The values of properties that are set to EDITABLE or CREATE_ONLY will still be shown inside edit forms, however it will not be possible to change the values.

In message bundle:

This setting specifies the type of component to use for editing an attribute of type ELEMENT_COLLECTION. The default value, CHIPS, will result in a “chips” component (basically a field that holds multiple tags). You can change this to DIALOG to render a component that uses a popup dialog to enter additional values.

This setting is not configurable using a message bundle.

The email setting can be used to specify that a field must contain a valid email address. It is automatically set to true if the property is annotated with the @Email annotation (from the Java validation framework).

In message bundle:

The enumFieldMode determines which input component to use when managing an attribute of type ENUM. By default, the value DROPDOWN is used, which means that a dropdown field (combo box) will be used. You can change this default by modifying the value of the system property dynamoframework.defaults.enum-field-mode. When the value is changed to RADIO a set of radio buttons will be used instead.

In message bundle:

The fileNameProperty setting can be used to specify the name of the property that is used to store the name of an uploaded file after a file upload. This setting is intended to be used on attributes of type LOB:

By default, if you define an attribute of type LOB, the application will render a file upload component for editing this attribute. The byte content of the uploaded file will be stored in the property itself, but the file name of the file that was uploaded will not be persisted.

If you want to store the file name as well, simply create another property (of type String) and then point the fileNameProperty of the @Attribute annotation that is placed on the property that holds the binary representation to this property. The framework will then store the name of the uploaded file in this property as part of the file upload process.

The actual fileName property must be annotated as readOnly since it is automatically set by the framework and does not need to be modified by the user.

If you don’t specify a fileNameProperty for an attribute that is meant for file upload, the upload and download will still work, however when downloading a file, it will be assigned a default file name because the actual file name is unknown.

In message bundle:

The groupTogetherWith setting can be used to specify that the input components for several attributes must be placed together on a single row in an edit form. This can be a good way of saving screen space. The value of this setting consists of a list of attribute names. The input components for these attributes will be placed behind the original attribute, in the order in which they are defined.

Here you see an example of this for the region attribute:

And this is the input form that will be generated:

You can still use all available settings to modify the behaviour of the components for the “extra” attributes that are placed behind the first attribute. The framework makes sure that the extra attributes do not show up more than once.

In message bundle:

This setting can be used for rare occasions in which you want to use an attribute inside a search form (e.g., for setting up cascading) but you want to ignore the selected value when actually performing a search.

In message bundle:

This setting can be used on a LOB property to specify whether it represents an image. By default, this setting has the value false. If set to true, the application will try to render a preview image of the value (byte contents) of the property.

In message bundle:

The lookupEntityReference setting can be used to specify the reference (unique identifier) that is to be used when looking up nested entities. e.g., suppose that you have an Organization entity that has an attribute Country. By default, when looking up countries (e.g., when filling a dropdown list), the default “Country” entity model will be used. If you want to use a different entity model, you can specify this using this setting.

You can use the message bundle (entitymodel.properties) to modify how this entity model behaves.

In message bundle:

The lookupQueryType setting can be used to specify the query type to use inside a popup search dialog that is used inside a lookup field component.

The maxCollectionSize setting determines the maximum number of allowed elements in an element collection, one-to-many relation, or many-to-many relation. Its value is derived from the max value on the standard Java Validation @Size annotation.

In message bundle:

The maxLength setting can be used to specify the maximum allowed length of an attribute of type String. This value is normally automatically derived from the @Size(max=<value>) annotation.

It can also be used to set the maximum length of string values inside an element collection. In this case, you must set the maxLength directly using the @Attribute annotation.

In message bundle:

The maxLengthInGrid setting can be used to set the maximum length of the value of a String property when it is displayed inside a grid – if the value of the property is longer than this, the value will be truncated after the first maxLengthInGrid characters. This can help save space in grids.

In message bundle:

The maxValue setting can be used to specify the maximum value of a numeric attribute. This value is automatically derived from the @Max annotation for Integer or Long fields.

It can also be used to set the maximum value of numeric values inside an element collection. In this case, you must set the maxValue directly using the @Attribute annotation.

This setting is not configurable using a message bundle.

The memberType setting can be used to explicitly set the member type (i.e. the type of an individual entity) of an attribute type DETAIL. Normally, the member type can be derived from the source code automatically, but there are certain cases in which this is not possible, e.g., when working with a property that does not directly map to a member field, but rather returns a collection that is calculated on the fly. In this case, you can use the memberType to set the exact type of the members of the collection.

This setting is only supported as an annotation override.

The minCollectionSize setting determines the minimum number of allowed elements in an element collection, one-to-many relation, or many-to-many relation. Its value is derived from the min value on the @Size annotation from the Java validation framework.

In message bundle:

The minLength setting can be used to specify the minimum allowed length of an attribute of type String. This value is automatically derived from the @Size(min=<value>) annotation.

It can also be used to set the minimum length of string values inside an element collection. In this case, you must set the minLength directly on the @Attribute annotation.

In message bundle:

The minValue setting can be used to specify the minimum value for a numeric attribute. This value is automatically derived from the @Min annotation.

It can also be used to set the minimum value of numeric values inside an element collection. In this case, you must set the minValue directly using the @Attribute annotation.

In message bundle:

The multipleSearch setting can be used to allow searching on multiple values at once for attributes of type MASTER. By default, the user would only be allowed to search on a single value at a time for such attributes, but if you set this setting to true you will be allowed to select multiple values (and the application will return all entities that match at least one of the selected values). This will also change the component that is rendered by default from a combo box to a multiple select field.

You can use the searchSelectMode to further modify the type of the search component that is rendered (you can also use a lookup field by using the value LOOKUP).

In message bundle:

The navigable setting can be used to specify that a hyperlink for in-application navigation must be rendered for a certain property. This works both in a grid and inside an edit form. This is only supported for properties of type MASTER (i.e. many-to-one relations).

In order to use this form of navigation, you first need to set the navigable setting for the property to true. This will then make the attribute values clickable inside results tables, and inside a form that is in read-only mode.

In message bundle:

The navigationLink setting can be used to specify the path to use for intra-application navigation (see also under navigable)*. By default, the application will use the name of the referenced entity (with the first letter lower-cased) as the value of the navigation link, but this can be modified by setting the navigation link. If this setting has a value that is not equal to the empty string, then this setting will be used rather than the default.

In message bundle:

The Dynamo framework only returns the attributes that are actually needed for displaying or editing the entities to the front-end.In very rare occasions it can happen that there are attributes that are not directly needed in the UI but that are used as the input for certain other (read-only) attributes.By default, the values of these attributes are not returned by the API.In these cases, you can set the neededInData setting to true in order to return these attribute values anyway.

In message bundle:

The numberFieldMode setting can be used to set the field mode to use for a numeric property When set to TEXTFIELD application will render a text field.This field has input validation so that only numbers can be entered.

When set to NUMBERFIELD, the application will render a text field with a pair of spinner buttons that can be used to increase or decrease the value.

The default value of this setting can be modified by changing the system variable dynamoframework.defaults.number-field-mode.

In message bundle:

The numberFieldStep setting can be used to set the step size to be used for a number field (see section Number field mode). The default value is 1, but you can set this to any positive integer.

In message bundle:

The percentage setting is used to indicate whether a numeric value represents a percentage. By default, this attribute has the value false. If set to true, the value of the property will be displayed with a “%” sign following it, both in read-only and edit mode.

The percentage sign is purely cosmetic; the actual value of the property is not converted or changed in any way.

In message bundle:

The precision setting determines the number of digits will be shown behind the decimal separator when displaying non-integer numbers. By default, it is set to 2, but you can change this by changing the value of the system property dynamoframework.defaults.decimal-precision.

In message bundle:

The prompt setting determines the value of the prompt that shows up inside the editable field for the attribute (in Angular/PrimeNG this is known as the “placeholder”)

If not set, it defaults to the value of the displayName setting.

In message bundle:

The quickAddAllowed setting can be used to allow the creation of entities directly from inside a form, for a UI component that is used to manage a MASTER or DETAIL relation. Normally, in such a case a combo box, multi-select or similar component will be rendered (depending on the value of the selectMode setting)

If you set the quickAddAllowed setting to true, an additional button will be rendered next to the edit component for the property. When pressed, this button will bring up a dialog that will allow the user to create a new entity.

When the user presses the OK button in this dialog, the framework will create a new entity based on the contents of the dialog. This comes with an automatic check for duplicate values, provided you have configured this on the underlying service.

As an example, consider the following:

Here, we define a “countryOfOrigin” property that is of type “Country”. We set the quickAddAllowed to `true. Once the user now starts the application, they will see an “Add” button behind the field that can be used to create a new country. Once pressed, the button will bring up the following dialog:

The user can now enter the properties of the country in the popup – once they press the “OK” button the application will store the new Country, add it to the options that are present in the selection component, and select it.

The application will carry out an automatic check for duplicates when the user tries to save the entity (based on the findIdenticalEntity functionality), and will then look for an error message stored under the <short name of entity>.not.unique`key in order to display an error message. e.g., in the example above, you should add a `Country.not.unique message to the message bundle.

In message bundle:

The replacementSearchPath setting can be used to modify the search path that is used when translating search filters into a query – it can happen that you are using a derived property in your search screen (e.g. to allow searching on only a subset of values) and when you take no further action this will produce an error when carrying out the query since the property is not known in JPA. In cases like this, you can use the replacementSearchPath setting to specify the alternate (real) path to use during the search.

The replacementSearchPath setting is managed completely in the back-end.

In message bundle:

You can use this setting to override the path to sort on when the user clicks on a column header in a search results grid. By default, the application will then sort on the exact path to the property, but if the replacementSortPath is set, that value will be used instead.

The replacementSortPath setting is managed completely in the back-end.

In message bundle:

The requiredForSearching setting determines if a property is required before a search can be carried out inside a SearchLayout.* If you create a search form that contains properties that have requiredForSearching set tot true, you will not be able to carry out a search (i.e. the search button will be disabled) until you provide a search value for these properties. Note that for an attribute for which two search fields will be rendered, at least one of the fields must contain a value.

The default value of this setting is false.

In message bundle:

The searchable setting determines whether a property will show up in a search form on a search screen. By default, it is set to NONE which means it will not show up in a search form. Setting this property to ALWAYS means it will always show up in a search form. Setting it to ADVANCED means it will only show up in search forms for which the “advanced search” mode has been enabled.

In message bundle:

The searchCaseSensitive setting determines whether search operations on the attribute are case-sensitive. The default is given by the system property dynamoframework.defaults.search-case-sensitive which defaults to false. This setting is only used for attributes of type String and ignored in all other cases.

On the attribute, you can use the values BooleanType.TRUE and BooleanType.FALSE.

This setting is managed completely on the back-end.

In message bundle:

The searchDateOnly setting determines whether search operations on an attribute that represents a date/time (either LocalDateTime or an Instant) are carried out using only date selection fields rather than time selection fields.

By default, when searching on a date/time attribute, the application will render two timestamp search fields that allow you to specify a search interval. When you change this setting to true then instead the application will render to date selection fields. Searching using these date selection fields will return any time stamps that fall within the specified date interval (inclusive). e.g., if you enter the search values 2020-04-04 to 2020-04-06 you will return any records for which the time stamp value matches the interval from 2020-04-04 00:00:00 up to 2020-04-06 23:59:599999999

In message bundle:

This setting determines whether to search for an exact value rather than a range, when searching for numeric or date values. By default, for such a field two search fields will be rendered: one for the lower bound of the range to search for, and one for the upper bound of the range to search for.

By default, this setting has the value false. If set to true, then instead of the two search fields, a single field will be rendered that allows the user to search for an exact value.

In message bundle:

The searchPrefixOnly setting determines whether search operations on the property check only for a prefix match. If this is set to true, then searching for e.g., “a” will only match “almond” (“a” appears at start) but not “walnut” (“a” appears in the middle). If set to false, then “a” will match both “almond” and “walnut”.

By default, this setting has the value false. This setting is only used for attributes of type String and ignored in all other cases.

This setting is managed completely on the back-end.

In message bundle:

The searchSelectMode setting is used to specify how the component for searching an attribute of attribute type MASTER or DETAIL will be rendered (inside a search form).

By default, the value of the searchSelectMode setting is equal to the value of the selectMode, but you can change it explicitly if you want a different component to be rendered inside a search form.

The following restrictions apply:

Depending on the type of component that is selected, different calls to the back-end will be performed:

In message bundle:

The selectMode setting is used to specify how the component for selecting an attribute of type MASTER or DETAIL will be rendered (inside an edit form).

The following restrictions apply:

Depending on the type of component that is selected, different calls to the back-end will be performed:

In message bundle:

The sortable setting can be used to specify whether a grid can be sorted on the attribute. By default, it is set to true for all attributes.

In message bundle:

The textFieldMode setting can be used to specify whether to render either a text field, a text area or a password field for editing an attribute of type String. The default is TEXTFIELD. The value TEXTAREA will be ignored inside a search form. The value PASSWORD will be ignored inside a search form.

In message bundle:

This indicates whether extraneous space characters will be trimmed from the start and end of the input inside text areas and text fields. This defaults to false but can be modified by changing the value of the defaults to false but can be modified by changing the value of the dynamoframework.defaults.trim-spaces system property.

On the @Attribute annotation, you can use the trimSpaces setting which supports the values INHERIT, TRIM and NO_TRIM. When INHERIT is used, it will just use the value of the system property. With TRIM and NO_TRIM you can either enable or disable the trimming for this specific attribute.

In message bundle:

The trueRepresentation and falseRepresentation settings can be used to modify how a Boolean value is displayed in read-only mode. By default, such a value will simply be displayed as true or false, but this can be overruled by setting respectively the trueRepresentation and falseRepresentation values.

This setting does nothing in edit mode, since in that case a checkbox or toggle button will be rendered.

In message bundle:

The url setting can be used to specify that a certain String property must be rendered as a clickable URL.

The default value is false. If set to true, then a validator will be added to the field (when in edit mode) that checks if the entered value is a valid URL (must start with http or https). Also, in view mode the framework will render a clickable URL containing the value of the attribute – when clicked it will open the provided URL in a separate browser window.

In message bundle:

The visibleInForm setting determines whether a property will be displayed inside an edit form. It is not to be confused with the visibleInGrid attribute that governs whether a property shows up in a grid.

By default, all simple properties will have visibleInForm set to true. All complex (master and detail) properties will be hidden by default.

Instead of true you can also use the value SHOW and instead of false you can also sue the value HIDE.

In message bundle:

The visibleInGrid setting determines whether a property will be displayed in a search results grid.

By default, all simple properties will have visibleInGrid set to true. All complex (master and detail) properties will be hidden by default.

Instead of true you can also use the value SHOW and instead of false you can also sue the value HIDE.

In message bundle:

By default, the properties of an entity will be displayed in the order in which they appear in the Java class file. This can be overruled by using an @AttributeOrder annotation or setting the attributeOrder via the message bundle.

The @AttributeOrder annotation takes a single parameter, named attributeNames which contains an array of field names – the order in which the attributes appear in the array is the order in which they will appear in the application.

You can achieve the same effect by including a message like Organization.attributeOrder=name,headquarters,address,countryOfOrigin,reputation in the message bundle (use commas to separate the values). The message in the bundle will overwrite the ordering set by @AttributeOrder. If your entity has a large number of attributes this might get a bit unwieldy though.

The ordering does not have to contain all properties; if you leave out any attributes, then those will be placed (in the normal order) after any attributes that are explicitly mentioned in the annotation or the message bundle.

Also by default, the attribute order in a search form and in results grid is the same as the default attribute order (see the previous paragraph). You can override this by using the @GridAttributeOrder and @SearchAttributeOrder annotations.

These annotations do the following:

These additional attribute orders completely overwrite the default attribute order, so you will have to redefine all attributes in the order you want to see them. Any attributes that are not explicitly mentioned are included at the end in alphabetical order.

You can also overwrite these orders using the message bundle:

In addition to ordering the attributes, they can also be grouped together. To do this, you can include an @AttributeGroups annotation on your class definition, which can in turn include any number of @AttributeGroup annotations.

Each @AttributeGroup annotation contains the name of the group and an array that contains the names of the properties that must be included in the group. As an example, consider:

The above defines two attribute groups identified by the message keys Organization.first and Organization.second. The display names of the groups can be defined in the message bundle:

When you want to achieve the same using a message bundle, you can do this in the following way:

I.e. you include two messages for every attribute group: one containing the message bundle key and one containing the attribute names as a list of comma-separated attribute names. The messages are numbered starting at “1”.

The attribute grouping is only used to determine which properties to group together, not to determine the order in which the attributes appear within this group. This order is still determined by the @AttributeOrder annotation as described earlier.

When you want to refer to a certain attribute group in your code, you should do so by using the (unique) message key of that group.

The Dynamo framework supports dealing with nested entities. When Dynamo generates an entity model for an entity, it automatically creates nested entity models for all complex properties it encounters. This is currently supported up to three levels deep. The models are constructed lazily when needed.

The entity model that is created for a nested entity is a separate model from the top-level model for the entity. So, the direct model for the “Address” entity is a different model than the nested model for Person.address.

Some settings behave differently for nested entity models. e.g., for any properties of nested entities, the searchable and visibleInGrid settings will be set to false by default.

You can override settings on nested attribute models in the same way as you can override attributes of non-nested entities, i.e. by including a message in the message bundle that contains the full path to the property (e.g., Movie.director.name.displayName=Director Name).

The entity model framework also supports dealing with “element collection” properties, i.e. properties that are collections of simple types (currently String, Integer, Long and BigDecimal are supported) and that are annotated with the @ElementCollection annotation.

For these properties, the application will automatically generate either a chips component or a dialog component (depending on the value of the elementCollectionMode setting) that allows you to add items to, remove items from, and modify items in the collection. You can use the minLength`and `maxLength settings to modify the minimum allowed length and maximum allowed length of the individual items (in case of a collection of Strings), or use the minValue and maxValue settings to define a minimum or maximum value for a collection of numeric values.

The @Size annotation (from the Java validation framework) can be used to restrict the minimum and maximum number of elements that are allowed in the collection as a whole.

Dynamo has certain requirements regarding the Data Access layer and Entity classes that are used in applications developed with the framework.

All Entity classes (i.e. classes that map to a table in the database) must inherit from the AbstractEntity class. This means that they inherit a version field (used for optimistic locking) and an id field that denotes the technical primary key. The type of this id field is configurable via the type parameter of the AbstractEntity class.

An example Entity class looks like this:

In principle, it is allowed to use inheritance when defining entities. However, be careful when using abstract superclasses: their use is currently only allowed when the abstract superclass itself is not directly exposed via the REST services. This is because the REST serialization and deserialization process cannot properly deal with abstract classes.

For every Entity class, you must (normally) create a Data Access Object (DAO) interface and the accompanying implementation. The DAO must inherit from the BaseDao interface:

And the implementation must inherit from BaseDaoImpl:

The minimal implementation contains just two methods: getEntityClass() which returns the type of the entity that is managed by the DAO, and getDslRoot() which returns the QueryDSL root.

QueryDSL is a framework that is used by the Dynamo Framework to create type-safe queries. Basically, what QueryDSL does is create a QueryDSL class for every entity class in your application. When developing in Eclipse or Intellij, the IDE will automatically generate the appropriate classes. You can also run a command line Maven build to generate them.

Finally, note that the DAO implementation class is annotated with @Repository, which will register it as a Spring bean (it also has additional functionality in Spring Data, but Dynamo does not currently use the Spring Data library).

In addition to developing a DAO for your entity, you must also create a service class. This service class in its most basic form will serve as a delegate to the DAO, but it is also the place where you can place business logic.

The declaration of a service interface is very easy; the service must extend BaseService.

You can define a service by extending the BaseServiceImpl class and inject the appropriate DAO. This DAO must also be returned by the getDao() method. Note that the service must be annotated with @Service, registering it as a Spring service.

By default, the methods of the service that manipulate data (basically, save() and delete() are already annotated with the @Transactional annotation (from the Spring framework). If you add any methods yourself that also need an active transaction, you either have to mark these methods (in the service implementation class) as transactional. Alternatively, you can place the @Transactional annotation on the service implementation subclass in order to make all methods in that service transactional.

The Dynamo framework is built around the concept of fetching data (using fetch join queries) whenever possible. The philosophy behind this is that it is usually much faster to fetch all required data using a single query than performing numerous smaller queries to achieve the same result.

For this reason, we recommend to keep the use of eager fetching to an minimum and use lazy fetching combined with fetch joins whenever possible.

The framework supports several methods that make it possible to fetch data based on a primary key or collection of keys, and also allow you to specify with relations to fetch as part of the query.

Note e.g., the following method defined in BaseService:

As you can see, this method accepts a vararg parameter that specifies which relations to fetch. If left empty, the application will use the default setup, which you can specify by using the @FetchJoins annotation on an entity class.

This means that whenever you perform a fetch query (for multiple entities) using a standard service method, and you do not explicitly specify which relations to fetch, all relations specified by the “joins” property will be returned.

When performing a query to fetch just a single entity (and its relations), the detailJoins will be used instead.

The consequence of this is that the joins setting should normally contain the relations that you want to display in a results table, whereas the detailJoins should contain the relations that you want to display inside an edit form.

When declaring a @FetchJoin, you can specify the type of join. The default is LEFT JOIN which means that the entity will be returned even if the relation to fetch is empty. You can change this to INNER. This will often improve performance but only used this if it relation you are fetching is mandatory and thus always present.

Take care not to include any substantially large relations, since this can lead to poor performance.

If you create a component that contains a tabular display of data, you can specify the way in which the data will be retrieved. There are two options here:

In both cases, the grid is filled lazily – only a small subset of the available data will be retrieved. The best approach depends on the situation – if you have a large data set and no relations to fetch then paging is preferred. If you have a lot of relations to fetch (or if you must fetch any one-to-many or many-to-many relations), use the ID-based approach.

In addition to defining the joins using the @FetchJoin annotation, it is also possible to configure the joins in the entitymodel.properties message bundle.

This is done as follows:

Some clarifications:

To set up two joins for the Organization entity, you can do the following:

And to define three joins to be used when fetching a single entity:

As you have seen before, it is possible to set default values for simple attributes.These default values are applied on the client side when creating a new entity.As an alternative to using these default values, you can also create an entity with default values in the back-end.

In order to do this, override the initialize() method in the implementation of the entity’s service.In this method you can initialize the entity with all the desired default values.This is especially useful when creating entities with nested collections.

By default, you do not need to make any changes to the REST API offered by the Dynamo framework in order to be able to use an entity in the front-end – as long as you properly create an entity class, a DAO, and a service as described above, the endpoints for creating, updating and searching this entity will be made available by the framework – you should simply be able to create a component in the user interface that refers to the new entity, and all endpoints will work out of the box.

The validation functionality offered by the Dynamo Framework are based on the JSR 303 (Bean Validation) standard: to express validation rules, simply use the standard annotations (@NotNull, @Size, @Min, etc.) on the properties of your entity.

You can also use @AssertTrue and @AssertFalse to express more complex (inter-field) validation rules, or write your own validations by implementing the ConstraintValidator interface. To use @AssertTrue or @AssertFalse, create a method on the entity class that returns a Boolean, then annotate that method with either of these annotations – during the validation process these methods will be executed and if the return value does not match the value expected by the annotation then a validation error will be reported.

Custom validation messages can be included in the ValidationMessages.properties message bundle.

When you save an entity (by calling the service method save()), it is automatically validated against these validation rules, and an OCSValidationException will be thrown if any of the validations fail.

If you need to perform any custom validations for a certain entity class, you can do so by overriding the validate() method in the Service implementation class for that entity.

The settings that are relevant for validation will also be exposed via the entity model API to the front-end, and will be used to create the appropriate Angular validators. The following validators are supported:

When the user submits a form, the validators mentioned above will be executed, and if any of them fail the form will not be submitted to the back-end.

If all validations pass on the front-end, a call to the back-end will be performed. In the back-end, the same validations will be performed again, possible augmented with any custom validations defined exclusively in the back-end. In case any of these validations fail, the call will be rejected and a validation error message will be shown.

Unfortunately, it is not possible to automatically replicate the custom back-end validations in the front-end. However, it is possible to replicate the validations by using custom validators. This will be covered in more detail later in this manual.

There is one additional feature with regard to validation that we must mention here. In case you have an entity that contains a logical primary key (either a single field or a combination of fields) the framework provides an easy way to check for possible duplicates. To do so, you only have to override the findIdenticalEntity() method from the BaseServiceImpl in your service implementation class.

This method takes an entity as its only parameter; inside the method body, you can perform any query to check if there already is an entity that has the same values for the unique field or combination of fields. If the method returns a non-null value, then the framework will throw an OCSValidationException as part of the validation process.

Consider the following example that checks if there already is an organization with the same name as the organization you are trying to save (which is passed as a parameter to the method):

It can happen that you have a very simple entity for which you will only need the default methods provided by BaseService. If this is the case, then you do not have to go through the trouble of creating a DAO and Service class. Instead, you can configure a DefaultServiceImpl and/or DefaultDaoImpl in a configuration class. This looks as follows:

As you can see, you can configure a bean that is an instance of DefaultServiceImpl and supply the necessary arguments to the constructor. This includes:

After you have configured a service like this, you can inject it into your code as follows.Note that an @Qualifier annotation that matches the name of the bean is required:

Class: org.dynamoframework.configuration.DynamoConfigurationProperties

Class: org.dynamoframework.configuration.DynamoConfigurationProperties$OllamaConfigurationProperties

Class: org.dynamoframework.configuration.DynamoConfigurationProperties$OpenAiConfigurationProperties

Class: org.dynamoframework.configuration.DynamoConfigurationProperties$DefaultConfigurationProperties

Class: org.dynamoframework.configuration.DynamoConfigurationProperties$DefaultConfigurationProperties$EndpointConfigurationProperties

Class: org.dynamoframework.configuration.DynamoConfigurationProperties$BedrockConfigurationProperties

Class: org.dynamoframework.configuration.DynamoConfigurationProperties$VertexAiConfigurationProperties

Class: org.dynamoframework.configuration.DynamoConfigurationProperties$CsvConfigurationProperties

You can retrieve the Dynamo properties using the DynamoPropertiesHolder in the following way:

Back-end applications that want to use the Dynamo framework are fairly standard Spring Boot applications. Below is a sample pom.xml file that shows the minimal set-up for a Dynamo back-end.

Replace the placeholders between square brackets by your own values

This example POM also does not include any database drivers. This means you will likely need to add your own database driver (e.g., Postgresql).

It also does not contain any dependencies for setting up application security, however the three dependencies that you need to set up Spring security based on OAuth are included in the pom but commented out.

With this in place, there is only a little bit of set-up needed to be able to use the application. First of all, include an ApplicationConfig class as follows

Finally, we need a Spring Boot Application class

Be sure to replace the placeholders above by the directories that contain your entities (for the @EntityScan) and your services/components (for the @ComponentScan)

The application also needs access to an implementation of the Dynamo interface UserDetailsService. This service is responsible for checking whether a user is in a certain role and whether they are allowed to perform certain actions. The implementation of this service depends on your authentication provider of choice and implementing it is beyond the scope of this documentation. Below you find a dummy implementation that will never reject a request.

A Dynamo application uses a number of message bundles. These message bundles are made available to the Spring Framework and you can retrieve a message from them using the MessageService which is a Spring-managed singleton bean that you can inject into your services. Note that many standard components already have a reference to this MessageService.

The message bundle that is most important for updating the application is the message bundle located at src/main/resources/entitymodel.properties. While the application will function without this message bundle, it is very useful for specifying e.g., localizations of enumeration values or for overriding entity model defaults defined in the annotations.

The MessageService provides a number of methods for retrieving messages. Some of these are used internally by the framework and should not normally be used directly. The following methods are intended for developers:

If a message with a certain key cannot be found, then a default warning message will be returned. If you do not want this behaviour, you can use the getMessageNoDefault() version of the method instead. This version returns null when a message cannot be found.

As a Dynamo application is a Spring Boot application, you can add or modify any properties by changing the application.properties (or application.yml) file which should be located in the src/main/resources directory of the UI subproject. The properties specific to Dynamo will be covered in the section Configuration.

Dynamo does not have any functionality for directly dealing with authentication. It is recommended to use Spring Security for securing your application.

The following gives some pointers for setting up Spring Security, using OAuth2 (with the backend serving as an OAuth resource server)

When you start a new front-end project that uses the Dynamo framework in its front-end, there are several approaches you can take. The easiest approach is to use the blueprint project found at https://github.com/opencirclesolutions/dynamo-blueprint

This project contains the skeleton for an Angular application that uses the Dynamo framework. It comes with:

The fastest way to get started is to fork this project, then replace all occurrences of "dynamo-blueprint" by your desired project name.

With this in place, you should be able to run the ng serve command to start a minimal application. This application has all the infrastructure in place but does not do any authentication or authorization.

In order to add custom logic to this application, you can run the following command to create a component:

Inside this component, you can use the dynamo components like <app-generic-search-layout>.

In order to be able to actually use the component, don’t forget to add a route to it in the app-routing.module.ts, as shown below.

If you already have an existing front-end project you can also copy the Dynamo sources directly to your project.

To do so, make sure that your project uses the following dependencies

and that Bootstrap and ngx-translate are set up properly.

With that in place, you can copy the contents of the dynamo-angular/shared folder to the /src/app/shared folder in your application.

You will also need the code used to communicate with the back-end. You can make this available to the front-end by copying the contents of the dynamo-angular/dynamo/model to the dynamo/model directory in your front-end application. You can also run the Open API tools generator as described below.

Finally, the messages used for the internationalization of the Dynamo components have to be added to the application message bundles. These messages are included under the dynamo-angular/i18n/ directory. Currently, English and Dutch are supported. These message need to be added to the message bundle files, typically under /src/assets/i18n

Finally, in case you are using the PDF viewer component and this produces errors, you might need to add the following to your angular.json file:

To use localization, you can use the (standard) functionality provided by the translateService.

Message bundles (named <locale>.json, e.g., nl.json, en.json) can be placed in the assets/i18n directory.

The messages take the form key: value:

In the HTML components, messages can be referenced as follows:

In the Typescript files, you can inject a translateService instance, then use that to retrieve values from the message bundle:

In order to display notification messages, you can inject and use the NotificationService into your component.

You can then use the info(), warn(), and error() methods to display an error message

By default, the message will disappear after a couple of seconds, but you can use the sticky parameter set to true in order to make the message sticky/persistent.

The Dynamo Framework uses a generic framework for executing search requests to the back-end.Normally the details of this framework are hidden from the developer, but in some cases, e.g., when defining field filters, it can be useful to know how the filter mechanism works in detail.The rest of this section will cover how to set up the various supported filters.

Some extra explanation is in order with regard to how the Dynamo framework deals with updates of existing entities. All updates of existing entities are performed by doing a PUT call to /api/dynamo/crud/{entityName}/entityId.

With regard to editing complex attributes inside an edit form, Dynamo offers several options. This section will go over these options.

First of all, there are basically three types of complex attributes:

In rare cases, it can occur that your application contains an edit form for creating/updating entities that depends on an external value that is dependent on the context. e.g., you are creating a new person that is a member of an organization, but this organization is not present as a field in the input form, however it is passed to the edit form based on a previous action. In this case, you can use a hidden field to pass a value into an edit form. The hidden field is not present/visible in the form, but its value is passed along to the backend regardless.

In order to include a hidden field in a form, use an ng-template tag and add the dHiddenField directive to it. Then provide the field name and value. In case this is an entity, it is sufficient to only include the primary key (entityId in the example below).

In general, Dynamo is not particularly concerned with whether the objects you are displaying in the UI are actual entities backed by a database table – any class that extends the AbstractEntity class (and is hence identified by a unique ID) can be used with the entity model framework). This makes it relatively easy to use View Objects in the UI. In the case of a view object you are creating an object that is solely used to transfer data to the UI where it will be used for display purposes. This technique can be used to combine data from e.g., multiple sources

In order to use a view object, take the following steps:

It is also possible to define actions on the entity model that will directly be translated to input dialogs in the UI. This can be used when you have an action that operates on part of an entity, e.g., you want a dialog that can be used to change only an organization’s name.

In order to use this functionality, you must perform a number of steps:

As an example, consider the following:

Under the covers, the application will create an entity model based on the DTO that is passed to the annotated method. This entity model comes with all the functionality of a regular entity model – this means that you can annotate the DTO properties with the @Attribute annotation (and the other entity-model related annotation), and these settings will influence how the dialog that is used to carry out the action will behave.

In the UI, the framework will automatically generate buttons that bring up a modal dialog that can be used to carry out the action. This modal dialog will contain input components based on the entity model. e.g., for the action defined above, it will look as follows:

Actions of type CREATE will appear in the button bar below the results table in a search layout, split layout, or editable table layout.

Actions of type UPDATE will appear in each row in the results table, behind the regular popup button.

The action is also linked to the entity by means of the ID field - the ID of the entity will be passed along to the call to the back-end and should bind to the ID field in the DTO. In your service you can then use this ID in order to retrieve the entity.

It is possible to configure role-based authorization to limit which users are allowed to perform which actions on certain entities. This is done by means of placing the @Roles annotation on an entity class.

The @Roles annotation has three properties:

In all cases it is true that if no value, or an empty list, is provided, no specific roles are required and any user may perform the action. In case multiple values are provided, a user can perform the action as long as they have any of the provided roles.

It is possible to use the message bundle to override the required roles, by using the readRoles, writeRoles and deleteRoles keys. Each value takes a comma-separated list of the role names.

The Dynamo back-end will check the roles against the user’s Spring Security roles. It is left to the developer to ensure that the proper roles are added to the user principal (we recommend using OAuth).

In the backend, you can inject an instance of the UserDetailsService in order to be able to perform role checks. You can then use the validateXXX() methods which will throw an OCSSecurityException when the user does not have the proper roles to read/write/delete the entity managed by the entity model.

In the front-end, the UI components offered by the Dynamo framework will be automatically adapted based on the provided roles. This means that:

Currently, the Dynamo framework does not provide functionality for automatically building a menu or defining navigation rules based on the entity model roles. However, it does offer some functionality to ensure that only authorized users get to see certain screens

First of all, you can add a RoleGuard to any route that should only be accessible to certain users:

The data takes an array of roles that are allowed to access the specified route. The RoleGuard will block access to a route if the user does not have at least one of the provided routes, and navigate to the login route instead.

Secondly, you can use the AuthenticationService to check whether a user is in a certain role. You can e.g., use this when building a menu, to enable/disable certain routes.

One of the most commonly used components will be the “Generic Search Layout” which offers a search form combined with a results table. To use a GenericSearchLayout, define your own component, then in the HTML for that component, include something like this

This is the most basic set-up that will provide you with a search screen for the “Organization” entity. By default, this will do the following:

The GenericForm component can be used to edit or display a single entity. In its most basic form it can be used as follows:

This will set up an edit form for managing entities of type Organization. It can be used both for creating new entities and editing existing entities (based on the value of the entityId).

By default, the form will contain a single column of input components, in the order specified by the @AttributeOrder defined on the entity. The type of the component that will be rendered depends on various settings on the attribute model (e.g., selectMode, textFieldMode).

Only the attributes for which visibleInForm is set to true will be included in the form, and only if they indeed editable (see the Editable type for more details). If an attribute cannot be edited, then the attribute’s current value will be shown as a label.