Upgrading 10.4 to 10.5

When migrating to a new Cadenza version:

  1. Check and update database schemas using the Database Migration Tool.

    • Backup your database before running the tool, as schema structures may change.

  2. Check and update the Cadenza API. The recommended version of Cadenza JS for use with this Cadenza version is v11.0.2 (see the release notes).

  3. If you use workbook reports with your own binaries of Chromium and ChromeDriver, check and update ChromeDriver. The version of ChromeDriver for use with this Cadenza version is v145 (see System Requirements).

Applying updates in sequence is strongly recommended, as skipping versions may lead to increased update effort.

Users and Cadenza administrators find additional migration notes in the user documentation.

Configuration Changes

New Mandatory Configuration

The following plugins now have mandatory configuration. They were previously technically optional but de facto required for sensible operation of the feature:

Changes to the accessmanager Configuration

The legacy CadenzaDb authenticator has been removed. The corresponding settings have to be removed from the accessmanager Configuration.

In addition, the OAuth authenticator has been replaced with the new Oidc authenticator. This also results in several changes in its specific configuration, which are detailed in a separate chapter below.

The authenticators CadenzaDb and OAuth are no longer available as a value for

  • authenticators > authenticator > refid

  • authenticators > authenticator > groupMapping > refid

  • authenticators > authenticator > propertyMapping > refid

  • userSuggestion > providers (> provider)

  • userPrintNameSuggestion > providers (> provider)

Corresponding entries must be removed. Path components in parentheses apply to XML configuration only and are omitted in YAML and environment properties configuration. Instead of the OAuth authenticator, the new Oidc authenticator can be used as a value instead in the above-mentioned places.

The following settings must be removed completely, if present:

  • passwordEncryptor

  • additionalLoginHelpLink

  • autoLoginUserName

  • securityPolicies

  • polling

  • authentication

  • authorization

Changes to the basicweb Configuration

maxConcurrentUsers is now Optional

The basicWebConfiguration > management > maxConcurrentUsers setting in the basicweb Configuration has been made optional.

Cadenza now defaults to 1000 maxConcurrentUsers. This value will be taken together with the allowed number of concurrent users in your Cadenza license, and the smallest value will be used to determine the final concurrent user limit.

Most Cadenza licenses allow fewer than 1000 concurrent users, and most installations don’t require more than 1000 concurrent users per node anyway. This means that in most cases the configuration can be simplified by removing the maxConcurrentUsers option.

If that was all that you had previously configured in the management section, you can now remove that entire section as well.

Removal of the layout Element

The basicWebConfiguration > layout is no longer used and has been removed. If you have it in your configuration, you must remove this setting.

Changes to the messagebroker Configuration

The messagebroker > addressMappings setting must be removed, if present.

Changes to the gisterm Configuration

The following settings were unused and should be removed from your configuration, if present:

  • tuning > capabilities > disposeOldRasterDataOnNavigation

  • tuning > imageCatalog : remove the imageCatalog setting and its children

  • tuning > restrictions > selectorLayer : remove the selectorLayer setting and its children

Removed Plugins

The following plugins must be removed if present or Cadenza will not start:

  • Gis_DataSource_Csv

  • Gis_DataSource_GeoPackage

  • Gis_DataSource_OsmRaster

  • Gis_DataSource_SpatiaLite

  • Gis_Offline

  • Gis_Raster_Cache

OAuth Configuration Reworked and Renamed to OIDC

Several extensions to our support for OpenID Connect (short: OIDC) authentication have made an overhaul of the configuration necessary. At that point, we have renamed the plugin and configuration and reworked it to better reflect its scope.

Changed plugin and configuration

The plugin Accessmanager_OAuth is no longer supported.

If this plugin was previously used, it must be replaced with the plugin Accessmanager_Oidc and the accessmanageroauth settings must be replaced with the accessmanageroidc Configuration. See also the example configuration.

Some main changes to it:

  • The root element in XML configuration is now accessmanagerOidcConfiguration instead of accessmanagerOAuthConfiguration

  • In YAML configuration the settings are now under accessmanageroidc

  • The structure has changed, all non-root elements are bundled under the new element identityProvider.

  • The new optional issuerUrl element can be used to discover several other configuration elements including, for example, the publicKey. Discovery (of the publicKey) enables Cadenza to support the OpenID Connect Key Rollover process. The discoverable elements are therefore optional in the configuration if discovery via the issuerUrl is used. If discovery is enabled and a discoverable element is configured, then the configured value is used instead. These are the discoverable elements:

    • publicKey including its type and the signature algorithm

    • authenticationUrl

    • tokenUrl

    • logoutUrl

    • adminServiceUrl

  • The adminService element has been split into definition of its used provider and the discoverable adminServiceUrl.

  • The relyingPartyInitiatedLogout element has been split into the boolean to define if it is used and the discoverable logoutUrl.

  • The allowTokenPassthrough is now optional with the default false. It is no longer required for the relyingPartyInitiatedLogout.

  • The publicKey now also has the attribute algorithm (was formerly the separate element signatureAlgorithm).

  • The publicKey is now required with its attributes if discovery via the issuerUrl is not enabled.

  • The configuration options of groupMapping now are identical to those for JWT: In the claimPath element JSONPaths are supported, replacing the old way of configuring groups via the claimValueStructure. And simpleMapping with its attributes was adapted to be identical to the staticMapping in JWT with its attributes claimValue and groupName. Be aware that the static mapping is now deprecated for Open ID Connect: Use the dynamic mapping in combination with the ui feature "Group mapping IDs" instead.

Changed authenticatorId

The authenticatorId OAuth is no longer supported, use OIDC instead for OpenID Connect in the accessmanager Configuration as mentioned in its separate chapter above.

Changed monitoring metrics

The metric class oauth was replaced with oidc. Further information can be read at Monitoring Metrics

shapefile Configuration no Longer Used

The shapefile configuration (either as an XML configuration file called shapefile-config.xml or as a section called shapefile in the single file configuration) is no longer used by Cadenza. You should remove the settings from your configuration.

wfs Configuration no Longer Used

The wfs configuration (either as an XML configuration file called wfs-config.xml or as a section called wfs in the single file configuration) is no longer used by Cadenza. You should remove the settings from your configuration.

Other Changes

Documentation is no Longer Included in the Cadenza Distribution

We no longer bundle a copy of the Cadenza Help and Learning documentation with the Cadenza WAR file or Docker images. This reduces their size significantly.

The full Cadenza documentation is available online. It is regularly updated by Disy. The Cadenza documentation includes:

  • Learning modules

  • User documentation

  • Administrator documentation

  • Developer documentation

In the Cadenza demo distribution, the "Help" menu now links to the learning modules and user documentation available online.

If you need to host the documentation in your own infrastructure, you can use a new docker image we provide. See Self-Hosting Cadenza Documentation for more information on this.

To customize the Cadenza "Help" menu to link to your own hosted versions, see the Customizing the Help Menu documentation.