Upgrading to dotCMS 4.0

Last Updated: May 20, 2021
documentation for the dotCMS Content Management System

Version 4.0 is a major milestone and upgrade for dotCMS, including a number of significant new features and improvements, and preparing dotCMS for even more significant features in the future. Because these changes are significant, however, they may affect your existing dotCMS installation and how you manage it - especially if you've customized portions of dotCMS. This document lists a number of important considerations you should be aware of before you upgrade an earlier version of dotCMS to version 4.0.0.

Changes Affecting Content

Removed Deprecated Features

A number of legacy deprecated features have been completely removed from dotCMS. These features are no longer supported, and the code that implements them has been deleted from the dotCMS 4.0.0 code base.

The following are several specific features to check your installation for before upgrading to dotCMS 4.0.0:

  • The Category Tab Content Type field
    • If you have any Content Types with a Category Tab field, you must remove this field from the Content Type before upgrading to dotCMS 4.0.
  • Old Velocity Macros
  • Old Velocity Viewtools
  • Any customizations or changes to the base dotCMS UI
    • If your dotCMS implementation has any customizations of the old dotCMS UI, these must to be updated to match the new look and feel.
  • Custom Portlets
    • If you have custom portlets deployed in your dotCMS installation, they should still work without modification in the new dotCMS UI.
    • However you may want to update the css and styling in any custom portlets to match the new dotCMS UI.
  • Legacy Files (pre-v1.9)
    • Before upgrading to dotCMS 4.0, you must convert your Legacy Files via WebDAV.
    • Also make sure to check your content for links to legacy files.
  • Legacy HTML Pages
    • Before upgrading to dotCMS 4.0, you must convert your Legacy HTML Pages via the Maintenance screen.

OSGI Felix Version Changed

The OSGI library in dotCMS has been upgraded to use Apache Felix version 5.6.2 and the code in Felix has been “un-repackaged” for easier access. Felix 5.6.2 now supports servlet container spec 3+ which will allow you to natively register filters and servlets programmatically. Because dotCMS 4.0.0 now ships Felix “un-repackaged” you will need to change your java imports in order for your OSGI plugin to compile. For example:

Old Import:

import com.dotcms.repackage.org.osgi.framework.BundleContext;

New Import:

import org.osgi.framework.BundleContext;

New Content Type for “Preview as” Mobile Devices

This new Enterprise functionality works based on a Content Type named “Device” (Content Type variable name: PreviewDevice).

This new Content Type is not automatically-created when you upgrade to dotCMS 4.0 from an earlier version of dotCMS. Therefore:

  • If you are upgrading from an earlier version of dotCMS, you will need to download this Content Type as a bundle (from the dotCMS Demo Site) and upload that bundle into your dotCMS installation.
  • If you have an existing Content Type named “Device” you will still be able to do this (as long as the Content Type variable name is different), but it is recommended that you change the name of your Content Type before uploading the new Devices Content Type.

Once you've added the new Content Type, you can add or remove devices to preview by simply adding or removing the appropriate content of the “Device” Content Type.

CMIS Server Deprecated

dotCMS 4.0 officially deprecates support for CMIS. As an alternative, we suggest using the rich dotCMS RESTful apis.

Changes Affecting Administration

Changes Building from Source

dotCMS 4.0.0 now follows the “gradle standard project layout” for our source code and all build tasks have been migrated to gradle.

If you run from the standard dotCMS distribution, this change should have little to no impact on you. However if you have forked or customized the dotCMS 3.x source codebase, you will need to update your repository to take this change into account before moving to dotCMS 4.0.0.

Bookmarks and Portlet IDs Changed

All the back-end URLs and portlet IDs in dotCMS have changed. If users have system bookmarks, they will need to be updated. If you have custom code that relies on the the legacy URLs or IDs, it will need to be modified (this should be rare).

Note that the URL to login to the dotCMS back-end has also changed, from /admin to /dotAdmin. dotCMS 4.0 will automatically redirect from the old URL to the new URL; however if you have any bookmarks or scripts which use the old URL it is recommended that you change them as soon as possible, as use of the old URL is deprecated and will be removed in a future release.

Elasticsearch Backup/Restore Endpoints Changed

The Index backup and restore has been rebuilt to use the native Elasticsearch index snapshot, replacing the custom developed code used in previous dotCMS releases.

If you rely on the old backup and restore functionality, we suggest that you test your scripts to ensure they still execute correctly.

Authentication Using Websockets

The new dotCMS back-end UI uses websockets to drive two-way interactivity. Unfortunately some firewalls and proxies do not yet support the websocket protocol. However if you are behind a firewall or proxy that does not support websockets, dotCMS will automatically downgrade the connection to a “long polling” connection of 15 seconds, so authentication will still work, but will not have the same authentication and peformance benefits as websockets.

Upgrading from Earlier Releases

You can upgrade to dotCMS 4.3 from releases earlier than dotCMS 3.x. In most cases the upgrade may be performed directly, and dotCMS will upgrade properly. However in some cases you may need to take additional steps to prepare your data for the upgrade; these are the same steps that would be needed to upgrade from the earlier release to dotCMS 3.x. For information on preparing an earlier release for upgrade to dotCMS 3.x, please see the Older Releases documentation.

On this page