dotCMS 5.0 is a major upgrade which includes changes to core dotCMS functionality such as Workflows and core dotCMS components including Elasticsearch. Due to the nature of these changes, it is strongly recommended that you read this entire document before upgrading to dotCMS 5.0 from an earlier version of dotCMS, and perform the steps recommended in this document during your upgrade process to ensure that your site runs correctly after the upgrade.
- Full Cache Flush and Reindex
- Elasticsearch Queries
- Recommended: Browser Cache Flush
- Upgrading from Earlier Releases
Full Cache Flush and Reindex
Due to the change in the Elasticsearch version used by dotCMS in version 5.0, you must perform a full reindex of your dotCMS content after upgrading to dotCMS 5.0, and perform a full reindex of all Site Search indexes. Because the Elasticsearch change affects all indexes, there is no way to reindex only portions of your dotCMS content.
It is also recommended that you perform a full cache flush before performing a reindex, to ensure that all content in the cache is replaced after the index is completed.
Elasticsearch Queries
dotCMS 5.0 includes an upgrade of Elasticsearch from version 1.7.3 to version 6.1.3. This update includes several major changes to Elasticsearch which will prevent some queries that worked in dotCMS 4.x and below versions from working in dotCMS 5.0.
Update Queries Which Contain the _all Keyword
Elasticsearch no longer supports the use of the _all keyword in queries. In order to support existing customers and continue providing the benefits of having a “catch-all” field designator of this type, dotCMS has created a new term catchall which duplicates the functionality of the previous _all keyword.
In order to ensure your Elasticsearch queries perform the same as they did in previous dotCMS versions, you must modify all queries that use the _all keyword, replacing it with catchall.
To find and update your queries:
- Perform the following search using the Query Tool:
- Lucene Query:
+catchall:*_all* - Offset: 0
- Limit: 1000
- Press the SUBMIT button
- Lucene Query:
- Open each content returned from this query.
- In each content, search and replace each instance of “_all” with “catchall”.
Update Wildcard Queries for Numeric and Date/Time Fields
In earlier versions of Elasticsearch, all fields were indexed as strings. In the new version of Elasticsearch, all fields are now indexed as native types (such as integer or date), which both improves performance and enables some additional query methods with full Elasticsearch JSON queries. This includes fields of the following types:
| Field Type | Data Type |
|---|---|
| Text | Decimal |
| Text | Whole Number |
| Date | N/A |
| Date and Time | N/A |
| Time | N/A |
However wildcard queries only work on strings, and this means that these field types can not be accessed using wildcards. For example, the following date query, which worked in dotCMS 4.x and earlier, no longer works in dotCMS 5.0:
+publishDate:[2015* TO 2016*]
To resolve this, you must update any queries which use wildcards to access any of the above types of fields. There are two ways you can rewrite wildcard queries for these field types:
- For the best performance it is recommended that, whenever possible, you rewrite the query to no longer use wildcards.
- If it is not possible or desireable to remove the wildcards from the query, you may retain the behavior of the previous query by using the raw version of the numeric or date/time field in the query.
For example, the above query can be rewritten in either of the following ways:
+publishDate:[20150101 TO 20161231]+publishDate_dotraw:[2015* TO 2016*]
Update All Queries Which Use the yyyyMMdd date format
Elasticsearch 6.1 no longer supports the date format yyyyMMdd without the time included. Therefore all queries which use the old yyyyMMdd date format must be updated to one of the date formats supported by Elasticsearch 6.1. The following date formats are supported:
- Date-only Formats:
MM/dd/yyyy
- Date and Time Formats:
MM/dd/yyyy hh:mm:ssMM/dd/yyyy hh:mm:ss [AM|PM|am|pm]yyyyMMddHHmmss
Note that the simplest way to modify existing yyyyMMdd formatted dates is to add the time to the end of the date. For example the date 20170101 could be modified to 20170101000000. Please recognize that when modifying dates within a date range query (e.g. [20170101 TO 20171231]), the second date in the range should specify the last second of the day instead of the first (e.g. [20170101000000 TO 20171231235959]).
Recommended: Browser Cache Flush
It is generally recommended that, after you upgrade to dotCMS 5.x, your back-end users flush their browser cache. This helps ensure that back-end User Interface elements such as Javascript, Angular components, and images from the older version do not persist and cause unexpected behavior with the new back-end interface.
Upgrading from Earlier Releases
You can upgrade to dotCMS 5.x from releases earlier than dotCMS 4.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 4.x. For information on preparing an earlier release for upgrade to dotCMS 4.x, please see the Upgrading to dotCMS 4.0 documentation.