Skip to content

Customizable Enumerations

Jump to bottom
Maté Strysewske edited this page Jul 30, 2021 · 6 revisions

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. Right now, this feature only supports Disease Variants, which were formerly stored in their own table and have now been migrated to the new customizableenumvalue table. This guide explains how new values can be added to this table.

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. Currently only the datatype DISEASE_VARIANT is supported.
  • 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:

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

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

[
  {"languageCode":"en","value":"Example value"},
  {"languageCode":"de-DE","value":"Beispielwert"},
  {"languageCode":"es-ES","value":"Valor del ejemplo"}
]
Clone this wiki locally