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

These changes may or may not be important to your system depending on the details of your implementation; please review them, and contact support if you have any questions. You may also wish to review our Deprecations page.

Details by Version #

25.12.01-01 #

SDK update: The React-library AI search result property has changed:
- DotCMSAISearchResponse.dotCMSResults -> DotCMSAISearchResponse.results

Migration guide:

// Before
const response = await client.ai.search('query', 'index');
response.dotCMSResults.forEach(item => console.log(item));

// After
const response = await client.ai.search('query', 'index');
response.results.forEach(item => console.log(item));

25.07.08-1 #

SDK update: Imports must be updated:
- import @dotcms/client/next -> import @dotcms/client
- import @dotcms/angular/next -> import @dotcms/angular
- import @dotcms/react/next -> import @dotcms/react This establishes a stable foundation for the SDK with proper dependency management, updated documentation, and enhanced dual publishing strategy.

25.06.05-1 #

GraphQL behavior: Block Editor fields are returned as parsed objects instead of JSON strings.
GraphQL behavior: GraphQL now automatically converts _raw fields to objects under their corresponding base keys.

25.06.03-1 #

GraphQL behavior: Aligned GraphQL page query behavior with REST Page API for Vanity URLs, including in cases where the "from" page object does not exist.
Metadata behavior: Fixed modDate — now updates properly after Unpublish or Archive actions.

25.02.12 #

Enabled authentication for servlet requests, allowing users to download files via an authenticated API request. Users can have their resources protected behind authentication, but still access them via an authenticated API request.

24.12.27 #

Corrected Push Publishing behavior: System now correctly respects the push-publishing filter governing relationships — i.e., relationships: false will properly prevent relationship data from being transmitted to, or altered on, the receiver.

24.11.11 #

Endpoint change: Disabled the legacy /DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/uploadBundle endpoint in favor of /api/bundle/sync.
- The old endpoint can be re-enabled via the DOT_ENABLE_OLD_BUNDLE_UPLOAD_ENDPOINT configuration variable.

24.08.27 #

Log behavior change: A new global log4j configuration in Tomcat may cause conflicts with existing custom logging behaviors; in the worst case can cause a server to fail to start. Using the default logging configuration is recommended when upgrading.
API response change: Page API's returned image property now includes the entire image object, rather than just an identifier string.

24.07.19 #

Cookie change: The access_token cookie has been renamed rme, as its only purpose is to establish a "remember me" login flow. rme cannot be used as a Bearer token in the header, and concerns itself exclusively with full login procedures that update the user's "last login" date.

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.

Older Versions #

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