The USxS-R applications contain a number optional modules and configuration options. These are visible in the applications under the System → Modules and Configuration views.
The normal way to enable modules and edit configuration values is to use the User Interface. However, it is also possible to enable modules and set configuration values using docker environment variables. These settings can either set default configuration, or override values set via the UI. This is useful if the ITC wishes to set the same values for all district's in their data center. For example, typically the SMTP host should be set the same for all districts.
Enabling Optional Modules
To enable a module, you use the "Module Id" to determine the corresponding environment variable. The environment variable suffix is the "Module Id" without the "org.ssdt-ohio:" prefix. For "common" modules, the "ssdt.common." prefix is optional. Then uppercased and dots and dashes converted to underscores.
The table below shows a few common modules and the corresponding environment variable suffix:
|Module Id||Environment Variable Suffix|
|org.ssdt_ohio:ssdt.common.notification-email||SSDT_COMMON_NOTIFICATION_EMAIL or NOTIFICATION_EMAIL|
|org.ssdt_ohio:ssdt.common.masschange||SSDT_COMMON_MASSCHANGE or MASSCHANGE|
After determining the environment variable suffix, then add environment variables to the
docker-compose.override.yml by prefixing the modules suffix with "INSTALL_".
For example, to enable the modules in the above table, you would add the following to the uspsapp and/or usasapp services:
Value of the environment variable is not relevant. It is not currently possible to uninstall a module via environment variables. Once a module is installed, it can only be uninstalled using the UI. However, if a module is uninstalled via the UI, the environment variable must also be removed. If the environment variable is still set on next startup, the module will be re-installed.
Setting Configuration Values
The value of configuration objects may be set by docker environment variables by defining the correct environment variable. Environment variables may be used to apply default configuration, or to override the value configured in the application.
To determine the environment variable and view the Configuration. Then hover over the property label you wish to set and note the "env:" value. This is the fully qualified name of the environment variable that can be added to the
docker-compose.override.yml . For example, the "SMTP Host" on the "Email Configuration" will show "env: NOTIFICATION_EMAIL_EMAILNOTIFICATIONCONFIGURATION_SMTPHOST".
To avoid ambiguity, the fully qualified environment variable is recommended. However, in many cases, the environment variable name can be shortened to the shortest suffix which as at least one underscore. So the above example, the SMTP host can be shortened to EMAILNOTIFICATIONCONFIGURATION_SMTPHOST.
Once you determine the correct environment variable, then default value for the configuration can be set in the
docker-compose.override.yml . For example:
In this case, the default value will be set automatically. However, the value may be changed by an administrator using the application UI.
If wish to enforce a value for a particular configuration value, the prefix the environment variable name with "OVERRIDE_", for example:
With this value set, the administrative user will be unable to change the value.
Using the "OVERRIDE" option may create confusion for the administrative user. The UI will appear to allow the user to change a value. But immediately after saving the change, the value will revert to the overridden value. The UI is unaware of the environment variables and does not warn the user that the value has been overridden.