How to Configure Cadenza

A Cadenza configuration involves the following steps:

Optionally defining named variables for reuse throughout the configuration
Deciding which of the features available by Cadenza edition are wanted and needed
Configuring all settings based on the chosen features and their requirements
Optionally configuring any further optional settings

These steps can be achieved using different approaches, referred to as configuration modes:

multi-file: Configures settings via multiple XML files stored in the Cadenza configuration directory
single-file: Configures settings via a single YAML configuration file
env: Allows settings to be configured or overridden via environment variables

Setting the Configuration Mode

By default, the multi-file and env modes are active. You can change this by setting the CADENZA_CONFIGURATION_MODE environment variable or system property.

Combining Configuration Modes

You can combine configuration modes if needed. The following combinations are supported:

multi-file, env (default)

Configuration is performed using multiple XML files located in the Cadenza configuration directory (see CADENZA_CONFIG_PATH) and can be overridden via environment variables or system properties.

multi-file

Configuration is performed exclusively using XML files in the configuration directory (see CADENZA_CONFIG_PATH). Overriding via environment variables or system properties is disabled.

single-file, env

Configuration is performed using a single unified YAML configuration file (see CADENZA_CONFIG_FILE) and can be overridden via environment variables or system properties.

single-file

Configuration is performed exclusively using a single YAML file (see CADENZA_CONFIG_FILE). Overriding via environment variables or system properties is disabled.

Single-File Configuration

Requirements

In single-file mode, all configuration settings are defined in a single configuration file in YAML format. The absolute path to this file must be specified using the CADENZA_CONFIG_FILE environment variable.

Creating and Editing the Single Configuration File

A configuration file can be created and edited manually:

To configure feature-specific settings, you need the ID of the configuration, along with the corresponding setting names. The applicable configurations depend on the available Cadenza features.

The Cadenza features and configuration IDs are documented in Cadenza Editions and Features.

The YAML configuration file follows a structured layout:

All configuration files begin with a top-level element called cadenzaconfig
The next level can include the following sections:
- variables (optional): Defines named variables that can be reused throughout the configuration
- settings (mandatory): Defines all mandatory and optional settings for the active features
  - Each entry in settings begins with the configuration ID, followed by the specific settings to apply

Multi-File Configuration

Requirements

In multi-file mode, configuration settings are defined in multiple XML files, stored in the Cadenza configuration directory—by default, <cadenza_home>/config. This directory can be customized using the CADENZA_CONFIG_PATH environment variable.

Creating and Editing the Multiple Configuration Files

The same types of information as in single-file mode must be provided but split across different XML files. At a minimum, you need:

variables.xml (optional): Defines named variables
All Cadenza features that require a configuration need to be provided a configuration file to become active, using the configuration ID to derive the file name:
```
<configuration ID>-config.xml
```
For example, to configure the basicweb Configuration, the corresponding file name would be:
```
basicweb-config.xml
```

Migrating From Multi-File Configuration to Single-File Configuration

Cadenza can log the current configuration in the single-file format. This can be a good way to bootstrap a migration to the new single-file format.

See Exporting Configuration via Logging.

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.