Overriding Configuration Using Environment Variables or System Properties

To override configuration settings using environment variables or system properties, the env mode must be activated. This mode enables you to:

  • Override existing configuration values

  • Define new configuration values not yet present in the file-based configuration

Each setting to be overridden is specified as a key-value pair. The key follows a hierarchical, case-insensitive structure that starts with cadenzaconfig. This prefix ensures the override applies specifically to Cadenza configuration.

Key Format

The key structure reflects the path to the setting as it appears in the YAML configuration. Underscores (_) are used to indicate nesting. The general format is:

cadenzaconfig_<section>_<subsection>..._<setting>=<value>

List Indexing

If a section of the configuration corresponds to a list, numeric values in the key are interpreted as indexes into that array.

For example, consider a configuration where multiple spatial reference systems are defined in a list, and we want to override a property of the fourth entry (index 3):

cadenzaconfig_workbookmap_availableSpatialReferenceSystems_srs_3_defaultMapExtent_minX=-335780.0

Here, 3 is not a key name, but an index into the srs list.

This corresponds to the following YAML structure:

cadenzaconfig:
  workbookmap:
    availableSpatialReferenceSystems:
      srs:
        - ...
        - ...
        - ...
        - defaultMapExtent:
            minX: -335780.0

Setting via Environment Variables

You can define environment variables before starting the application, for example like this in bash:

export CADENZACONFIG_WORKBOOKMAP_AVAILABLESPATIALREFERENCESYSTEMS_SRS_3_DEFAULTMAPEXTENT_MINX=-335780.0
It is a convention to uppercase the names of environment variables, Cadenza will interpret them case-insensitively.

Setting via Java System Properties

Overrides can also be passed as system properties when launching the JVM:

-DCADENZACONFIG_WORKBOOKMAP_AVAILABLESPATIALREFERENCESYSTEMS_SRS_3_DEFAULTMAPEXTENT_MINX=-335780.0

This behaves identically to environment variables.

Notes and Limitations

There are limitations when using environment variables or system properties for configuration:

  • Multi-line strings cannot be represented

  • Null values cannot be distinguished from empty values

  • Boolean values must be passed as strings (e.g. true, false)

  • List and object structures must be overridden at specific indices or paths — new elements cannot be inserted dynamically

For complex changes, it is better to edit the YAML or XML configuration files directly.