Release Notes | Version 4

Sophora 4 Update Notes

Instructions for updating from the previous Sophora version.

General Sophora 4 Update Notes

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 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.

With server 4.4.0 the new property sophora:firstPublicationDate (intended for the date of the first publication of new documents) has been added to sophora-mix:publishable and thus, due to inheritance, also to sophora-mix:document.

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 adminExport (full, fullWithSeparatedNodeTypes or allSystemDocuments) or the documentTypes criteria or a query (XPath or Solr; documents must be searchable). 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 Client API: Update Notes

4.0.0After the update to Sophora Client 4.0.0.The long time deprecated constructor 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).
4.0.0After the update to Sophora Client 4.0.0.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.
4.0.0After the update to Sophora Client 4.0.0.The deprecated 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.
4.0.0After the update to Sophora Client 4.0.0.The class INodePage now has a generic 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.
4.0.0After the update to Sophora Client 4.0.0.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().
4.0.0After the update to Sophora Client 4.0.0.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.
4.0.0Can be adjusted before updating to a newer major version.The class com.subshell.sophora.commons.locking.StringKeyLockManager is no longer recommended and will be removed in Sophora 5.0.0. Please use com.subshell.sophora.commons.locking.ReentrantLockProvider instead.

Sophora Delivery: Update Notes

URL decoding

2.5.41, 3.0.2, 4.0.0After updating to Sophora Delivery 4.0.0, 3.0.2, 2.5.41We 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

HTML encoding

3.0.24, 4.0.11After updating to Sophora Delivery 3.0.24, 4.0.11Link URLs in <a>-tags generated from link documents (textlinks) are now XML-encoded. (e.g. '&' instead of '&'). If you have encoded them by yourself so far, you should not anymore because this will break your textlink destination because URLs would be encoded twice.

Sophora DeskClient: Update Notes

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 Hyphenator: Update Notes

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

Sophora Importer: Update Notes

Configuration Changes

4.0.0After the update to Importer 4.0.0With 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.
4.1.2After the update to Importer 4.1.2Since 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.

API Changes

4.0.0Before the update to Importer 4.0.0The deprecated method execute(InputStream input, OutputStream output, IErrorTracker errorTracker) has been removed with Release 4. 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.0 so you can adjust your custom pre-processors ahead of upgrading Sophora.
4.0.0After the update to Importer 4.0.0In order to get a more detailed time logging of each step during the import process the following constructors/methods now need an additional parameter:
  • 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
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(;

Sophora Metadata Supplier: Update Notes

4.0.0After the update to Sophora Metadata Supplier 4A new version of the Mapper Plugin adapted to Metadata Supplier Version 4 must be installed.
4.0.0After the update to Sophora Metadata Supplier 4The configuration of the server connection in the application.yml must be changed from
# Sophora connection settings
      url: '<your server url>'
      username: '<your username>'
      password: '<your password>'

# Sophora connection settings
        - '<your server url>'
      username: '<your username>'
      password: '<your password>'

Sophora Server: Update Notes

URL Handling

4.7.0Configuration can be adjusted before updating to version 4.7.0Starting with version 4.7.0, the Sophora Server has a new default implementation for composing and parsing URLs, which uses the URL components of the Sophora webapp-framework instead of requesting the deliveries.The new implementation can handle both Sophora document URLs and URLs for the Sophora Image Service. It also avoids HTTP calls to the deliveries and thus it's much faster.

If you want to keep the old behavior and use the URL handling from the deliveries, you can set the property sophora.url.use-url-library=false in the server configuration file.

Otherwise you should adjust the relevant properties for the URL generation to match your setup.
For more information about the properties, see the description in the documentation of the Sophora server configuration.

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.


Virtual Properties

Field names for virtual properties indexed in the internal Solr contain slashes which makes them unusable with the fl-parameter. Solr Cloud uses underscores instead of slashes which fixes that problem.

"sophora-nt_stickyNote/sophora_comment_s": "comment" (virtual property in internal Solr)
"sophora-nt_stickyNote_sophora_comment_s": "comment" (virtual property in Solr Cloud)

Sophora Social Media Connector: Update Notes

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 Teletext: Update Notes

4.2.0This must be done before the Teletext Generator is started for the first time in version 4.2.0.The configuration for the Sophora Client has changed, we are now using the configuration of the library Spring Boot Sophora Commons. Therefore your configuration of the Sophora Server connection must be adapted.

The prefix teletext.sophoraServer has to be changed to sophora.client.server-connection. We can now configure more than one server, so the previous property host now has the name urls and takes a list of URLs. Below you will find a brief summary about the actual configuration changes in YAML format.

If you want to read more about all available configuration properties, have a look at the corresponding documentation for Spring Boot Sophora Commons.

Format before:
    host: "http://<server>:<port>"
    username: "<user>"
    password: "<pwd>"

Format after:
      urls: ["http://<server>:<port>"]
      username: "<user>"
      password: "<pwd>"

The names of some optional properties have also changed. If you have configured some of these properties, you have to replace the old by the new names, otherwise these properties have no effect.


This must be done before updating the SFTP server or the Teletext GeneratorWith this version of the Teletext Generator, the outdated ssh-rsa will not be supported anymore by default. You will either need to update your server (SFTP target) to support ssh-rsa2 or add the following Java options to your .conf file to re-enable ssh-rsa:
"-Djsch.server_host_key=...,ssh-rsa -Djsch.client_pubkey=...,ssh-rsa"
4.1.0After the update to Teletext 4.1.0The teletext generator requires no special Solr cores to be present and uses internal cores default and default-live existing in Sophora configuration by default.
The Solr core Teletext_Live is not used anymore.
4.2.0The technical documentation is moved to the Website

Sophora UGC: Update Notes

UGC Service

4.0.0This must be done when UGC is started for the first time in version 4.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.
4.1.0After the update to UGC 4.1.0 and only if you use a reverse proxy for your UGCWhen running the UGC webapp with a reverse proxy (i.e. for the editorial ui), you must now explicitly define an allowed origin to the websocket which is used to check for new content. Please use websocket.allowedOrigin to set an allowed origin.
4.2.2After the update to UGC 4.2.2 and only if you use a reverse proxy for your UGCThe path of the websocket to check for new comments and images changed from /websocket/ to /websocket/commentsAndImages
Consult the Reverse proxy documentation page for details on configuring a reverse proxy.
4.3.0After the update to UGC 4.3.0UGC now supports the OpenAPI 3.0 Specification. The OpenAPI Specification endpoint has changed from /v2/api-docs to /v3/api-docs.
The Swagger UI endpoint has changed from /api-ui/index.html to /swagger-ui.html.
4.0.2After the update to UGC 4.0.2The configuration property group double-opt-in.transport has been deprecated with version 4.0.2 of UGC. It will be removed with version 5.0.0. Please use email.transport instead. Consult the UGC Webapp documentation page for details on the configuration.

UGC Taglib

4.0.0After the update to UGC taglib 4.0.0With Sophora 4 the prior deprecated node function VotingReport.getReport(INode) has been removed. Use VotingReport.getRankingReport(INode) to get the same report or consider the method VotingReport.getSimpleReport(INode) if a simplier report may satisfy your requirements. The methods have been existing prior to Sophora 4 so that adjustments can be done before the update.

Web App Framework: Update Notes

4.1.0After the update to 4.1.0Following interfaces moved to other packages:
com.subshell.sophora.webapp.routing.configuration.IRoutingModelMapProvider -> com.subshell.sophora.webapp.routing.model.IRoutingModelMapProvider
com.subshell.sophora.webapp.routing.configuration.IResponseHeaderProvider -> com.subshell.sophora.webapp.routing.response.IResponseHeaderProvider

With the new version, you will also have to put your static resources into the default Spring Boot resources folders. These are:
  • META-INF/resources/
  • resources/
  • static/
  • public/

Sophora YouTube-Connector (AV-Tool) Update Notes

Configuration Changes

4.1.0After the update to AV-Tool 4.1.0The 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.
4.6.0This must be done before updating the SFTP server or the YouTube ConnectorWith this version of the YouTube Connector, the outdated ssh-rsa will not be supported anymore by default. You will either need to update your server (SFTP target) to support ssh-rsa2 or add the following Java options to your .conf file to re-enable ssh-rsa:
"-Djsch.server_host_key=...,ssh-rsa -Djsch.client_pubkey=...,ssh-rsa"

Sophora Mobile Client: Update Notes

4.5.0This must be done before the Sophora Mobile Client is started for the first time in version 4.5.0.The configuration of the server connection in the application.yml must be changed from

  username: webclient
  password: thisIsSecret
  httpPort: 1196
  httpsPort: 1195


      urls: [""]
      username: "webclient"
      password: "secret"

Last modified on 11/15/22

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