Changelog

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.

Updates of embedded Libraries

Scripting with Groovy 3.0

Sophora 4 now uses Groovy 3.0 as scripting engine. As there are some major changes, e.g. to the Groovy parser, we advise to check your scripts on a non-production system before upgrading your production system. Note that scripts are used by several Sophora components (e.g., Server, DeskClient, Importer, and customer-specific tools). See the Release Notes for Groovy 3 for further details on potential incompatibilities and workarounds. We recommend the Upgrading Guide by Collibra.

Sophora 4 initially used Groovy 2.5. Check the Release Notes page and the update notes sections below for details on Sophora components compatible with Groovy 3.0.

Update to Spring Boot 2.7

Spring Boot based Sophora applications, such as the Sophora Importer and Sophora Teletext, have upgraded to Spring Boot 2.7.

Spring Boot 2.4 has changed the priority with that application.yml configuration files are processed. No changes are necessary if you use on-premise installations or Docker images provided by subshell. Action might be required if you use project-specific Docker images with multiple application.yml files. Have a look at the Spring Boot Config Data Migration Guide for details.

The Spring Boot dependency is important in particular, since we use the Dependency Management of Spring Boot. Please refer the Spring Documentation for further information about that topic.

Sophora 4 initially used Spring Boot 2.3. Check the Release Notes page and the update notes sections below for details on Sophora components compatible with Spring Boot 2.7.

Update to Spring Framework 5.3

Sophora applications now use Spring Framework 5.3. If your applications use the Sophora Client or other Sophora libraries, you should update to Spring 5.3 as well. Have a look at the Upgrade Notes of the Spring Framework.

Sophora 4 initially used Spring 5.2. Check the Release Notes page and the update notes sections below for details on specific Sophora components compatible with Spring 5.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.

XPath is now deprecated

The underlying storage technology of Sophora, Jackrabbit/JCR, will be replaced in Sophora 6. Therefore, the XPath query language will no longer be available in Sophora 6. Prior to that release, we will provide alternatives to XPath-based features, and there will be detailed guides how to migrate to those alternatives. We strongly advise not to use XPath any more where alternatives already exists. For instance, when searching for documents, use IQuerys or Solr instead.

Sophora Client API: Update Notes

VersionTimingChanges
4.30.0After the update to Sophora Client 4.30.0In com.subshell.sophora.api.structure.StructureNode the methods getDefaultDocumentUUID(), getHierarchyDocumentUUID() and getStructureNodeDocumentUUID() are changed so that they will return null instead of throwing a RuntimeException. That happens if the Reference of the concerning document or structureNode is null or an external Reference is set.
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.
VersionTimingChanges
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.
VersionTimingChanges
4.27.0After the update to Sophora Client 4.27.0.The dependencies of the Sophora Client were updated. The Sophora Client now requires only the dependency org.springframework:spring-jcl for Java-Commons-Logging, the two dependencies commons-logging:commons-logging and org.slf4j:jcl-over-slf4j have been removed.
Aditionally the name for another dependency was changed, now the dependency jakarta.validation:jakarta.validation-api is used, before the Sophora Client used the dependency named javax.validation:javax.validation-api.
4.17.0After the update to Sophora Client 4.17.0.The dependencies of the Sophora Client were updated. Crucial updates include Spring Boot in version 2.7.5 and Spring in version 5.3.23. Another important update is the use of Groovy in version 3. Refer to the General Sophora 4 Update Notes above for further details.

Sophora Delivery: Update Notes

URL decoding

VersionTimingChanges
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 sophora.properties:
sophora.delivery.legacyMissingIndexDocumentHandling=true

HTML encoding

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

Categories

VersionTimingChanges
4.4.0After updating to Sophora Delivery 4.4.0The following classes have been deprecated and will be removed in Sophora Delivery 5.0.0:
  • com.subshell.sophora.delivery.taglib.GetCategoryTag
  • com.subshell.sophora.delivery.taglib.GetCategoryObjectTag

The following methods have been deprecated and will be removed in Sophora Delivery 5.0.0:
  • com.subshell.sophora.delivery.api.IContentProvider#getCategory(String)
  • com.subshell.sophora.delivery.api.IContentProvider#getCategory(UUID)

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

VersionTimingChanges
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

VersionTimingChanges
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.7.0After the update to Importer 4.7.0Since importer version 4.7.0 the new module com.subshell.sophora.importer.schema is implemented. The artifact containing the Sophora-XML schemas are now found in the new module and not at com.subshell.sophora.importer.core anymore.
4.8.0Before the update to Importer 4.8.0Groovy Version is updated from 3.0.17 to 3.0.19. Please check your transformation scripts if they are compatible with the new Groovy version.
E.g. the behavior of methods Tuple2.of() is changed.
4.10.0After the update to Importer 4.10.0Feed items with a future date will be ignored while polling.
If a Sophora feed document (sophora-extension-nt:feed) defines an XPath for the date of items (sophora-extension:dateXpath), items will be ignored, if their date is in the future.
VersionTimingChanges
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.
4.4.0After the update to Importer 4.4.0 and before updating to 6.0.0Since importer version 4.4.0 there are two new modules to build and represent Sophora-XML. One of them is the model, which now contains some classes that resided in the Importer core before.
To use the new artifact use the artifactId com.subshell.sophora.importer.model in the groupId com.subshell.sophora

These Classes will be removed in 6.0.0!
  • com.subshell.sophora.importer.core.creators.ProtectionInstruction replaced by com.subshell.sophora.importer.model.documents.ProtectionInstruction
  • com.subshell.sophora.importer.core.instructions.lifecycle.LifecycleActivityType replaced by com.subshell.sophora.importer.model.documents.instructions.LifecycleActivity.Type
com.subshell.sophora.importer.core.updating.BehaviourType replaced by com.subshell.sophora.importer.model.documents.ChildNodeUpdateBehaviour.Behaviour
  • com.subshell.sophora.importer.core.updating.MergeInsertPosition replaced by com.subshell.sophora.importer.model.documents.ChildNodeUpdateBehaviour.MergeInsertPosition
4.8.0After the update to Importer 4.8.0 and before updating to 5.0.0Since importer version 4.8.0, the Method IErrorTracker#writeToFile(File file) is deprecated and should be replaced with an own implementation of writing the errorfile, using the new methods
IErrorTracker#getFilename()
IErrorTracker#getErrorFileContent()
IErrorTracker#shouldWriteFile()
to retrieve the filename, content and whether or not an errorfile is necessary. In Importer 5, IErrorTracker#writeToFile(File file) will be removed.

API Changes

VersionTimingChanges
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
  • com.subshell.sophora.importer.ws.impl.ImportService#importXml
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(Instant.now());
importer.doImport(importerStopwatch);
importerStopwatch.close();
LOG.info(importerStopwatch.toString());
4.7.0After the update to Importer 4.7.0 and before updating to 5.0.0These Classes are deprecated since 4.7.0 and will be removed in 5.0.0!
  • com.subshell.sophora.importer.core.creators.CategoryCreator
  • com.subshell.sophora.importer.core.creators.CategoryPath
4.7.0The Kotlin DSL to build documents has changed slightly. com.subshell.sophora.importer.model.documents.dsl.ResourcesBuilder.document() has been renamed to resource().
This affects the resources { } block. DSL usages have to be changed from
buildDocument { resources { document { /* ... */ } } }

to

buildDocument { resources { resource { /* ... */ } } }

This has been changed to reduce confusion when using the DSL.

Sophora Metadata Supplier: Update Notes

VersionTimingChanges
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
sophora:
  client:
    server-connection:
      url: '<your server url>'
      username: '<your username>'
      password: '<your password>'
to
# Sophora connection settings
sophora:
  client:
    server-connection:
      urls:
        - '<your server url>'
      username: '<your username>'
      password: '<your password>'

Sophora Repo Exporter: Update Notes

VersionTimingChanges
4.0.6When updating to 4.0.6+A referenced document (according to configured maxRecursionDepth) will be exported if the recursionCriteria matches or, additionally, if no recursion criterion is configured in the corresponding "documents" block. "documents[].maxRecursionDepth" is now also applied in daemonMode.

Sophora Server: Update Notes

URL Handling

VersionTimingChanges
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.
4.18.0Configuration can be adjusted before updating to version 4.18.0The configuration for the image URL component from the Sophora webapp-framework has changed in version 4.18.0
  • Structure node documents have a new property imageUrl, which will be used as prefix for image URLs generated by the URL component
  • The value of the new property sophora.url.image-service-default-domain will be used as default, when the imageUrl in the site of the image is not configured
The old configuration property sophora.url.image-service-domain is obsolete and should be removed after updating the Sophora Server to version 4.18.0
For more information about the properties, see the description in the documentation of the Sophora server configuration.

New script to the sophora server

VersionChange
4.16.3Next to the script sophora.sh another script named sophoraServerControl.sh can now be used to start the Sophora Server, sophoraServerControl.sh will replace the script sophora.sh in Sophora 5. See Using the Sophora Server for further information on how to use sophoraServerControl.sh and sophora.sh.

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 sophora.properties file. Starting with Sophora 4, access tokens are an extension to a Sophora user. You have to manually assign the access tokens from the sophora.properties 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.

Solr

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)

Spring Data Sophora: Update Notes

VersionTimingChanges
4.6.0This must be done before the Spring Data Sophora is updated to the version 4.6.0 in your application if
  • the application has custom SDS Repositories (SophoraDocumentRepository), and
  • any of the repositories extends another custom repository, and
  • the super repository has @RepositoryOptions, and
  • the extending repository doesn't has its own @RepositoryOptions
Spring Data Sophora Repositories extending other repositories inherit their settings defining in the annotations @RepositoryOptions.

If this is not desired please overwrite the inherited settings by setting the empty @RepositoryOptions at the extending repository.
VersionTimingChanges
4.8.0After the update to Spring Data Sophora 4.8.0.The dependencies of Spring Data Sophora were updated. Spring Data Sophora now requires only the dependency org.springframework:spring-jcl for Java-Commons-Logging, the two dependencies commons-logging:commons-logging and org.slf4j:jcl-over-slf4j have been removed.
Aditionally the name for some other dependencies were updated to match with the dependencies of Spring Boot and Hibernate Validator:
  • javax.validation:javax.validation-api → jakarta.validation:jakarta.validation-api
  • javax.annotation:javax.annotation-api → jakarta.annotation:jakarta.annotation-api
  • org.glassfish:jakarta.el → org.apache.tomcat.embed:tomcat-embed-el

Sophora Teletext: Update Notes

VersionTimingChanges
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:
teletext:
  sophoraServer:
    host: "http://<server>:<port>"
    username: "<user>"
    password: "<pwd>"

Format after:
sophora:
  client:
    server-connection:
      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.

Before:
teletext.sophoraServer.connectRetries
teletext.sophoraServer.connectRetryInterval
teletext.sophoraServer.documentCacheSize
teletext.sophoraServer.readAnywhere

After:
sophora.client.server-connection.retries
sophora.client.server-connection.retry-interval
sophora.client.cache.document-cache-elements-in-memory
sophora.client.misc.use-read-anywhere
This must be done before updating the SFTP server or the Teletext Generator.With 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.4.0This must be done if you have custom Teletext scripts that reference the Teletext add-on scripts and when updating the Teletext Scripts (dependency) to version 4.4.0.All scripts that are provided via the Teletext add-on have been moved to a distinct package. All packages start with the prefix com.subshell.sophora.teletext.script.* followed by the type of the script and potential sub packages. Please see the following mapping of module name to its package prefix that should help making the conversion:

teletext-scripts-client --> com.subshell.sophora.teletext.script.client
teletext-scripts-common --> com.subshell.sophora.teletext.script.common
teletext-scripts-formfieldchange --> com.subshell.sophora.teletext.script.formfieldchange
teletext-scripts-server --> com.subshell.sophora.teletext.script.documentchange
teletext-scripts-solr --> com.subshell.sophora.teletext.script.solr
teletext-scripts-testutil --> com.subshell.sophora.teletext.script.test
teletext-scripts-validation --> com.subshell.sophora.teletext.script.validation
4.4.0Before the update to Teletext 4.4.0Writing operations (save, publish, delete) for documents via Spring Data Sophora repositories are not supported anymore. If you use such calls in your plugin please replace them with their corresponding ISophoraClient functions.
VersionTimingChanges
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
4.4.0After the update to Teletext 4.4.0All custom Spring Data Sophora repositories in your plugin should extend com.subshell.sophora.teletext.api.repositories.ParentTeletextDocumentRepository now and not com.subshell.sophora.spring.data.repository.SophoraDocumentRepository anymore.

Sophora UGC: Update Notes

UGC Service

VersionTimingChanges
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.6.0After the update to UGC 4.6.0 and if you use the basic auth feature of UGCUGC now uses csrf tokens to protect Basic Auth sessions from csrf attacks. You also need to update UGC Submitter to version 4.6.0 if you want to use csrf protection. If you don't use the submitter and still want to use the UGC API, please check if you need to add the token to your playout. For example, you can find a tutorial here: https://docs.spring.io/spring-security/site/docs/5.0.x/reference/html/csrf.html
If you still want to use the swagger-ui and have activated basic auth, you have to enable csrf for spring doc in the configuration. Consult the documentation page for details on configuring a reverse proxy. Consult the UGC configuration documentation page for details.
4.8.0When updating to UGC 4.8.0Deprecated feature Legacy Rating has been removed.
VersionTimingChanges
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.
VersionTimingChanges
4.7.0When updating to UGC 4.7.0The dependencies of the UGC were updated. Crucial updates include Spring Boot in version 2.7.10 and Spring in version 5.3.26. Refer to the General Sophora 4 Update Notes above for further details.

UGC Taglib

VersionTimingChanges
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.
4.8.0When updating to UGC 4.8.0Deprecated feature Legacy Rating has been removed.
VersionTimingChanges
4.7.0When updating to UGC Taglib 4.7.0The dependencies of the UGC Taglib were updated. Crucial updates include Spring in version 5.3.26. If your applications use the UGC Taglib or other Sophora libraries, you should update to Spring 5.3. Refer to the General Sophora 4 Update Notes above for further details.

UGC Submitter

VersionTimingChanges
4.7.0When updating to UGC Submitter 4.7.0The dependencies of the UGC Submitter were updated. Crucial updates include Spring in version 5.3.26. If your applications use the UGC Submitter or other Sophora libraries, you should update to Spring 5.3. Refer to the General Sophora 4 Update Notes above for further details.

Sophora URL Library: Update Notes

VersionTimingChanges
4.2.0After the update to 4.2.0The configuration option sophora.url.domain-name was renamed to sophora.url.default-domain.
The configuration option sophora.url.prefer-site-domain was removed.

The precedence for generating an absolute URL for a document is now as follows:
  • The longest prefix match from sophora.url.structure-path-to-domain
  • The Sophora-Site URL property
  • The sophora.url.default-domain
4.5.0After the update to 4.5.0The configuration options for image URL generation have changed, there is a new property imageUrl in structure node documents and a new property sophora.image-service.url.structure-path-to-domain in the configuration properties. The existing property sophora.image-service.url.domain-name was renamed to sophora.image-service.url.default-domain.

The precedence for generating an URL for image documents is now as follows:
  • The longest prefix match from sophora.image-service.url.structure-path-to-domain
  • The Sophora-Site imageUrl property
  • The sophora.image-service.url.default-domain
4.7.0After the update to 4.7.0The class SophoraUrl has a new property AbstractRequestTarget requestTarget replacing the old property String redirectUrl, therefor the package of classes AbstractRequestTarget , RedirectTarget and ForwardTarget has changed from com.subshell.sophora.webapp.routing.redirect to com.subshell.sophora.webapp.commons.routing.

This change allows more flexibility for redirects via SophoraUrl and only affects you, if you use a custom URL codec implementation (read section "Define custom URL codec" in the Sophora URL Library Guide for more information) or the mentioned classes from old package com.subshell.sophora.webapp.routing.redirect.

Web App Framework: Update Notes

VersionTimingChanges
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/
4.3.0After the update to 4.3.0When a document template is requested with an URL which contains a non-existing structure path, a "404 Not Found" response will be returned.
4.6.0After the update to 4.6.0The HTTP status code of following redirect types is changed:
TEMPORARY_REDIRECT from 307 to 302
PERMANENT_REDIRECT from 308 to 301

Sophora YouTube-Connector (AV-Tool) Update Notes

Configuration Changes

VersionTimingChanges
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

VersionTimingChanges
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

sophora-server:
  username: webclient
  password: thisIsSecret
  host: sophora.hostname.com
  httpPort: 1196
  httpsPort: 1195

to:

sophora:
  client:
    server-connection:
      urls: ["http://sophora.hostname.com:1196"]
      username: "webclient"
      password: "secret"

Sophora TableStar Update Notes

TableStar

TableStar Controller

VersionTimingChanges
4.2.0This must be done before the TableStar Controller is started for the first time in version 4.2.0.
  • The Sophora Server connection info notation within the application.yml has been changed. An example of the new configuration can be found in the documentation of the TableStar Controller.
  • The management endpoints (e.g. /jolokia, /health) are now located below /actuator. Examples: /actuator/jolokia, /actuator/health

Last modified on 9/14/23

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

Icon