Server 5

Sophora Server Update Notes

Instructions for updating from the previous Sophora version.

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.
  • 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.AutoloadedDriver instead of the previously used driver org.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

5.0.0Before the update, preferrably months beforeThe 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.0Before the update, preferrably months beforeSupport 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.0Before the update, preferrably months beforeThe SolrCloud connection now requires a Zookeeper url. A direct connection to one of the SolrCloud nodes using has been discontinued. For more information about the connection configuration see the Sophora Server installation guide.
5.3.0Before the updateMake sure your script run with both Groovy 3 and Groovy 4.
5.0.0Before the updateSupport 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.0Before the updateVersions 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:
  • sophora.archive.enabled
  • sophora.archive.activeOnStartup
  • sophora.archive.deleteOldVersionsAfterDays
  • sophora.archive.checkAllDocumentsForOldVersions
  • sophora.archive.preserveNumberOfVersionsInArchiveRepository
  • sophora.deleteDocuments.archive
Additionally, this document property will be ignored by the server:
  • sophora:archiveAfterDays
5.0.0Before the updateSupport for legacy categories has been discontinued. Use enhanced categories (modelled as select values) instead prior to updating to Sophora 5.
5.0.0Before the updateThe Content Manager method getConfigurationDocumentProperties no longer includes values from the Sophora Server's internal configuration file (
This especially covers the properties:
  • sophora.previewBaseUrl
  • sophora.browser.url.password.*
  • sophora.documentManager.generateIdsWithMinusAsSuffix
The method will now only return values from the sophora configuration document, which you can find in the DeskClient's admin view. If you have been using the method before then just make sure that all relevant values are contained in this document instead.
4.20.3Before the updateThe 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.cache.passwordHash.maxSize
  • sophora.cache.structure.maxSize
  • sophora.cache.nodetype.maxSize
  • sophora.cache.proposalsection.maxSize
Caches are no longer restricted in their sizes.
4.15.2Before the updateServer side event scripts had access to the IScriptDocumentManager via the method getDocumentManager(). The IScriptDocumentManager provides access to the saveDocument method which underwent some changes:
  • saveDocument(INode serverNode, String idStem, boolean preserveHistory) is deprecated since 4.15.2 and removed in 5. There are alternatives without the parameter preserveHistory.
  • saveDocument(INode serverNode, String idStem) now returns a UUID instead of String. This method is intended for saving new documents.
  • saveDocument(INode serverNode) is new since 4.15.2 and intended to just save existing documents.
5.0.0Before the update to 5.0.0, after using at least 4.21.0The script now has to be used to start a Sophora Server; it replaces the old start script 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.0Before or during the updateAdditional configurations for the Server plugin content-api have to be part of the Servers
Older versions of the Sophora Server allowed adding configurations for this Server plugin via the file. This is no longer possible. From version 5.0.0 onwards, these properties have to be part of the regular file. If you have been using the specific configuration files, you can just copy their content into the regular file before the update and then remove the 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.0During the UpdateThis 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:
  • repository.xml (in <Versioning> and <Workspace>)
  • workspaces/default/workspace.xml
  • workspaces/live/workspace.xml
5.0.0After the updateThe 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.0After the updateThe 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:
  • sophora-content:teaserImage/sophora:reference
  • sophora-content:slideshow[1]/sophora:reference
  • sophora-extension:imagedata/sophora-extension:binarydata
Xpath expressions like 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.0After the updateStarting 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 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.

Last modified on 1/19/21

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.