Filters

Documentation about the behavior of filters used in the Harmoney application.

General rules:

• In general and unless otherwise specified, fields with a string, number, enum or date value will use an = operator in the actual query. Meaning the actual query will look like: WHERE ... = filtervalue
  • See https://dev.mysql.com/doc/refman/8.4/en/comparison-operators.html#operator_equal
• Some fields - usually free search fields - will use a LIKE operator with wildcards enabled. Meaning the actual query will look like: WHERE ... LIKE '%filtervalue%'
  • See https://dev.mysql.com/doc/refman/8.4/en/string-comparison-functions.html#operator_like
• Fields that use a collection as value will in general use the IN operator in the actual query. Meaning the actual query will look like: WHERE ... IN (value1, value2, value3)
  • See https://dev.mysql.com/doc/refman/8.4/en/comparison-operators.html#operator_in
• In general, archived entities are never included in the filter results. Only in the filters used in the data removal providers do we include archived entities!

Filter field labels

The label shown above a field in the UI filter panel is not translated by the front end. It comes from the displayValue of the field definition, which the back end resolves from that field's translation key: BACK_END.FIELDS.<translationKey>.label, with a deprecated fallback to FRONT_END.LABEL.<translationKey>. The .label translation is mandatory: without it no displayValue is produced at all. The optional BACK_END.FIELDS.<translationKey>.extra.infoText and .extra.description add the info icon and description.

Fields that are declared on the filter itself (status, partyType, …) get a translation key automatically, so for those only the translation has to exist. Metadata fields do not: they live in a JSON map, so the application cannot derive a field for each key. A metadata field that is only used as a filter value therefore has no field definition, and the filter panel falls back to showing the raw key. Note that a translation configured for the metadata field elsewhere (for example on the dossier detail page) does not fix this, because there is no key to resolve against in the filter.

To label a metadata filter field, add an entry for it to the FSP's field-definitions configuration provider. This cannot be done from JSON configuration:

.add(FinancialSpDossierFilter.class, entries -> entries
        .add(entry -> entry
                .on(FinancialSpDossierFilter_.metadata, DossierMetadataFields_.dossier2)
                .setStandardFieldDefinition(d -> d.fromFieldDescriptor(DossierMetadataFields_.dossier2)
                        .setVisible(true)
                        .setDisplayAfter(FinancialSpDossierFilter_.metadata, DossierMetadataFields_.dossier1)))
)

Two rules are easy to get wrong here:

• The field must be set visible. Labels are never resolved for a field that can never become visible, so an entry without setVisible(true) replaces the raw key with a Missing TR key placeholder instead of fixing it. This matters for filters that are only ever shown because a dashboard supplied a value: the UI reveals such a field when it carries a value, but the back end still refuses to label it while it is invisible.
• Two entries cannot target the same setDisplayAfter field. FieldDefinitionProvidersTest validates this, so it normally fails the build. It is worth knowing anyway: at runtime it makes the filter-field-definitions request fail, and the UI then renders no filter panel at all without showing an error. Chain the fields instead, as in the example above.

The two placeholders tell you which of the two situations you are looking at:

Label shown in the filter panel	Meaning
Missing TR key (fieldname: filter.…)	The field has a definition, but no translation key or no translation.
LABEL.…	The field has no field definition at all.

Date formats

We use 2 datatypes to represent date values in our filters: Instant and LocalDate. Note that the application always uses UTC time!

Instant

Probably the most common datatype we use for date related filter fields. An Instant supports both “date” and “time” values.
To configure a correct Instant value, you should follow the following format: yyyy-MM-ddTHH:mm:ssZ. So for example, the last day of 2024 at 6:30 in the evening will look like this: 2024-12-31T18:30:00Z. It’s important to always add the “time” part, only providing the date part (e.g. 2024-12-31) is not a valid Instant value! In case you only need a date, you can use the start of day time, e.g.: 2024-12-31T00:00:00Z

As mentioned above, note that the application uses UTC times when working with date time values!

See also: https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html

LocalDate

Filter fields with a LocalDate only support date values without a time unit. To configure a correct local date value, you should follow the following format: YYYY-MM-DD. So for example: 2024-12-31 is a valid local date filter value.
See also: https://docs.oracle.com/javase/8/docs/api/java/time/LocalDate.html