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.

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

Cadenza comes out of the box with some core functionality that is always on and that requires some configuration. We will go over it in this example.

In addition to this core functionality you can enable additional features through plugins. The names and purposes of all available plugins are documented in Plugins.

In our minimal example we will at least have to select some way for our users to authenticate to Cadenza.

  • Multi-File XML

  • Single-File YAML

plugins.xml
<?xml version="1.0" encoding="UTF-8"?>
<pluginConfig>
  <plugins>
    <plugin name="AccessManager_Embedded"/>
  </plugins>
</pluginConfig>
singlefileconfig.yaml
cadenzaconfig:
  plugins:
    - "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 Core Functionality

Cadenza includes functionality that is central to its operation and is automatically activated. This requires some configuration so Cadenza can start.

You can use the Plugins documentation to see what configuration is required. For the core functionality this is:

Note that these configurations can sometimes require setting a secret like a password for example. We have a dedicated page that describes how we deal with secrets in configuration.

  • Multi-File XML

  • Single-File YAML

accessmanager-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<userRegistry>
  <authenticators>
    <authenticator refid="Embedded"/>
  </authenticators>
</userRegistry>
basicweb-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<basicWebConfiguration>
  <management>
    <maxConcurrentUsers>10</maxConcurrentUsers>
  </management>
</basicWebConfiguration>
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>
jobs-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<jobsConfig>
  <datasource>
    <driverName>text</driverName>
    <jdbcURL>text</jdbcURL>
    <user>text</user>
    <password>text</password>
  </datasource>
  <execution>
    <workerThreadPoolSize>10</workerThreadPoolSize>
  </execution>
</jobsConfig>
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:
    accessmanager:
      authenticators:
        authenticator:
          refid: "Embedded"
    basicweb:
      management:
        maxConcurrentUsers: 10
    configurationdatabase:
      database:
        driverName: "$VAR{FOOBAR}"
        jdbcURL: "text"
        user: "text"
        password: "text"
    jobs:
      datasource:
        driverName: "text"
        jdbcURL: "text"
        user: "text"
        password: "text"
      execution:
        workerThreadPoolSize: 10
    userpreferences:
      database:
        driverName: "text"
        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).

  • Multi-File XML

  • Single-File YAML

accessmanagerembedded-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<embedded>
  <users>
    <user>
      <loginName>johndoe</loginName>
      <password>secretpassword</password>
      <groups>
        <group>Admin</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:
    accessmanager:
      # AccessManager configuration (omitted for clarity)
    basicweb:
      # BasicWeb configuration (omitted for clarity)
    configurationdatabase:
      # ConfigurationDatabase configuration (omitted for clarity)
    jobs:
      # Jobs configuration (omitted for clarity)
    userpreferences:
      # UserPreferences configuration (omitted for clarity)
    accessmanagerembedded:
      users:
        user:
          - loginName: "johndoe"
            password: "secretpassword"
            groups:
              group:
                - "Admin"

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:
    accessmanager:
      authenticators:
        authenticator:
          refid: "Embedded"
    basicweb:
      management:
        maxConcurrentUsers: 10
    configurationdatabase:
      database:
        driverName: "$VAR{FOOBAR}"
        jdbcURL: "text"
        user: "text"
        password: "text"
    jobs:
      datasource:
        driverName: "text"
        jdbcURL: "text"
        user: "text"
        password: "text"
      execution:
        workerThreadPoolSize: 10
    userpreferences:
      database:
        driverName: "text"
        jdbcURL: "text"
        user: "text"
        password: "text"
    accessmanagerembedded:
      users:
        user:
          - loginName: "johndoe"
            password: "secretpassword"
            groups:
              group:
                - "Admin"