Upgrading 10.1 to 10.2

Database schemas for the infrastructure features must be checked with each new Cadenza version and updated if necessary. The Database Migration Tool is available for this purpose.
It is strongly recommended to make a backup before using this tool, as the structures of the schemas may change!

Upgrade information relating to the user interface (including access settings) can be found in the release notes of the user documentation.

System Properties Changes

The following system properties are no longer supported by Cadenza:

  • cadenza.configFile → no longer supported, must be removed. The file must now always be named core-config.xml. See Configuration File Changes for the 'core' configuration for further details.

  • cadenza.configDir → you must use the environment variable (or system property) CADENZA_CONFIG_PATH to specify a full path to the directory containing the Cadenza configuration files.

  • cadenza.codeBase → no longer relevant, will be ignored if specified but should be removed from your startup scripts

  • cadenza.workDir → no longer relevant, will be ignored if specified but should be removed from your startup scripts

See Environment Variables, System Properties and Other Runtime Configuration Options for a full overview of all the settings you can pass when starting Cadenza.

Configuration File Changes

Removal of the baseConfiguration and base-config.xml Capabilities

This version of Cadenza introduces new ways to override or extend a base configuration.

With this addition we have removed two old mechanisms that were used to extend an existing set of configuration. These were sometimes used in Classic Desktop installations of Cadenza. These mechanisms no longer work starting with this version:

  • Some configuration files would allow you to define a <baseConfiguration> element that could refer to another configuration file of the same type. All settings in the one file would override and extend those of the baseConfiguration file. The <baseConfiguration> can no longer be used.

  • A configuration directory could contain a base-config.xml file that would point to another directory and the final configuration of Cadenza was a result of merging together the files of those directories. The base-config.xml file is now ignored by Cadenza.

Core Cadenza configuration, former cadenza-config-web.xml

The central Cadenza configuration file, usually named core-config.xml, potentially renamed by the now removed system property cadenza.configFile is now

  • no longer required

  • always named core-config.xml to align with the naming of configuration files and the new configuration modes

  • no longer supporting declaring a variablesFile element to specify another variables.xml file

  • still supporting a repositoryListFile element, yet we discourage using this mechanism and recommend using environment variables instead

  • treated like other configuration files, i.e. it is possible to use $VAR variables and resides in the config directory

In case no variablesFile that differs from the default value variables.xml was declared in the cadenza-config-web.xml, the only necessary actions are to rename the file to core-config.xml and remove the variablesFile element if any.

In cases where the file was just renamed using the cadenza.configFile system property and no other such files were used for an installation, the only necessary actions are to remove that system property, rename the file to core-config.xml and remove the variablesFile element if any.

In all other cases, like when multiple core config files were in use for an installation, and potentially declared separate variables.xml files, then it is necessary to rethink the use case. By declaring or modifying configuration through environment variables using regular $SYSTEM variables or the new env mode most common use cases can be recreated.

Breaking Changes in purposeofrequest-config.xml

If the Purpose_Of_Request plugin is activated, the purposeofrequest-config.xml file must be adapted, if present (otherwise Cadenza will not start).

The result of the settings has not changed, but instead of having a fields element containing a list of up to two select or textfield elements in arbitrary order, there are now the new firstField and secondField elements. The firstField is mandatory, the secondField is optional, both can contain either one of the previous select or textfield elements.

To migrate, remove the fields element, keeping its content(s). Then wrap your first select or textfield element in a firstField element, and if needed act accordingly with the second input field.

Unused Settings removed from gisterm-config.xml

The following Classic-only elements must be removed from gisterm-config.xml file, if present (otherwise Cadenza will not start):

  • Under gistermConfiguration remove the element general completely

  • Under gistermConfiguration remove the element gui completely

  • Under gistermConfiguration → presentation remove the following elements:

    • activeMaxScale

    • labelReferenceScale

    • logo

    • intervalClassificationDefaulDecimalFormat

    • generalFeatureLayerConfigurationFileName

    • measurementAngle

    • editingAngle

    • defaultObjectInfoBehavior

  • Under gistermConfiguration remove the element gisTermServer completely

  • Under gistermConfiguration → tuning remove the following elements:

    • featureCollection

    • display

  • Under gistermConfiguration → tuning → restrictions remove the following elements:

    • maxThemesPerMap

    • printQueryThreadCount

    • maxClientLayerSize

  • Under gistermConfiguration → tuning → restrictions → layerLoading remove the following element:

    • parallelThreads

Removed Classic-only Configuration Files

The following Classic-only configuration files can be removed, if present:

  • gistermselector-config.xml

  • layertemplate-config.xml

The automatic trimming of leading and trailing whitespace from values in XML configuration files has been removed

Leading and trailing whitespace characters for values in XML configuration files are now preserved.

Individual features may still ignore leading or trailing whitespace (e.g. when displayed in the browser).

Configuration of Spatial Reference Systems in the Management Center

Several configuration options relating to spatial reference systems are now defined via the user interface in the Management Center > System settings > Spatial reference systems. The following associated configuration settings are no longer required:

  • Favorite spatial reference systems previously defined in the workbookmap settings must be transferred to the Management Center. The workbookmap settings, e.g. the workbookmap-config.xml file, is no longer used and should be removed if present.

  • Spatial reference system for CDS previously defined in the manageddata settings must be transferred to the Management Center. The manageddata settings, e.g. the manageddata-config.xml file, is no longer used and should be removed if present.

  • Default spatial reference system for coordinate display previously defined in the gistermweb settings (defaultCoordinateVisualizationSrs) must be transferred to the Management Center. The defaultCoordinateVisualizationSrs setting, e.g. in the gistermweb-config.xml file, is no longer used and should be removed if present.

The availableReferencingSystems element is unused and can be removed from the referencingconfiguration-config.xml file.

Automatically Generated Cluster Secret

In the basicweb-config.xml configuration file, the <clusterSecret> element must be removed, otherwise Cadenza will not start. Cadenza now automatically generates this secret at boot time and distributes it among the cluster. This improves security by automatically generating a high entropy secret and generating a new secret at every startup.

Experimental HSQL Support Removed

Support for HSQLDB for demonstration purposes as database for some Cadenza operating schemas and as a data source has been removed. This has never been a production-level feature.

New Windows Service Approach

The installation files for Cadenza as a Windows service are now located in the <cadenza_home>\tools\windows-service directory. Use the file (un)installCadenzaService.bat to install or uninstall the service (as administrator). You can also configure the service’s name, ID, and description in the cadenza-service.xml file. The service will use the same Tomcat startup scripts as the normal installation (e.g. setenv.bat). Additional files and configuration like service.bat are no longer needed.

Metrics Improvements

Changed Metrics Names

The names of the following metrics have changed in order to comply with the Open Metrics Exposition Format standard:

Old Name New Name

cadenza_workqueue_execution_time_measurements_total

cadenza_workqueue_execution_time_seconds_count

cadenza_workqueue_execution_time_seconds_total

cadenza_workqueue_execution_time_seconds_sum

cadenza_workqueue_max_execution_time_seconds

cadenza_workqueue_execution_time_seconds_max

cadenza_workqueue_waiting_time_measurements_total

cadenza_workqueue_waiting_time_seconds_count

cadenza_workqueue_waiting_time_seconds_total

cadenza_workqueue_waiting_time_seconds_sum

cadenza_workqueue_max_waiting_time_seconds

cadenza_workqueue_waiting_time_seconds_max

cadenza_dbpool_connection_creation_measurements_total

cadenza_dbpool_connection_acquire_time_seconds_count

cadenza_dbpool_connection_creation_time_seconds_total

cadenza_dbpool_connection_acquire_time_seconds_sum

cadenza_dbpool_connection_usage_measurements_total

cadenza_dbpool_connection_usage_time_seconds_count

cadenza_dbpool_connection_usage_time_seconds_total

cadenza_dbpool_connection_usage_time_seconds_sum

cadenza_web_report_pdf_size_measurements_total

cadenza_web_report_pdf_size_bytes_count

cadenza_jvm_gc_concurrent_phase_count

cadenza_jvm_gc_concurrent_phase_time_seconds_count

cadenza_jvm_gc_concurrent_phase_seconds_sum

cadenza_jvm_gc_concurrent_phase_time_seconds_sum

cadenza_web_report_pdf_size_bytes_total

cadenza_web_report_pdf_size_bytes_sum

cadenza_access_manager_request_time_total

cadenza_access_manager_request_time_seconds_count

cadenza_access_manager_requests_time_seconds_total

cadenza_access_manager_requests_time_seconds_sum

cadenza_access_manager_response_size_total

cadenza_access_manager_response_size_bytes_count

cadenza_access_manager_response_size_bytes_total

cadenza_access_manager_response_size_bytes_sum

Unit of duration metrics standardized to seconds

All duration metrics use seconds as time unit now. The following metrics had to be changed:

Old Name Old Time Unit New Name

cadenza_dbpool_configured_connection_idle_time_before_closing_milliseconds

milliseconds

cadenza_dbpool_configured_connection_idle_time_before_closing_seconds

cadenza_dbpool_configured_connection_max_waiting_time_milliseconds

milliseconds

cadenza_dbpool_configured_connection_max_waiting_time_seconds

cadenza_job_last_heartbeat

milliseconds

cadenza_job_last_heartbeat_seconds

cadenza_job_last_scheduling_check

milliseconds

cadenza_job_last_scheduling_check_seconds

cadenza_dbpool_configured_connection_idle_time_before_closing_milliseconds

milliseconds

cadenza_dbpool_configured_connection_idle_time_before_closing_seconds

Content-Type Header

The metrics endpoint now sets the Content-Type header.

By default it is text/plain; version=0.0.4; charset=utf-8.

When the new OpenMetrics output format is explicitly requested via Accept header, it is application/openmetrics-text; version=1.0.0; charset=utf-8.

New metric type "info"

Cadenza now also supports the metric type "info". Info metrics are used to expose textual information which don’t change during the process lifetime.

We use it for one metric: "cadenza_build_info" (previously "cadenza_build").

The info metric type is only used for the content type "application/openmetrics-text; version=1.0.0; charset=utf-8". When "text/plain; version=0.0.4; charset=utf-8" is requested, info metrics are reported as gauge instead.

Name with Prometheus format (= old name) Type with Prometheus format (= old type) Name with OpenMetrics Format Type with OpenMetrics format

cadenza_build

gauge

cadenza_build_info

info

Miscellaneous

  • Cadenza will now fail to start if the parameter net.disy.cadenza.web.cookies.samesite is set to none and the parameter net.disy.cadenza.web.session.cookies.secure is not set to true. That particular combination of settings would result in an invalid configuration. See How to Configure Cadenza for Embedding for more information on what these properties are for and how to correctly configure this.