Update Notes

Instructions for updating from previous Sophora versions.

Table of Contents

Update Guidance

Skipping Versions: If you skip a major Sophora release to update your instance to the current version, please consider the update notes of the omitted versions as well. See the list of Sophora versions to see the individual update instructions.

Changed Classpath for Scripts

We cleaned up some dependencies in the DeskClient and therefore some libraries that were accessible by scripts run by the client can no longer be used. Server scripts are not affected.

Client Scripts

These libraries are no longer available for Client Scripts from version 2.5.0 on:

  • activation-1.1.jar
  • antlr-2.7.7.jar
  • aspectjrt-1.6.11.jar
  • aspectjweaver-1.6.11.jar
  • avalon-framework-api-4.3.1.jar
  • avalon-framework-impl-4.3.1.jar
  • batik-codec-1.7.jar
  • batik-rasterizer-1.7.jar
  • most of bsf-2.4.0.jar
  • most of ehcache-core-2.5.7.jar
  • a part of com.jhlabs.filters.jar
  • the implementation of com.subshell.ibf
  • javamail-1.4.jar
  • jsr305-1.3.9.jar
  • metadata-extractor-2.6.4-subshell-1.jar
  • most of sanselan-subshell-0.97-incubator-3.jar
  • serializer-2.7.1.jar
  • spring-jdbc-4.3.7.RELEASE.jar
  • spring-tx-4.3.7.RELEASE.jar
  • xmpcore-5.1.2.jar

A full ist of missing packages can be found here. If your scripts use any of the listed packages the script will no longer work and you have to modify your code.

Validation Scripts

Validation scripts can only use classes accessible by com.subshell.sophora.client. That means additionally to the above mentioned libraries, also the following are no longer available:

  • batik-all-1.7.jar
  • ch.qos.logback.classic_1.2.3.jar
  • ch.qos.logback.core_1.2.3.jar
  • com.fasterxml.jackson.core.jackson-core_2.8.7.jar
  • com.fasterxml.jackson.core.jackson-databind_2.8.7.jar
  • com.subshell.sophora.json
  • org.apache.commons.logging_1.2.0.jar
  • org.apache.xerces_2.9.0.v201101211617.jar
  • org.apache.xml.resolver_1.2.0.v201005080400.jar
  • fop-0.94.jar
  • fop.jar
  • fop-hyph.jar
  • guice-3.0.jar
  • guice-assistedinject-3.0.jar
  • javax.xml_1.3.4.v201005080400.jar
  • nekohtml.jar
  • org.eclipse.*
  • spring-web-4.3.7.RELEASE.jar
  • xmlgraphics-commons-1.2.jar

A full ist of missing packages can be found here. If your scripts use any of the listed packages the script will no longer work and you have to modify your code.

Sophora Server

Mysql schema changed

In all server versions since 2.1.23, 2.2.28, 2.3.19, 2.4.3, 2.5.0 the database schema for Mysql is changed, to avoid a performance bottleneck. The problem is described in detail here and here.

The modified database schema is used for newly created databases only. For existing databases (main repository and archive repository), the following SQL statements can be executed. This should only be done while the sophora server is stopped.


JMS Message Properties changed

Some message properties for inter server communication have been modified with Version 2.5.19. Therefore a slave older then 2.5.19 might have trouble reading these messages properties from a master of version 2.5.19 or newer. To avoid these problems, we strongly recommend to update your connected Sophora Servers together starting with the slaves.

Sophora Delivery

Changed behavior when accessing reference properties in templates

Accessing a direct reference property of a document with an external reference returned in previous versions a ContentValue instance capsuling the external id of the reference. Therefore the condition ${not empty current.referenceProperty} falsely returned true.

With the version 2.5.0 and ongoing accessing an external reference in a reference property returns null and therefore the above condition returns false. The changed behavior may cause NullPointerExceptions in existing templates, if there are any conditions like ${not empty current.referenceProperty.propertyOfReferencedDocuments} to check for an external reference. Please review all accesses to reference properties via the ContentMap. The access of referenced documents in components is not affected by this change.

Removing the filter pattern for flushing cache fragments on changes to documents or structure nodes

The following properties and functions are removed from Sophora Delivery with version 2.5.0

sophora.delivery.cache.remove.filterPattern.documentA regular expression that is used as a filter for files that will be deleted when a registered document changes. If set only those cache fragments will be deleted that match the given expression. This feature only works in production environment (isProduction=true).
sophora.delivery.cache.remove.filterPattern.structureNodeA regular expression that is used as a filter for files that will be deleted when a registered structureNode changes. If set only those cache fragments will be deleted that match the given expression. This feature only works in production environment (isProduction=true).
sophora.delivery.isProductionDecide if filterPattern should be used or not. (Default: true)

AbstractContentMap: Improved Getters

The AbstractContentMap can now parse Long, Double, Date and Boolean values from String properties.

The getBoolean method will no longer throw ClassCastExceptions and instead behaves as getLong, getDouble and getDate do.

This feature is available in versions 2.2.24, 2.3.16, 2.4.7, 2.5.4 and newer.

Sophora Delivery: More exact invalidation when changing YellowData

The Sophora Delivery used to treat YellowData changes like document changes when it comes to flushing cached content. This has been adjusted with Sophora Delivery 2.5.9. Now while creating cacheable fragments the delivery tracks, whether yellow data has been accessed (e.g. through virtual properties) and then flushes cached content accordingly.

To do so, an update has to be performed on the cache DB. This update might take a couple of minutes during the first start after the update. Updating a sample cache DB with 15 million entries took 5 minutes.

Sophora API

Deprecated methods are removed

Several long term deprecated methods have been finally removed from the package com.subshell.sophora.api.

Most removed methods have a (slightly different) direct replacement. Especially methods using Strings to hold UUIDs can easily be replaced with corresponding methods directly using UUID-Objects. Most of the replacement methods are already present in existing versions (e.g. 2.4 or 2.3), thus it is recommended to prepare custom code before the update to version 2.5 is performed.

Special attention has to be paid to groovy scripts (e.g., server or deskclient scripts). They have do be validated against the new API to ensure that no removed methods are used.

Noteable API Changes (since API 2.5.53)

The method ItemPath.getIndex() may now return negative values. The special value ItemPath.ALL_ITEMS_INDEX may be returned by this method. To check if all items with the name of the path are denoted use the method ItemPath.isForMultipleItems().

Changes to custom fields for properties (since DeskClient 2.5.17)

Affected Class/InterfaceChange
com.subshell.sophora.eclipse.editor.form.IFormFieldthe method boolean isInheritanceOfValueEnabled() has been removed
com.subshell.sophora.eclipse.editor.form.AbstractFormFieldthe method String createLabelTooltip() has been removed
the method boolean isInheritanceOfValueEnabled() has been removed

The following IContentManager methods now throw an ItemNotFoundException if no document with the given UUID exists.

  • lock(SessionToken st, UUID documentUuid, boolean force)
  • unlock(SessionToken st, UUID documentUuid)
  • getLockState(SessionToken st, UUID uuid)

This makes the behavior of these methods consistent to other document-related methods.

Note that this also affects these corresponding ISophoraClient methods, which now also throw this exception:

  • lock(UUID uuid, boolean force)
  • unlock(UUID uuid)
  • getLockState(UUID uuid)

Sophora Client: Configuration property removed

The sophora client configuration property document.idstem.filter.useApiRegexp has been removed. All sophora ID stems now have to match the system internal regexp and the user defined regexp if it is defined.

Migrationmode safety update

A safety feature was added to the Sophora Server. Documents without "modified by" or "modification date" properties are no longer accepted by the server if migrationmode is active in the current session. This was only an issue, if the migrationmode was set unintentional.

Component Labels

The label on the component tab can now be "overridden" by setting the document label in the reference type. If a document label is configured in the reference type, the value of those property will be displayed (or the overridden value of the component). To keep the previous labels, make sure no property is configured as document label in your reference types.

New Feature in User Generated Content: Responses

Usercomments now have a new field called parentId. This means that a new column will be created in the database table usercomment after the update. This may take a while depending on the size of the table.

Preview documents

Preview documents have to be published in order to be available as preview to all users. You should publish all preview documents prior to updating to ensure that the same previews are still available.

Document Editor

The document editor now clearly separates form field groups, if they are configured to be highlighted. Now you can easily see where a group ends. Therefore the editor uses "cards" for each group and fields without a group. Please check your node type configuration, if combinations of groups are displayed as intended in the new DeskClient.

Groups with the display type 'No highlighting' will stay on the current card. If you want to have fields on the same card, you need to use form field groups with no highlighting. Contrary if you want to have a separator between a highlighted group and the following fields you must not use groups without highlighting.

In the picture you see how groups with a label are extended by groups with no highlighting to use multiple columns in a part of the card. The blue card ends because the groups are followed by a configuration without a group.

Migration of old channel properties to sophora:channelSettings childnode

With the new scheduled publishing of playout channels, a channel update will be performed to replace all uses of the sophora:disabledChannels property with the new sophora:channelSettings child node. All property configurations using the old property will be removed and replaced with a child node configuration using the new child node at the old configuration's location. Additionally, the following configuration key will be added to the configuration document which ensures that the sophora:channelSettings childnodes won't be included when exporting a document. This is necessary because the importer will create them automatically from the channel fields in the XML.

document.export.childNodesNotToExportInSophoraXml = sophora:channelSettings

Text (Fixed Size): New parameter for changeable background color (Since DeskClient 2.5.6)

The new configuration option "background color changeable" in the input field type "Text field (Fixed Size)" comes with an additional parameter in the com.subshell.sophora.hyphenation.TextDocument constructor. If you wish to use this feature, the constructor with the additional parameter backgroundColor must be used in all scripts that modify the relevant text fields. Otherwise, the changed background color is not persistent. The constructor without a backgroundColor is still valid for text fields that don't implement this feature.

TextDocument(Scale scale, List<String> textLines, List<ManualHyphenation> manualHyphenations, List<TextColor> textColors, 
Optional<RGBColor> backgroundColor)

Legacy Teletext features removed (Since DeskClient 2.5.31)

The legacy slot range editor and Texas editor for teletext pages have been completely removed from the DeskClient.

New Solr Core default-live

The new solr core default-live is now available. It is present on master and slave servers and contains all documents in their latest live version. The core will be created and indexed after the first start of the sophora server with a version greater than or equal to 2.5.0. This solr core can be extended with custom solr indexing scripts by using the default mapping document.

Custom DeskClient-Plug-ins

Dependencies (since 2.5.6)

The DeskClient does no longer reexport the bundle org.eclipse.core.runtime, due to version problems with the (re-)exported package javax.annotation. That bundle is required if you have an activator or use localization (class NLS) and it also provides packages like org.osgi.framework. You should check that your plug-in compiles against the new version of the DeskClient. If some classes from the packages org.eclipse.core.runtime, org.eclipse.osgi or org.osgi are missing, you have to add the dependency directly.

Require-Bundle: org.eclipse.core.runtime;bundle-version="3.13.0"

Also the library Guava must now be imported directly to not enforce a version for all plug-ins. Previously this was provided by com.subshell.sophora.eclipse.libs for all plug-ins. Now each plug-in which makes use of Guava has to declare this dependency on its own.

Require-Bundle: com.google.guava;bundle-version="21.0.0"

Updated Jetty version 9.4.7

The sophora server now uses the embedded web server jetty in the version 9.4.7.v20170914. As a result the HTTP protocol in the version 0.9 is not supported anymore.

Schedulable channels

It is now possible to schedule the enablement of channels in documents. The channel information of documents are from now on stored in child nodes of the type sophora:channelSettings and no longer in the properties sophora:enabledChannels and sophora:disabledChannels. All required node type updates are performed automatically.


Configurable headline and content size

With the UGC release 2.5.4 the maximum size of the fields headline and content becomes configurable. If a database is used that was created before version 2.5.4, the fields HEADLINE, CONTENT, ORIGINALCONTENT and ORIGINALHEADLINE of the table USERCOMMENT and the fields HEADLINE and CONTENT of the table IMAGEUPLOAD must be changed to the type text.

Jolokia port

Since 2.5.11 the ugc-webapp opens port 1694 for jolokia. If it is already binded by another application you can configure it with jolokiaPort in ugc-webapp.json. See https://www.subshell.com/en/sophora/documentation/205/add-ons/user-generated-content/index.html#ugc-webapp.

Changed UGC Group IDs and Packages

With UGC release 2.5.24, all UGC maven modules changed their groupId from com.subshell.sophora to com.subshell.sophora.ugc. Update your dependencies accordingly. You may also have to change other configurations, e.g. logback.xml, because also the Java package names changed from com.subshell.sophora.usercontent to com.subshell.sophora.ugc.

Due to changed package names, an old (i.e., < 2.5.24) ugc-webapp is not compatible with a new (i.e., >= 2.5.24) ugc-submitter or ugc-taglib. When increasing the UGC versions, you must first upgrade the ugc-webapp to at least version 2.5.25 before increasing the versions of the rest.

Sophora-Addon Maps

Refinement of the add-on key (since DeskClient 2.5.15)

With the new Maps addon you can configure the map to be rendered by one of three different providers: Bing, Mapbox and OpenStreetMap. You need to confirm the update "Sophora Maps: Add-on activation refinement" on the first connection with the DeskClient, so that the former add-on key will be changed to the Bing license key. Please note that the keys of Mapbox and OpenStreetMap will not be entered automatically. If you have acquired one of these licenses, it is important to inform your subshell contact to provide these keys to you.