Page tree
Skip to end of metadata
Go to start of metadata

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 IdEnvironment Variable Suffix
org.ssdt_ohio:ssdt.common.notification-emailSSDT_COMMON_NOTIFICATION_EMAIL or NOTIFICATION_EMAIL
org.ssdt_ohio:ssdt.common.masschangeSSDT_COMMON_MASSCHANGE or MASSCHANGE
org.ssdt_ohio:usas.usps-integrationUSAS_USPS_INTEGRATION


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:

environment:
      - INSTALL_NOTIFICATION_EMAIL=1
      - INSTALL_SSDT_COMMON_MASSCHANGE=1
      - INSTALL_USAS_USPS_INTEGRATION=1

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:

environment:
   - EMAILNOTIFICATIONCONFIGURATION_SMTPHOST=mx1.example.org

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:

environment:
   - OVERRIDE_EMAILNOTIFICATIONCONFIGURATION_SMTPHOST=mx1.example.org

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.