Upgrading - Important Changes

Last Updated: Oct 14, 2022
documentation for the dotCMS Content Management System

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. Unfortunatly, 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.


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


  • 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.


  • Deterministic Ids added to objects.


  • Requires Java 11.
  • Last version to support Oracle and MySQL.
  • 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.


  • Removes legacy user_proxy table.


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


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


  • 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.


  • 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.


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


  • Drops legacy fileasset and htmlpage database tables.


  • 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

On this page