Upgrading: Important Changes

dotCMS versions are developed to automatically upgrade data to achieve backward compatibility whenever possible. When a dotCMS instance starts up, it will check the version of the database schema and ensure the data matches the version of dotCMS that is running. If an older version of the database is found, dotCMS will attempt to upgrade the data and data model automatically, before dotCMS is started. Additionally, dotCMS versions often update or remove old versions of libraries that are shipped with dotCMS. Unfortunately, it is not always possible to make upgrading data, libraries AND content both completely automatic and 100% backward compatible. When upgrading an older dotCMS installation, there are specific changes in the codebase and tooling that might require understanding and manual work in order to update the dotCMS installation to a working state.

There are hundreds of changes across dotCMS versions that affect all types of functionality. Most of these are captured in detail in our change log and github documentation for each version. Below are a list of major changes across versions that we have seen cause questions and issues as customers have upgraded from older versions.

Details by Version

23.10

• Default behavior change: dotCMS 23.10.24 (whether Current or LTS) initiates the default behavior of deleting versions of Content older than a year and greater than 100 versions ago. This will never include live or working versions of content. See Content Versions for information on how to adjust this behavior through environment variables.

23.06

• MSSQL is deprecated, and will no longer be receiving active support; from now on, all DB development will be in PostgreSQL.
  • All remaining transitional MSSQL support will have ended as of the following EOL dates:
    • 23.06 (Jun 14, 2024)
    • 23.01.x LTS (Sep 22, 2024)

23.01

• Removed unused MySQL and Oracle drivers; users relying on either of these will need to provide their own drivers in their plugins.

22.12

• Requires a reindex immediately after upgrade due to changed handling of identifiers.

22.09

• As of this build, LDAP support is deprecated, and may be removed from the product at a future date. It is recommended that customers still using LDAP to integrate with dotCMS begin migration to a different Single Sign-On (SSO) solution, such as SAML (through Azure or another Identity Provider).

22.08

• By default, dotCMS no longer follows redirects when accessing remote URLs programmatically. This change is configurable, and can be reversed by setting the REMOTE_CALL_ALLOW_REDIRECTS property to true.

22.06

• Initial admin password automatically generated; retrieve from log or use DOT_INITIAL_ADMIN_PASSWORD environment variable.
• Updated several default configuration values, such as disallowing HTTP by default.
• Build scripts have adjusted to use Gradle 7.3.3.

22.05

• OSGi Fragments now update the osgi-extras properties and are not used in the plugins screen.
  

22.03

• Timezone added to all dates — dates using daylight savings might need manual (sql/by hand) adjustment.
• Content now stored as a json field rather than as columns — custom database content queries (which should not be done anyway) are no longer an option.
• All front-end struts paths disabled.
• Calendar screen removed, calendarEvent deprecated.
• Hazelcast removed.
• /api/v2/users incorporated into /api/v1/users. Redirect calls appropriately.

21.07

• Deterministic Ids added to objects.

21.06

• Requires Java 11.
• Last version to support Oracle and MySQL.
  • This tool can simplify the migration from MySQL to PostgreSQL. It is believed to work in most cases, though it has not been tested with significantly old versions of the software. We still recommend, as we do generally, that you make backups before performing any major operation on a database.
• Static plugins no longer supported. Almost all configuration should now be done as environmental variables.
• Non-postgres installs require 3rd party cache transport provider.
• Docker required for any supportable installation.
• All dotCMS cookies marked as Secure, SameSite and HTTPOnly, which can cause issues in some SSO environments.
• Enabled several security headers in Tomcat. Note that X-Frame-Options can be overridden by Content-Security-Policy: frame-ancestors using dotCMS Rules

21.02

• Removes legacy user_proxy table.

5.3

• Elasticsearch is now externalized.
• The clusterId of an environment determines the Elasticsearch indexes to use and should not be shared across clusters.

5.2.4

• Child Relationships are no longer queryable in Elasticsearch. There are convenience methods in both REST and velocity to mirror the old behavior.

5.2

• Front-end and Back-end roles are required for users.
• Elasticsearch mapping changes - default elasticsearch mapping changed from whitespace to custom/standard analyzer. This can be overridden at the field level and queries can be changed to query against the {fieldVar}_dotraw version of a text field. Dates are now mapped as date fields and numeric values are mapped as numberic fields in elasticsearch.

5.0

• Workflow Steps/Actions now required for every content action.
• System Workflow added.
• H2 no longer supported as content datastore.
• Major Elasticsearch version upgrade. _all is no longer queryable.

4.2

• Vanity Urls converted to content.
• Identifiers/paths get lowercased - dotCMS pathing should now be case insensitive.

4.0

• Drops legacy fileasset and htmlpage database tables.

3.1

• Requires Java 8
• Pages converted to content
• Pages no longer need .html or .dot extensions. If you need extension for index pages, you need to explicitly set CMS_INDEX_PAGE=index.html