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 sourced out and is now a separate module
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.
We encourage you to not see this as part of the update to Sophora 5. It is rather a prerequisit for this update.
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.
PostgreSQL does not support the unicode character U+0000 <Null>. As a consequence, we decided to drop support for this character as well. The Sophora Server will replace all occurrences of U+0000 automatically with the empty string. Based on our observations of larger Sophora repositories, this character realistically only occurs in a few (partly invalid) image metadata properties parsed from IPTC data.
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.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 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.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. |
