Customizable Enumerations

Introduction

SORMAS 1.60.0 has introduced a new customization feature that allows server administrators with database access to define their own server-specific values for supported enumerations. This guide explains how new values can be added to this table.

Supported Enumerations and Properties

The following enumerations and their properties can currently be customized in the database:

Disease variants

Data type: DISEASE_VARIANT
Properties:
- hasDetails: Whether the "Disease variant details" field is shown when selecting this variant.
  Supported values: true, false

Occupation types

Data type: OCCUPATION_TYPE
Properties:
- hasDetails: Whether the "Occupation details" field is shown when selecting this occupation type.
  Supported values: true, false

Other specific event risk

Data type: SPECIFIC_EVENT_RISK

Database Table

The customizableenumvalue table contains a row for each custom enumeration value that has been added to the system. These can be values that are automatically migrated from old enum types, or values that have been added by a system administrator. This table consists of the following columns (besides the usual columns that are part of every SORMAS table; the description, descriptiontransaltions and properties columns are currently unused and should be left empty):

datatype: The enumeration type which defines in which places of the application the value will be selectable, e.g. DISEASE_VARIANT.
value: The enumeration value, used as a technical identifier. Needs to be unique for its datatype and is not actually displayed anywhere in the application. It's recommended to use Java constant naming convention, e.g. NEW_ENUM_VALUE.
caption: The default caption of the enum value according to the server locale specified in the properties file. This is what's actually displayed in the user interface.
translations: Optional translations of this enum value to other languages that users of your system might be using. If their language is defined here, it will be used instead of the default caption. The translation format is explained in the "Adding Translations" section.
diseases: A comma-separated list of diseases that support this enum value. If left empty, it will be displayed for all diseases. Example: "EVD,CORONAVIRUS,CHOLERA". It is required to use the actual enum names of the diseases as defined in de.symeda.sormas.api.Disease here. They can also be retrieved from the data dictionary (e.g. in the "cases" sheet).

Adding New Values

To add new custom enum values to the system, please execute the following SQL script and replace the placeholders according to the table description above. The translations and diseases columns are optional and can be taken out of the script, or the placeholders can be replaced with NULL. All other columns are mandatory.

INSERT INTO customizableenumvalue (id, uuid, creationdate, changedate, datatype, value, caption, translations, diseases)
VALUES
  (nextval('entity_seq'), generate_base32_uuid(), now(), now(), '{{ datatype }}', '{{ value }}', '{{ caption }}', '{{ translations }}', '{{ diseases }}');

If you want to add multiple values at once, you can replace the semicolon at the end of the third row with a comma and copy and paste the third row to the end of the script as often as you wish. Please make sure that the last row ends with a semicolon instead of a comma.

An example of a populated script could look as follows:

INSERT INTO customizableenumvalue (id, uuid, creationdate, changedate, datatype, value, caption, translations, diseases)
VALUES
  (nextval('entity_seq'), generate_base32_uuid(), now(), now(), 'DISEASE_VARIANT', 'B.1.1.7', 'B.1.1.7', NULL, 'CORONAVIRUS'),
  (nextval('entity_seq'), generate_base32_uuid(), now(), now(), 'DISEASE_VARIANT', 'P.1', 'P.1', NULL, 'CORONAVIRUS'),
  (nextval('entity_seq'), generate_base32_uuid(), now(), now(), 'DISEASE_VARIANT', 'UNKNOWN_VARIANT', 'Unknown variant', '[{"languageCode":"de-DE","value":"Unbekannte Variante"},{"languageCode":"fr-FR","value":"Variante inconnue"}]', NULL);

Since customizable enum values are cached during server startup, a server restart is required after adding new values to the database.

Adding Translations

Translations are stored as a list using the JSON format. There are two key-value pairs expected for each translation of a specific enum value:

languageCode: The language code of the language that the value is supposed to be translated to. The language needs to be supported by SORMAS. The available language codes can be accessed in de.symeda.sormas.api.Language.java. Examples are en for English, en-NG for English (Nigeria), de-DE for German, de-CH for German (Switzerland), fr-FR for French, etc.
value: The translated value in the language specified by the languageCode.

An example for the translation of a value into a single language looks like this:

{"languageCode":"en","value":"Example value"}

Since the translations column expects a list, its content needs to be wrapped in square brackets:

Additional translations can simply be added inside the square brackets and have to be separated by commas:

Configuring Properties

Some customizable enumerations can be further configured by adding content to the properties column (please see the Supported Enumerations and Properties section for a list of supported properties). The notation here is the same as for translation into a single language described above. For example, to enable the disease variant details field when a specific disease variant is selected, the content of the properties column would look like this:

Additional properties would be added into the curly braces, with individual properties being separated by commas.

Default Values

Some customizable enumerations have default values that are enabled on all systems and are translated via Crowdin, such as any fixed enum. For these values, the defaultValue column in the database is set to true. Manual translations are not needed for those, and it is still possible to disable them if you don't want to use them on your server.