Upgrading 9.4 to 10.0

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!

Remediation of a Security Vulnerabilitiy in the Use of Environment Variables and System Properties

From version 10.0.185

This upgrade note is only relevant if none of the security upgrade 9.3.284, or 9.4.225 has been performed to date.

Cadenza had a potential security vulnerability in the Management Center, which will be fixed with this upgrade. Affected are

  • Cadenza data sources that do not use a data source template and instead use system properties or environment variables when manually entering connection parameters.

  • Static data restrictions for objecttypes that use system properties or environment variables when defining the condition.

Affected content must be migrated.

Before migrating the affected content, Cadenza must be upgraded, including the usual schema migration of the databases. The affected data sources and static data restrictions can then be determined and migrated.

Migration of Affected Cadenza Data Sources

For the definition of data sources in the Management Center, environment variables and system properties are no longer supported when manually entering the connection parameters. Cadenza variables can also no longer be used. If environment $SYSTEM/$VAR properties are required, the connection parameters must now be defined using a template in the repositorydatasourcetemplates-config.xml configuration file. The configuration file has been extended accordingly so that $SYSTEM/$VAR properties can also be used for the authentication data.

The following steps are necessary to identify and migrate data sources affected by this change:

Step 1: Checking whether data sources are affected by the change

Each repository database configured in your repositoryList.xml file must be checked. The following script can be used:

select ds.repository_name, ds.name, ds.print_name, ds.template_id, ds.url,
       ds.driver_name, ds.user_name, ds.identified_by
  from data_source ds
  where ds.url           like '%$VAR{%'  or ds.url           like '%$SYSTEM{%'
     or ds.driver_name   like '%$VAR{%'  or ds.driver_name   like '%$SYSTEM{%'
     or ds.user_name     like '%$VAR{%'  or ds.user_name     like '%$SYSTEM{%'
     or ds.identified_by like '%$VAR{%'  or ds.identified_by like '%$SYSTEM{%'

If the script returns no results, no data sources are affected.

Step 2 (if data sources are affected): Migrating of the data sources

  1. In repositorydatasourcetemplates-config.xml file: A template with the connection parameters must be defined for each affected data source.

  2. In the Cadenza Management Center: Each affected data source must be converted from the manual to the template-based definition with the associated template.

Do not change the IDs of existing templates that are already in use! Instead, you can create a new template with the new ID and assign it to the data sources in the Management Center. Before you remove an obsolete template from the configuration file, make sure in the Management Center that this template is not used by any data source.
Warning Data source uses unknown templateId: To resolve this error, add a template for each unknown ID in repositorydatasourcetemplates-config.xml file. You can then assign a new template to the affected data sources in the Management Center and delete the obsolete templates from the configuration file.

For WMS, WMTS, or Vector Tile data sources, we also recommend:

  • Do not use any environment variables or system properties that refer to sensitive information, as this information is automatically visible to users of these layers when accessing the geodata server directly. Geodata servers without authentication are currently always accessed directly. In this case, $SYSTEM/$VAR properties that are used in the URL are resolved and their values are automatically visible to the users of these layers. For geodata servers with authentication, access is not direct, but always via Cadenza. In this case, sensitive information in the URL remains hidden from the users of these layers.

Migration of Affected of Static Data Restrictions for Objecttypes

Environment variables and system properties are no longer supported for the definition of static data restrictions for an objecttype in the Management Center. The use of Cadenza variables is still possible.

To determine and migrate static data restrictions that are affected by this change, the following steps are necessary:

Step 1: Checking whether static data restrictions are affected by the change.

Each repository database configured in your repositoryList.xml file must be checked. The following script can be used:

select ot.repository_name, ot.name, ot.print_name, otm.print_name
  from objecttype_restriction otr
    inner join objecttype_member otm on otr.referenced_member_id = otm.objecttype_member_id
    inner join objecttype ot on otm.objecttype_id = ot.objecttype_id
  where otr.restriction_value like '%$SYSTEM{%'

If the script returns no results, no static data restrictions are affected.

Step 2 (if static data restrictions are affected): Migrating of the data restrictions

  1. In the variables.xml file: A variable ($VAR) must be added for each required environment variables or system properties ($SYSTEM).

  2. In the Cadenza Management Center: For each affected static data restriction, the environment variables or system properties ($SYSTEM) must be replaced by the corresponding Cadenza variable ($VAR).

Installing

Installation from an archive file has been simplified: It is no longer necessary to run an installer. After unpacking, the Cadenza server can be started directly by executing the start script start_cadenza.bat or start_cadenza.sh.

Before starting the server, some important settings can be made as follows:

  • For customizing locale, encoding and port, there is a new file cadenza_settings.bat or cadenza_settings.sh.

  • The setenv.bat or setenv.sh file where environment variables can be defined and set can now be found in the tomcat/bin directory.

Splitting Cadenza Workbooks and Cadenza Classic

With Cadenza 2024 Summer (10.0), we have separated Cadenza Workbooks and Cadenza Classic. Hybrid use of Cadenza is no longer possible. Version 10.0 requires at least the following changes:

  • Cadenza can now also be operated without the XML repositories originating from Cadenza Classic. This is the recommended operating mode for new projects. In the repositoryList.xml file, only the connection to the database repository remains (<databaseRepository>).
    If your Cadenza installation was originally set up with content from Cadenza Classic, it may be useful or necessary to continue using individual options from XML repositories for a transitional period. For this reason, the following elements from XML repositories will continue to be supported for the time being:

    • Classic layers that are provided in the Navigator, e.g. layers with display settings that cannot currently be fully implemented in Cadenza Workbooks, or layer types that are not yet natively supported by Cadenza Workbooks. If selector layers are still required, the associated objecttypes and filter forms will also continue to be supported.

    • Display options templates for layers

    • Start map from the MML as the basis for new map views

  • As XML repositories may contain other elements that are not supported by Cadenza due to their history in Cadenza Classic, we recommend that you view them and remove elements that are no longer used. An example of this is the configuration file gistermgazetteer-config.xml, which in 2023 Autumn Spring (9.3) has been replaced by the settings option in the Management Center and the configuration file locationfinderweb-config.xml.

    Important: If you remove folders and files, you must also remove their references in the repositoryTree.xml and templates.xml files.

    • The following folders can be removed from the root folder of an XML repository:

      • Charts folder, Help folder, MapDesign folder, PreviewImages folder, SpatialVisualizations folder, Reports folder and Workflows folder

      • Scripts folder, Selectors folder, TableAnalyzer folder and Tables folder. Important: Do not remove files (*.sel, *.top, etc.) that are still needed for Classic (selector) layers used in workbooks.

    • The following files can be removed:

      • From the Map folder in the root folder of an XML repository:

        • *.mml and *.layer files.
          Important: Do not remove Classic maps that are still needed as start or overview maps, or Classic layers that are still needed for map views in workbooks. However, if Classic maps and Classic layers are no longer needed in workbooks, remove the Map folder.

        • defaultFeatureInfo.xhtml in the LayerConfiguration folder

      • chaining.xml, gistermgazetteer-config.xml, layerSelectorResultProcessing.xml and permalinklist.xml in the root folder of an XML repository

  • If the Classic user administration is still used:

    • If an XML repository is still required for Classic layers, e.g. for the provision of a start map with overview map, please note that Cadenza no longer checks any authorizations for content from XML repositories.

    • To make a user a super administrator, they must be assigned to a group with super administrator authorization in the Management Center.

  • In the plugins.xml file, the Classic-only plugins and modules must be removed, otherwise Cadenza will not start.

    • The following plugins must be removed, if present:
      ExcelImport, Filesystem_Restriction, Integration_Application_Framework_WPS, Navigator_Bookmarks, ReportDesigner, Report_Jaspersoft_Studio, RepositoryManager, PluginConfiguration, ResultTableEditor, Permalink, Selector_SqlViewer, TableAnalyzer_Execute_Csv, Gis_DataSource_Oracle_Manage, Gis_DataSource_PostGis_Manage, Gis_Gazetteer,Gis_Import_Shape_To_Oracle, Gis_MapDesigner, Gis_Mobile_Export, Gis_Sld_Export, Gis_Topology, Gis_Wps, GarbageCollection

    • The following modules, which could be integrated without a plugin, must be removed, if present:
      AccessManagerLdapSyncModule, BrandingModule, GisTermProConfigurableActionsModule, GIStermProModule, IsoLineServiceDesktopModule, PostGisDesktopModule, SdoManagementConfigurationModule, OsmRasterLayerDesktopModule, GisTermScriptingDesktopModule, GisTermTileCacheSetDesktopModule, CadenzaConfigurableMenuProModule, CadenzaProModule, LocalDatasourceModule, MapServicePublishModule, ScriptingRModule, BusinessChartDesktopModule, WpsDesktopModule

  • The following Classic-only configuration files must be removed, if present:
    accessmanagerldapsync-config.xml, branding-config.xml, cadenzaconfigurablemenupro-config.xml, cadenzapro-config.xml, chartdesktop-config.xml, executecsv-config.xml, filesystem-config.xml, garbagecollection-config.xml, gistermpro-config.xml, gistermproconfigurableactions-config.xml, gistermtilecachesetdesktop-config.xml, gistermscriptingdesktop-config.xml, isolineservicedesktop-config.xml, localdatasource-config.xml, mapdesignerpro-config.xml, mapservicepublish-config.xml, osmrasterlayerdesktop-config.xml, permalink-config.xml, postgisdesktop-config.xml, scriptingr-config.xml, sdomanagementconfiguration-config.xml, wpsarcgisproxy-config.xml, wpsdesktop-config.xml, wpslocalprocess-config.xml, wpsproxy-config.xml, wpsserver-config.xml

  • The Classic Theming API is no longer supported (see Branding and Customizing).

  • WPS is no longer supported. The "Gis_Wps" plugin and the configuration file wpsserveridentification-config.xml must be removed, if present.

  • The configuration file basicweb-config.xml has been cleaned up.

    • The following elements must be removed, if present:
      context, supportedBrowsers, projectName, dataPath, webInfLibPath, helpUrl, classicHelpUrl, projectUrl, organizationUrl, management > maxViews, appearance > map, appearance > mapAsStartPage

    • Menu entries (menuEntries) with the following IDs must be removed, if present:
      selector, result, diagram, map, reloadRepository, resourceMonitoring, about, help-classic, logout, userprofile, custom

Authentication and Authorization

  • Cadenza now requests the user’s real name (if available) to show them in the UI, e.g. when displaying the owner of an element or sharing elements. With the optional <userPrintNameSuggestion> element it can be controlled for which provider the real names should be requested. If no real names should be displayed, the <userPrintNameSuggestion> element in the accessmanager-config.xml file must be empty.

Branding and Customizing

  • The system properties / environment variables CADENZA_ASSETS_BASE_PATH and CADENZA_CONTENT_BASE_PATH have been deprecated in favor of the new CADENZA_THEMES_PATH, as they are usually used together anyway. The deprecated properties will no longer be supported after one year after the release of Cadenza 10.0.

  • Cadenza Classic theming has been removed:

    • In the theme.js, the classic-map-* and custom-map-\* features and the info-link-target property have no effect anymore and should be removed from the file.

    • The .d-route-print-layout—​branding-top-left CSS class is not used anymore in Cadenza. Corresponding styles should be removed from the customerGlobal.css.

    • The following template functions are no longer supported and should be removed from your custom page content or you will get errors in Cadenza:

      • classicExternalApplicationUrl

      • customMenu

Caching

  • Support for the previously deprecated <maxSize> element of a <cache> in the cache-config.xml has been removed. If you still have it in your cache-config.xml, Cadenza won’t start.

Operating

  • Running Cadenza as a Windows service is not yet possible with this release.

  • Because we switched to a different connection pool implementation, some metrics are no longer supported:

    • cadenza_datasource_connection_max_borrow_waiting_time_milliseconds

    • cadenza_datasource_connection_max_waiting_time_milliseconds

    • cadenza_datasource_connection_mean_active_time_milliseconds

    • cadenza_datasource_connection_mean_idle_time_milliseconds

    • cadenza_datasource_connection_mean_borrow_waiting_time_milliseconds

    • cadenza_datasource_connections_borrowed_total

    • cadenza_datasource_connections_created_total

    • cadenza_datasource_max_idle_connections