Release Notes | Version 4

Update Notes

Instructions for updating from previous Sophora versions.

Update Guidance

If you want to upgrade to Sophora 4.0 you have to have your servers and components running with 3.x before.
See the list of Sophora versions to see earlier versions with their update instructions.

New System Requirements

Sophora 4.0.0 and later requires Java 11 to run all the Sophora components (Server, Delivery, Importer, ...).

Additional requirements for the DeskClient

  • The DeskClient additionally needs JavaFX 11 to use the integrated Chromium-based JxBrowser. See the DeskClient Installation Guide for further information about Java 11 with JavaFX.
  • The support for 32-bit platforms has been discontinued. The DeskClient only runs on 64-bit platforms and JVMs.
  • The DeskClient can no longer be run on Linux with GTK2. Furthermore the¬†SWT_GTK3¬†environment variable is ignored, as only GTK3 is supported now. Please also note, that GTK versions older than 3.20 are no longer supported.

Spring version update

The Spring version was updated to 5.2 and Spring Boot version was updated to 2.3.

New properties added in sophora-mix:document

The new date properties sophora:editorialDate (intended for the date of the editorial document) and sophora:dwellTimeStart (intended for indicating the start of the document's dwell time) have been added to the mixin sophora-mix:document and thus also to all document node types.

NodeType configurations changed to System Documents

All nodetype configurations have been changed to system documents of type "sophora-nt:nodeTypeDocument". The migration step to convert the old nodetype configurations happens automatically.

Users and Roles changed to System Documents

User and role entities have been changed to system documents of type "sophora-nt:userDocument" and "sophora-nt:roleDocument". Therefore some special features of these entities have been removed or mapped to standard Sophora document features and workflows. Note that changes to user or role documents must be published to take effect.

Exporting User Passwords as Hashes

When exporting users in the DeskClient, the normal document export wizard will appear and there will be no additional checkbox to "Export user passwords as hashes" anymore. To prevent passwords from being exported in a hashed form, you can add the property sophora:password to the "Properties that should not be exported" in the extended settings on the second page of the export wizard or to the document.export.propertiesNotToExportInSophoraXml setting in the configuration document.

Sophora Repo Exporter

The following special export configuration settings of the Sophora Repo Exporter have been removed:

  • fullWithoutPasswords
  • user
  • usersWithPasswords
  • usersWithoutPasswords
  • roles
  • dictionaries
  • proposalSections

You can replace these settings by using the documentTypes criteria or a query (XPath or Solr). To prevent passwords from being exported in a hashed form, you can add the property sophora:password to the propertiesNotToExportInSophoraXml setting in the main configuration or alternatively to the document.export.propertiesNotToExportInSophoraXml setting in the configuration document.

Sophora Server

Archive Worker

Two configuration properties are removed:

  • sophora.archive.maxVersionsToGet
  • sophora.archive.delayMs

The new default value (and minimum value) for sophora.archive.maxVersionsToRetain is '20'. This ensures, that the archive worker can concentrate its work on documents with more than 20 versions.

Caching framework changed

The Sophora server used EHCache for some internal caches. With Sophora 4 Caffeine is used instead. Due to that some of the caching statistics available through jmx look different now.

Sophora Cloud Delivery (Access Tokens for sessionless Sophora Client connections)

In Sophora 3, access tokens are configured using the property sophora.authenticate.tokens in the file. Starting with Sophora 4, access tokens are an extension to a Sophora user. You have to manually assign the access tokens from the file to a Sophora user document. You can do this by opening the user document in the DeskClient's Admin View and add the token to the user.
Note that all access tokens in Sophora 3 are internally mapped to the admin role; however, it is advisable to assign them to less priviliged users in Sophora 4.

Sophora Client and API

Constructor removed from ValidationError

The long time deprecated contructor ValidationError(String) has been removed from the class com.subshell.sophora.api.content.validation.ValidationError. Instead you have to use ValidationError(String, String, ErrorType, ItemPath).

Methods using Strings as UUIDs removed

Throughout the ISophoraClient and several API and Client classes several deprecated methods have been removed, that have been using Strings as UUIDs. In every case there is an alternative method using an UUID object directly.

Deprecated constructor and method from builder for NodeTypeConfigurations removed

The methods withPropertyConfigurations and withChildNodeConfigurations have been removed from NodeTypeBuilder. The same holds for a constructor of NodeTypeConfiguration used by these methods. In the unlikely case you've been using these methods directly, you have to build NodeTypeConfiguration objects using the tab assignments.

Generic type added to INodePage

The class INodePage now has a type parameter which it passes on to the parent interface Page. This is used to make ISophoraDocumentSummaryPage effectively a Page of elements of type ISophoraDocument. You might need to do straight forward adjustments to your code base if you have been using one of theses classes.

Merge-Methods removed for client script dialogs.

The methods merge(ISophoraDocument, INode) and merge(ISophoraDocument, INode, Set<String>, List<String>) have been removed from IClientScriptDialog. Instead you can use the method createMerge().

Find-Methods do not return null

All methods which return UuidSearchResult or NodeSearchResult (e.g. findDocuments or findDocumentUuids) are changed so that they will never return 'null' as a result. In older versions the methods return 'null' if the search result was empty. Now, in all situations an object of type UuidSearchResult or NodeSearchResult will be returned.


Presentation of Documents

Tags from the "sophora:tags" property are no longer displayed by default in the document entries (in search, opened documents view, etc.). If you want them to remain visible, the property must be included in the document information of the nodetype configuration.

Nodetype Registration of Built-In Node Types Removed from Administration View

In older versions some node types had to be registered manually via the administration area when setting up a new repository:

  • Images: sophora-extension-nt:image, sophora-extension-nt:imagedata
  • Copytext: sophora-extension-nt:copytext, sophora-extension-nt:paragraph, sophora-extension-nt:paragraphimage, sophora-extension-nt:paragraphlink
  • File: sophora-extension-nt:binarydata
  • Components: sophora-extension-nt:group
This manual registration is no longer necessary because the server delivers the node types by default.

Important Notes for DeskClient 4.4.0 and newer

  • For updates via update site, an installed DeskClient version 3.7.0 (or newer) or 4.3.0 (or newer) is required so that the automatic restart after the update works without errors.

DeskClient Plug-ins

Removed dependencies

Some dependencies that were provided by com.subshell.sophora.eclipse.libs and org.eclipse.core.runtime are no longer provided for all bundles. If you use one of the following dependencies inside your own plugin, you need to declare the dependency directly in your MANIFEST.MF file now.

  • commons-io
  • javax.inject
  • jaxen
  • joda-time

We recommend to use the Import-Package directive to import only used packages.

Removed API

The method IFormElement.getReferencedDocuments() was removed. The references in string properties are now collected and set to the documents' sophora:referencedDocuments property by the server during the save operation. The benefit is that a document will always have the references updated when saved. Before only the DeskClient filled in all references. The importer or scripts had to update the property sophora:referencedDocuments on their own. In Sophora 4 the method still exists in the abstract classes of the form field elements. So if you have overwritten this method you don't need to update your code immediately. This stub will be removed with the next major release Sophora 5.

The editor with the ID com.subshell.sophora.eclipse.editor.BrowserEditor was removed. Instead the e4 part com.subshell.sophora.eclipse.editor.BrowserPart can be used.

Removed deprecated API

The deprecated attributes "childNodeType" and "alwaysShowOnNodetype" of extension point "com.subshell.sophora.eclipse.editorComponents" have been removed.

Changes for Editor Tabs

If your input field provides an editor tab (implementing IEditorComponent.getEditorTabs()) you have to adapt your code for the following API changes:

  • The interface provided by IEditorComponentTabProvider.createEditorPart() was renamed from IExtendedEditorPart to ISophoraEditorPart.
  • You can no longer extend the Eclipse class EditorPart, extend AbstractSophoraEditorPart instead. We suggest to extend AbstractLoadingPart for additionally creating the controls lazy.
  • The first parameter for the init() method has changed from IEditorSite to ISophoraEditorSite.
  • The method getPartControl() was removed and instead the method createPartControl() must return the created control.
  • For property changes to PROP_DIRTY it must be referenced qualified as IEditorPart.PROP_DIRTY.
  • The methods isSaveAsAllowed() and doSaveAs() were removed.
  • ISophoraEditorPart.getReferencedDocuments() has been removed. AbstractSophoraEditorPart.getReferencedDocuments() is deprectated and will be removed in Sophora 5.

Changes for Input Fields

  • The method AbstractFormField.labelLinkActivated() is now deprecated. Use the new method getLabelLinkAction() of the IFormField2 interface instead. The associated attribute labelAsLink of the extension point com.subshell.sophora.eclipse.formInputFields (defined in the custom plugin.xml file) is also deprecated and can be removed. Both the method and the attribute will be removed in Sophora 5.
  • The method IFormElement.getReferencedDocuments() was removed. AbstractFormField.getReferencedDocuments() is deprectated and will be removed in Sophora 5.

Sophora Delivery

Changed behaviour when accessing structure nodes without index documents

With Delivery versions 2.5.41, 3.0.2, 4.0 and newer we changed the behaviour when requesting URLs pointing at index documents of structure nodes.

The new behaviour results in the regular handling of missing documents for this structure node.

If you don't want this then you can keep the former behaviour by adding this line to your webapp's


UGC Executable

With Sophora release 4 the ugc-webapp has been simplified to ugc. Therefore the executable jar has been renamed to ugc.jar. As a consequence the *.conf file that contains the VMARGS must also be renamed to ugc.conf.

Removed deprecated node function

With Sophora 4 the node function getReport(INode) from VotingReport has been removed. Use getRankingReport(INode) or getSimpleReport(INode) instead.

Sophora Importer

Changed configuration file format

With Sophora 4, we have renovated the Sophora Importer. It is now based on Spring Boot, which we use for all our tools developed in recent years. With this release, the configuration format of the Importer changes and you will need to migrate your configuration files. The installation of the Importer is different as well. The migration guide explains the steps needed to update your installation.

Removed deprecated methods from IPreProcessing

The deprecated method execute(InputStream input, OutputStream output, IErrorTracker errorTracker) has been removed with Release 4.0. Subclasses of IPreProcessing or AbstractPreProcessing now must implement execute(InputStream input, OutputStream output, IErrorTracker errorTracker, Map<String, String> params). This method has yet been existing prior to 4.0 so you can adjust your custom pre-processors ahead of upgrading Sophora.

Changed API

We changed the signature of the following methods/constructors:

  • com.subshell.sophora.importer.core.creators.ChildNodeSetzer#ChildNodeSetzer
  • com.subshell.sophora.importer.core.creators.DocumentCreator#createDocument
  • com.subshell.sophora.importer.core.creators.ImportPerRmi#doImport
  • com.subshell.sophora.importer.core.creators.ResourceListDocumentsCreator#ResourceListDocumentsCreator
  • com.subshell.sophora.importer.core.instructions.AbstractInstructionHandler#AbstractInstructionHandler
  • com.subshell.sophora.importer.core.instructions.InstructionProcessor#processInstructions
  • com.subshell.sophora.importer.core.instructions.ProposalsCreator#ProposalsCreator
  • com.subshell.sophora.importer.core.instructions.StickyNotesHandler#StickyNotesHandler
  • com.subshell.sophora.importer.core.instructions.lifecycle.LifecycleManager#LifecycleManager
  • com.subshell.sophora.importer.core.job.ImportJob#ImportJob
  • com.subshell.sophora.importer.feeds.model.FeedItemImporter#processXml
  • com.subshell.sophora.importer.job.FileImportJob#FileImportJob

Extended time logging

In order to get a more detailed time logging of each step during the import process the following constructors/methods now need an additional parameter.


If you are using any of the above contructors or methods you have to create a new ImporterStopwatch and use it as the parameter value. Example:

ImporterStopwatch importerStopwatch = new ImporterStopwatch(;

Social Media Connector

The deprecated configuration options sophoraUsername, sophoraPassword and sophoraHost have been removed. Instead use the configuration block sophoraServer with its properties host, username and password.

Sophora Hyphenator

The deprecated method hyphenate(List<String>, int, List<ManualHyphenation>) has been removed from the hyphenator. If you use it manually (e.g. in scripts) you have to use hyphenate(TextDocument, int) instead. Furthermore substituteCharacters(List<String>, List<ManualHyphenation>, Map<String, String>) has been removed. Instead the similar method from TextDocument should be used.

Teletext 2.0

Please reimport the script ReplaceTeletextChars due to a change in the Sophora API.


Since importer version 4.1.2 the configuration property sophora.client.server-connection.url is deprecated and should be replaced with sophora.client.server-connection.urls, where multiple connection urls may be used. In importer 5 sophora.client.server-connection.url is removed.


The configuration property akamaiUrlPrefixes has been deprecated with version 4.1.0 of the AV-Tool/YouTube-Connector. It will be removed with version 5.0.0. Please use akamaiUrlPatterns instead.

Last modified on 12/16/20

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