General Update Order
This update should be performed like other major Sophora updates. This implies this order:
First all Staging Servers and all Replica Servers must be updated. There are no dependencies between Replicas and Staging Servers. Thus, those can be updated in any order.
Then the Sophora Primary has to be updated. You can also switch the primary and then immediatly afterwards stop und update the former primary. Just ensure that the primary never runs in a more recent version then your Replica.
When all Sophora Servers are update you can start updating all applications based on the Sophora Client like the Sophora DeskClient or Importers.
Minimum Sophora Version prior to Upgrade
For compatibility reasons all of your Sophora Servers must be running with at least version 4.26.0 prior to the upgrade to 5.
Major Changes in Version 5
Sophora Server version 5 comes with the following changes:
- SolrCloud and the Sophora Indexing Service replace the internal Solr engine and indexing.
- Introduction of the Version Store
- The module ACS has been removed.
- The plugin Linkchecker has been moved to a separate module.
- The Content API has been moved to a separate module. Until Sophora Server version 6 it is still available as a Sophora Server-internal variant.
- Since version 5.3.0, Sophora Server uses Spring 6 and Groovy 4.
Removal of the embedded Solr
Until server version 4, the Sophora Server came with an integrated Solr engine. This has been removed completely in Sophora 5. The Sophora Server itself does not require Solr. Queries from Sophora Clients are mapped to Solr however and require the external SolrCloud. Support for SolrCloud was introduced in Sophora 4 alongside the Sophora Indexing Service. You must have migrated to SolrCloud and the Sophora Indexing Service prior to the upgrade. See indexing service migration guide for more details.
Introduction of the Version Store
Sophora Server 5 does no longer contain the Archive Repository. It was used to store access versions of documents. All those versions plus the versions from the main repository are now placed in the new Version Store which is based on PostgreSQL. To see what the Version Store does, refer to the Version Store Guide.
The Sophora Server does not automatically migrate all the versions. For migrating all your document versions into the new Version Store, refer to its migration guide.
Spring 6, Groovy 4 and Jetty 12 (since 5.3.0)
Starting with version 5.3.0, Sophora Server uses the Spring framework in version 6.1. (Prior versions use Spring framework 5.3.) This update brings a few notable changes:
- Derby uses the updated driver
org.apache.derby.iapi.jdbc.AutoloadedDriverinstead of the previously used driverorg.apache.derby.jdbc.EmbeddedDriver. Refer to the breaking changes table for more details. - The Groovy scripting engine is updated from version 3.0 to version 4.0. We strongly advice to have a look at the release notes for Groovy 4 and check your scripts.
- We updated Jetty 10 to Jetty 12.
Deprecation of JCR XPath
JCR XPath queries have been deprecated in Sophora 5 and will be removed in Sophora 6. Use IQuery-based queries instead.
Sophora 5 instroduces SoQL ("Sophora Query Language") as a replacement for XPath where text-based query definitions are required. Starting with Sophora Server 5.2.0, SoQL can be used to define Query Select Values. An updater (SoQLInsteadOfXpathForQuerySelectValuesUpdater) will migrate typical XPath-based Query Select Values to SoQL automatically upon the first startup of a Sophora Server >= 5.2.0. However, more complex XPath queries cannot be migrated automatically. You will see warnings in your log on every Sophora Server startup that remind you to migrate those manually.
List of breaking changes
| Version | Timing | Changes |
|---|---|---|
| 5.0.0 | Before the update, preferrably months before | The Server does no longer come with an internal Solr. You must have migrated to Solr Cloud and the Sophora Indexing Service prior to the upgrade. See indexing service migration guide for more details. |
| 5.0.0 | Before the update, preferrably months before | Support for LevelDB as Jackrabbit repository has been discontinued. LevelDB used to be an alternative repository technology for Staging Servers but it cannot be used Sophora 5 any more. Sophora 4 repositories stored in a LevelDB cannot be started using a Sophora 5 Server. If you were using LevelDB with any of your Sophora Servers then you have to migrate those before the update. In this case we recommend to setup an empty staging server and synchronize it from scratch. On larger repositories this might take a few days. But afterwards this newly synchronized server can be used as copy-paste prototype for all the other Sophora Staging Server. |
| 5.0.0 | Before the update, preferrably months before | The SolrCloud connection now requires a Zookeeper url. A direct connection to one of the SolrCloud nodes using sophora.solr.cloud.url has been discontinued. For more information about the connection configuration see the Sophora Server installation guide. |
| 5.3.0 | Before the update | Make sure your script run with both Groovy 3 and Groovy 4. |
| 5.0.0 | Before the update | Support for database binary store has been discontinued. A separate binary store is mandatory in Sophora Server 5. The option to use the database binary store no longer is available. So you either have to use the default file system binary store or the cloud binary store. If you have been using the database binary store or no binary store whatsoever before then you have to migrate your binary data into one of the other options. The easiest way to do this is through a full sync into a newly set up server configured to use a file system binary store (which is the default). The update to 5 requires a full-sync anyway to migrate document versions to the new version store, so you can do this in one go. |
| 5.0.0 | Before the update | Versions have to be migrated into the new VersionStore, see the migration guide for more details. These configuration options are no longer needed after the update:
|
| 5.0.0 | Before the update | Support for legacy categories has been discontinued. Use enhanced categories (modelled as select values) instead prior to updating to Sophora 5. |
| 5.0.0 | Before the update | The Content Manager method getConfigurationDocumentProperties no longer includes values from the Sophora Server's internal configuration file (sophora.properties).This especially covers the properties:
|
| 4.20.3 | Before the update | The following configuration options are no longer needed since 4.20.3 and 5.0.0 and can be removed from the Sophora Server's sophora.properties
|
| 4.15.2 | Before the update | Server side event scripts had access to the IScriptDocumentManager via the method getDocumentManager(). The IScriptDocumentManager provides access to the saveDocument method which underwent some changes:
|
| 5.0.0 | Before the update | Unlike in version 4, the IScriptingDocumentManager, which is used in document change scripts (IScriptDocumentChangeListener), now respects document permissions. Therefore, before the update, it must be ensured that all users have the necessary permissions for the documents accessed in these scripts. |
| 5.0.0 | Before the update to 5.0.0, after using at least 4.21.0 | The script sophoraServerControl.sh now has to be used to start a Sophora Server; it replaces the old start script sophora.sh. The new script is already available since 4.21.0. See Using the Sophora Server for further information on how to use the new start script. This does not apply to you, if you use our Docker image or Helm chart. |
| 5.0.0 | Before or during the update | Additional configurations for the Server plugin content-api have to be part of the Servers sophora.properties Older versions of the Sophora Server allowed adding configurations for this Server plugin via the content-api.properties file. This is no longer possible. From version 5.0.0 onwards, these properties have to be part of the regular sophora.properties file. If you have been using the specific configuration files, you can just copy their content into the regular sophora.properties file before the update and then remove the content-api.properties afterwards. Alternatively you can do all this in one go before launching the Sophora Server in version 5.0.0 (or greater) for the first time. |
| 5.3.0 | During the Update | This change only applies if you use Derby as your database: The Derby driver changed to org.apache.derby.iapi.jdbc.AutoloadedDriver, previously org.apache.derby.jdbc.EmbeddedDriver. Change the driver of all persistence managers in the following files:
|
| 5.0.0 | After the update | The IDs of document versions have changed. They are now generated with a determistic pattern to be equal on all cluster servers. This is unlikely to be relevant. However, as the version IDs have been different between different servers prior to version 5.0.0 and therefore were unreliable. |
| 5.0.0 | After the update | The format for describing document thumbnails has changed. Every nodetype configuration comes with the property "Thumbnail" on the "attributes" tab. This used to contain some pseudo XPath-Pattern which is no longer supported. Instead, it now uses an item path syntax: The new syntax supports accessing child nodes (with or without an index) and properties. The nodes and properties are separated by forward slashes, similar to URL paths. The item path follows this structure: [<child-node>/.../]<property> with zero or more child nodes at the begining and ending in a property. No prefix is required. Here are a few examples of the new item path syntax for thumbnails:
order by jcr:score at the end should be removed. Invalid item paths will cause empty thumbnails.The thumbnail path is resolved recursively. A chain like "Document A -> Document B -> Image Document" is possible. The last element in the chain should always point to an actual image document. Most real world examples of Thumbnail configurations are valid in the former XPath syntax and the new item path syntax and therefore don't have to be adjusted, but you should check this for every node type with thumbnails. |
| 5.0.0 | After the update | Starting with Sophora 5, the Server IDs are generated using a combination of a Server's hostname, http and https port, making it more robust against failure. The previously used server.properties file, which persisted the randomly generated Server ID, is automatically deleted during the first start of Sophora 5. This means that the IDs of every server will change during the update to Sophora 5. This should not have critical consequences, but will likely result in new time series data in the Sophora Dashboard. All this happens automatically. |
