Creating and Editing Configuration Settings

Single-File Configuration

Prerequisites

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 activate plugins, you need the names of the plugins. Some plugins are mandatory.

  • To configure plugin-specific settings, you need the ID of the configuration, along with the corresponding setting names. The applicable configurations depend on the activated plugins.

The names of plugins and configuration IDs are documented in Plugins and Their Configurations.

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:

    • plugins (mandatory): Defines the plugins to activate

    • variables (optional): Defines named variables that can be reused throughout the configuration

    • settings (mandatory): Defines all mandatory and optional settings for the activated plugins

      • Each entry in settings begins with the configuration ID, followed by the specific settings to apply

Multi-File Configuration

Prerequisites

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:

  • plugins.xml: Defines which plugins to activate

  • variables.xml (optional): Defines named variables

  • All required configuration files for each activated plugin, using the plugin’s configuration ID to derive the file name:

    <configuration ID>-config.xml

    For example, to configure the basicweb configuration for the Cadenza plugin, the corresponding file name would be:

    basicweb-config.xml

Example Configuration Walkthrough

This example illustrates a minimal configuration using both single-file and multi-file formats. It highlights the general structure and the differences between the two modes.

Selecting Plugins

First, you must define which plugins to activate. All mandatory plugins must be included, and you can add any additional ones based on the functionality you need. The names and purposes of all available plugins are documented in Plugins and Their Configurations.

  • Multi-File XML

  • Single-File YAML

plugins.xml
<?xml version="1.0" encoding="UTF-8"?>
<pluginConfig>
  <plugins>
    <plugin name="Cadenza"/>
    <plugin name="Gis"/>
    <plugin name="AccessManager"/>
    <plugin name="AccessManager_Embedded"/>
  </plugins>
</pluginConfig>
singlefileconfig.yaml
cadenzaconfig:
  plugins:
    - "Cadenza"
    - "Gis"
    - "AccessManager"
    - "AccessManager_Embedded"

Defining Variables (Optional)

You can optionally define named variables that can be reused in later parts of the configuration.

  • Multi-File XML

  • Single-File YAML

variables.xml
<?xml version="1.0" encoding="UTF-8"?>
<variables>
  <variable name="FOOBAR">$SYSTEM{SOMEENVIRONMENTVARIABLE}</variable>
</variables>
singlefileconfig.yaml
cadenzaconfig:
  plugins:
    # Plugins are configured here (omitted for clarity)
  variables:
    variable:
      - name: "FOOBAR"
        value: "$SYSTEM{SOMEENVIRONMENTVARIABLE}"

Configuring the Cadenza Plugin

The Cadenza plugin is one of the mandatory plugins and requires the basicweb and userpreferences configurations, as specified in Plugins and Their Configurations.

Note that the userpreferences configuration is the first in this example to use a secret (a database connection password in this case). We have a dedicated page that describes how we deal with secrets in configuration.

  • Multi-File XML

  • Single-File YAML

basicweb-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<basicWebConfiguration>
  <management>
    <maxConcurrentUsers>10</maxConcurrentUsers>
  </management>
</basicWebConfiguration>
userpreferences-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<userPreferencesConfiguration>
  <database>
    <driverName>text</driverName>
    <jdbcURL>text</jdbcURL>
    <user>text</user>
    <password>text</password>
  </database>
</userPreferencesConfiguration>
singlefileconfig.yaml
cadenzaconfig:
  plugins:
    # Plugins are configured here (omitted for clarity)
  variables:
    # Variables are configured here (omitted for clarity)
  settings:
    basicweb:
      management:
        maxConcurrentUsers: 10
    userpreferences:
      database:
        driverName: "text"
        jdbcURL: "text"
        user: "text"
        password:
          value: "text"

Configuring the AccessManager Plugin

The Gis plugin has no mandatory configuration, so we proceed to the next plugin with required settings: AccessManager. According to Plugins and Their Configurations, it requires the accessmanager and configurationdatabase configurations.

  • Multi-File XML

  • Single-File YAML

accessmanager-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<userRegistry>
  <authenticators>
    <authenticator refid="Embedded"/>
  </authenticators>
</userRegistry>
configurationdatabase-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<configurationDatabaseConfiguration>
  <database>
    <driverName>$VAR{FOOBAR}</driverName>
    <jdbcURL>text</jdbcURL>
    <user>text</user>
    <password>text</password>
  </database>
</configurationDatabaseConfiguration>
singlefileconfig.yaml
cadenzaconfig:
  plugins:
    # Plugins are configured here (omitted for clarity)
  variables:
    # Variables are configured here (omitted for clarity)
  settings:
    basicweb:
      # BasicWeb configuration (omitted for clarity)
    userpreferences:
      # UserPreferences configuration (omitted for clarity)
    accessmanager:
      authenticators:
        authenticator:
          refid: "Embedded"
    configurationdatabase:
      database:
        driverName: "$VAR{FOOBAR}"
        jdbcURL: "text"
        user: "text"
        password: "text"

Configuring the AccessManager_Embedded Plugin

Finally, we configure the AccessManager_Embedded plugin, which requires the accessmanagerembedded configuration (see Plugins and Their Configurations).

  • Multi-File XML

  • Single-File YAML

accessmanagerembedded-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<embedded>
  <users>
    <user>
      <loginName>johnviewer</loginName>
      <password>secretpassword</password>
      <groups>
        <group>Viewer</group>
      </groups>
    </user>
  </users>
</embedded>
singlefileconfig.yaml
cadenzaconfig:
  plugins:
    # Plugins are configured here (omitted for clarity)
  variables:
    # Variables are configured here (omitted for clarity)
  settings:
    basicweb:
      # BasicWeb configuration (omitted for clarity)
    userpreferences:
      # UserPreferences configuration (omitted for clarity)
    accessmanager:
      # AccessManager configuration (omitted for clarity)
    configurationdatabase:
      # ConfigurationDatabase configuration (omitted for clarity)
    accessmanagerembedded:
      users:
        user:
          - loginName: "johnviewer"
            password: "secretpassword"
            groups:
              group:
                - "Viewer"

Complete YAML Single-File Configuration Example

As we have only showed the individual configuration settings int he steps before, here is the complete example YAML file for reference:

cadenzaconfig:
  plugins:
    - "Cadenza"
    - "Gis"
    - "AccessManager"
    - "AccessManager_Embedded"
  variables:
    variable:
      - name: "FOOBAR"
        value: "$SYSTEM{SOMEENVIRONMENTVARIABLE}"
  settings:
    basicweb:
      management:
        maxConcurrentUsers: 10
    userpreferences:
      database:
        driverName: "text"
        jdbcURL: "text"
        user: "text"
        password:
          value: "text"
    accessmanager:
      authenticators:
        authenticator:
          refid: "Embedded"
    configurationdatabase:
      database:
        driverName: "$VAR{FOOBAR}"
        jdbcURL: "text"
        user: "text"
        password: "text"
    accessmanagerembedded:
      users:
        user:
          - loginName: "johnviewer"
            password: "secretpassword"
            groups:
              group:
                - "Viewer"