Administration | Version 4

Configuration Documents and Parameters

Get to know Sophora's different configuration documents, their purpose and the parameters you can use to set up the appearance of your DeskClients.

Standard Configuration Documents

Every Sophora installation has at least 5 different configuration documents. Depending on the add-ons you have purchased and the way in which you customised your system, there may be some more. Each of these additional configuration documents will be explained in the corresponding add-on documentation. In the following segment, we will introduce to you the five basic documents which you can find in the Administration view at System >> Configuration.

All configuration system documents consist of a dynamic table containing key value pairs. You can create, edit and remove key-value-pairs as in any dynamic table.


This document is initially created by the server and stores all abbreviations that can be or already are used as a markup. It contains a dynamic table with key-value-pairs, where the key is the abbreviation and the value is the abbreviated. You can define key-value-pairs in the system document which can be used as a markup in the copytext later on. Abbreviation markups that you or another user has created directly within the copytext are also stored within this system document.


The markup languages are not configured in a system configuration document, but in a select value. The corresponding select value document is initially created by the server; it has the name Languages. Nonetheless, you can define another document to provide the markup language. To do so, the configuration parameter document.markup.languages.selectvalue.externalid has to refer to the new language document (see the configuration properties table for the copytext). However, language select value documents need to be defined as top level select values, with the international country code as the key and a meaningful name.


The most important one is the Configuration document. It contains a dynamic table consisting of key-value-pairs. Within it, you can set general settings which will affect all DeskClients within your system, as well as some parameters concerning your Sophora server - which are usually adjusted in the server's file. You can find all valid server parameters in the corresponding article, all valid parameters for the DeskClient configuration a few paragraphs below.

It is necessary for any configuration change to take effect that you save and publish any adjustments you make in the configuration document. Some changes may even require you to restart your DeskClient or your server to become noticeable. Obviously, you also need to spell each key and value correctly, or you may experience no change in the DeskClients' behavior.

Note, that you can add, edit and delete the key value pairs as in any other dynamic table. Also, each key can get assigned multiple values.

+++ (Image: subshell/CC BY)
Add a new configuration document:

You can always create a new configuration document using the context menu of the entry Configuration within the Administration view.


You can configure mimetypes in this document. The usage of the document works analogous to the other configuration files.


This document lists the keys of all internal Sophora updates performed on the Sophora server or cluster the client currently is connected to. Under most circumstances, this document can safely be ignored. However, if an update has not been performed properly, it may be helpful to check the list of update keys stored here.

Configuration Parameters

DeskClient Appearance and Functionality

ParameterDescriptionPossible ValuesDefault
browser.enableProprietaryFeature.AACEnables the AAC codec in the integrated browser. This is needed for loading and playing web content with this format. Changing this parameter requires a restart of the DeskClient.
Important: By enabling this codec you state that you are aware that AAC is a proprietary component and you have a license in order to use it.
browser.enableProprietaryFeature.H264Enables the H.264 (MP4) codec in the integrated browser. This is needed for loading and playing web content with this format. Changing this parameter requires a restart of the DeskClient.
Important: By enabling this codec you state that you are aware that H.264 is a proprietary component and you have a license in order to use it.
browser.enableProprietaryFeature.WidevineEnables the Widevine digital rights management (DRM) technology in the integrated browser. This is needed for loading and playing web content protected by this technology. Changing this parameter requires a restart of the DeskClient.
Important: By enabling this feature you state that you are aware that Widevine is a proprietary component and you have a license in order to use it.
true/falsefalse the visibility of the Sophora ID in the compact view of the components tab.true/falsefalse
componentstructure.inheritance.canDisableIf set to false, inheritance of hierarchy groups cannot be (de-)activated using the context menu in a document's component structure.true/falsetrue
If set to true, inheritance of hierarchy groups can be (de-) activated in hierarchy documents only (in a document's component structure).
Note, that componentstructure.inheritance.canDisable must be set to true.
componentstructure.legacyComponentModeIf set to true, the legacy behavior on determining the allowed components in component groups is enabled. This affects reference types that extends another reference type.
See issue SOCI-869 for further details.
componentstructure.useDocumentReferenceLabelIf set to true and a reference label is configured in the reference type of a component, the reference label will be shown in the document's component structure instead of the Sophora ID.true/falsefalse
contentTypePropertyNameName of the property for the content types (for example used for submenus in document type filters within the search view).
This property has to be configured as a select value field within a specific node type configuration.
Any string propertysophora:contentType
deskclient.document.release.buttonVisibleManages the visibility of the button Release in the toolbar. Changing this parameter requires a restart of the DeskClient.true/falsetrue
deskclientHelpIndexUrlEvery user will be led to this URL, if he clicks the Help button in the Help menu, or if she presses F1.Any URL the internet browser of your trust can handle, e.g.:
deskclientHelpSearchUrlEvery user will be led to this URL, if he clicks the Help button in the Search view.Any URL the internet browser of your trust can handle, e.g.:
document.clone.technical.enabledEn- or disable technical cloning of documents. An editorial clone will store the Sophora ID of the original document in the cloned document's property sophora:originalDocument, whereas this property will be left blank with a technical clone.
If this key has assigned the value false, cloning a document will always yield an editorial clone; otherwise, there will be a submenu providing both options.
List of property names that should be excluded when exporting documents to Sophora XMLsophora:category
document.export.stringToReferencePropertiesMap node types and properties that should be exported as external reference.Format:
sophora-content-nt:teletextSlotPage=sophora-content:page, sophora-content:slot
document.file.saveFilePathIf enabled, the paths of file attachments in documents will also be saved. If disabled, the file paths will not be saved and already saved file paths will not be shown in the documents.
The path will be saved in the property sophora:filepath in sophora-nt:binaryData. Note, that any user may prevent the file path from being saved in his user preferences.
document.idstem.filter.regexpRegular expression to constrain the ID stem property.
NB: Even if you define a custom ID stem regex, all your ID stems still have to match the system default.
To write valid regular expressions, you can visit the Java documentation, for example.(?![iI][nN][dD][eE][xX][_-])[-a-zA-Z0-9_]*[-a-zA-Z_]
document.image.bulkCreate.limitSet the limit for a bulk creation of image documents, if the system permission for mass image upload is set.An integerNo limit
If set to true, the dialog Unpublished Components will hide any documents with a Publish At date set when publishing documents.
A user can overwrite this setting in his or her personal preferences.
document.state.disallowedExternalIdsForOfflineList of External IDs of documents that must not be set offline.Existing External IDs
document.state.disallowedUuidsForOfflineList of UUIDs of documents that must not be set offline.
This parameter is deprecated, use document.state.disallowedExternalIdsForOffline instead.
Existing UUIDs.
document.useVisibleDatePropertiesDefines wheter the document properties sophora:creationDate, sophora:modificationDate and sophora:publicationDate (default) or the properties sophora:visibleCreationDate, sophora:visibleModificationDate and sophora:visiblePublicationDate are used to display and sort documents e.g. in search results. Note: Use only if all documents have these sophora:visibleXxxDate properties (especially in Solr).true/falsefalse
environment.descriptionAn optional description for the server environment that is displayed in the DeskClient.Any string, e.g.:
"This is a test system for experimental usage."
environment.nameA name for the server environment that is displayed in the DeskClient.Any string, e.g: "TEST", "PROD", ...
geoData.document.externalIdExternal ID of the GeoData document which is used as a filter in terms of geo-blocking.Examples:
geoData.document.uuidUUID of the GeoData document which is used as a filter in terms of geo-blocking.
This parameter is deprecated, use geoData.document.externalId instead.
image.alignment.horizontal.defaultDefault horizontal alignment for image sections of newly imported images.left, center, rightleft
image.alignment.vertical.defaultDefault vertical alignment for image sections of newly imported, center, bottomtop
image.autoscale.jpegCompressionRatioCompression ratio when automatically downscaling JPEGs.Integers between 1 and 10080
image.autoscale.upscaling.enabledEnables automatical clipping and upscaling of image variants whose size is bigger than the existing original variant.
This ignores the disabled flag saved in image variants without own binary data and with sizes bigger than the existing original variant.
Enabling of this parameter can cause a difference between a preview of an image variant in DeskClient and a generated image.
image.autoscale.useSameRatioVariantEnables up/downscaling of image variants from existing variants with the same ratio.
Enabling the parameter image.autoscale.upscaling.enabled is required to perform upscaling or if the existing disabled flag of a required variant schould be ignored.
Enabling of this parameter can cause a difference between a preview of an image variant in DeskClient and a generated image.
passwordLost.mail.subjectThe subject of mails that are sent to users containing the code for the password lost function.
proposal.endDate.defaultSet the default period of a proposal. unknown leaves the field empty (see proposals).day
two days
search.button.positionConfigures the position of the search button. By default the button will be in front of the text field. If set to right it will be positioned behind the text field.left or rightleft
search.instantSearch.enabledConfigures whether the search results should be updated automatically when the search text or selected filter options change.true/falsetrue
searchAgent.updateIntervalThe interval that should be used to automatically update search agents (in seconds)positive integers300
sophora:attributeSets the name of the attribute property of reference node types (node types inheriting from sophora-nt:reference), resp. components. This property has to be configured as a select value field. The label of the selected select value in a component is displayed in the full display mode of the components tab in the document editor.sophora:attribute
sophora.client.connection.isReadAnywhereIf set to true, the readAnywhere functionality will be enabled for all clients. Requires the add-on High Availability Cluster.true/falsefalse
spellcheck.initiallyEnabledAdjust, whether spell checking is enabled by default. As soon as a user switches the spellchecking on or off, this will be saved into his or her personal preferences and overwrites this setting.true/falsefalse
tags.assist.enabledEn- or disable input assistance for tags in the search text input field, in the document editor's tags field and in the ID stem field of the New Document Wizard and change ID stem dialog.true/falsetrue
timing.validDateReferencePropertiesAllowed date reference properties for the timing configuration of structure nodes (e.g. sophora:creationDate). You can configure multiple values.
If no values are set or the key is missing, no filtering will be done (i.e. all date references are allowed).

Copytext Editor

ParameterDescriptionPossible ValuesDefault
copytext.paragraphbox.labelSpecifies the label for paragraph groups displayed in the copytext statistics dialog.Any stringParagraph Group (en)
Absatzgruppen (de)
document.markup.abbreviation.backgroundDefines the background color of the abbreviation markup.Valid color, represented by its HEX string#DDA0DD
document.markup.anchor.backgroundDefines the background color of the anchor markup.Valid color, represented by its HEX string#87CEEB
document.markup.languages.backgroundDefines the background color of language markups.Valid color, represented by its HEX string#FFDAB9
document.markup.languages.selectvalue.externalidExternal ID of the select value which provides the list of languages for language markups.Any string
document.markup.quote.backgroundDefines the background color of the quote markup.Valid color, represented by its HEX string#90EE90
textReplacementsList of characters that should be replaced when the user executes the Clean Up function within the copytext. You can use Unicode code points for special characters. Duplicated whitespace characters will be removed automatically and need not to be redefined here.targetCharacter=Replacement.


ParameterDescriptionPossible ValuesDefault
search.forceSolrIf the Solr search is enabled on the Sophora server and this key is assigned the value true, the DeskClient will perform a Solr search. This setting overrides the user preference Always run a JCR search.true/falsefalse
search.modifiersList of customised search modifiers. These modifiers are available below the Customised Search Modifiers toggle button within the Search view.
Either XPath or Solr queries can be used as search modifiers. XPath queries are marked by a leading §, while Solr queries are marked by a leading $. When using a Solr query, the Solr field names must be used instead of the property names.
<Label>;<Search modifier>
XPath example:
All published videos;§[@sophora:state='published' and @jcr:primaryType='sophora-content-nt:video']
Solr example:
All published videos;$[sophora_state_s:published AND primaryType_s:sophora-content-nt\:video]
showDeprecatedCategoriesDefines, whether the deprecated (old) categories should be shown. If the value is false, the enhanced categories are shown instead.true/falsetrue
textlinkNodeTypeDocument type of link documentsValid node type, e.g. sophora-content-nt:link
textlinkUrlPropertyName of the URL property within link documentsProperty name, e.g. sophora:url
textlinkDeniedDocumentTypes List of document types that cannot be referenced by text link in richtext and copytext.Node type names, e.g. sophora-content-nt:filter, sophora-content-nt:image
toolsList of (external) tools that should appear in the DeskClient's Tools menu
Tools may use special URIs to trigger actions in the DeskClient, e.g. to publish a document.
Channel overview;http://my.sophora-host:8082/system/channeloverview.jsp 
Sending a telegram;

HTTPS Connection Configuration

The following system parameters for the configuration of a HTTPS connection to the Sophora server also apply to other Sophora components. For the DeskClient, these parameters must be configured in the deskclient.ini file (and not in the configuration document). These parameters must be set behind the -vmargs parameter, e.g.:

ParameterDescriptionPossible ValuesDefault
-Dsophora.auth.trusted.certificates.onlyDefines, whether the certificate of the server should be checked or not. Note, that the protocol HTTPS must be enabled on the server.true/falsefalse
-Dsophora.auth.truststore.urlDefines the URL to the truststore. The truststore must contain the certificates of the Certificate Authority which should be used to verify the certificate of the server. Is only needed and considered, when the certificate will be checked.any valid URL, e.g.: file:/data/sophora/truststore.jksnone
-Dsophora.auth.truststore.passwordThe password for the truststore.Any stringnone

Command Line Parameters for DeskClients

You can start the Sophora DeskClient with the following parameters. There are two ways to provide these parameters on the DeskClient's start-up:

Starting the DeskClient within Eclipse : Go to the Run Configuration of the DeskClient (either enter the Run menu or press Ctrl while clicking the DeskClient's entry in the list of runs), switch to the tab Arguments and enter the desired key value pairs (as given in the table below) in the field Program arguments. Confirm your modifications with Apply and hit Run to start the DeskClient with the new configuration.

Starting a DeskClient's stand-alone version (autonomous release): Create a shortcut to the file deskclient.exe and open its Properties menu (via the context menu). Append the desired key value pairs (as given in the table below) after the path to deskclient.exe in the field target and confirm with OK. The parameters can also be specified in the file deskclient.ini which is located in the same folder as the deskclient.exe (for Windows). Mac users need to open the context menu on their file, select Show Package Contents, and navigate to Contents >> Eclipse to find the deskclient.ini.

-autoSave=(De)activate the automatic save mechanism of the document editor.
Possible values: true, false
-binaryDataCacheSize=The maximum in-memory size of the overall binary data cache (not per entry) in megabytes. Default is 500 MB.
-browserLogLevel=Sets the log level for the JxBrowser and Chromium process. Possible values: OFF, ALL, ERROR, WARNING, INFO, DEBUG. Default is INFO.
The jxbrowser_<date>.log file is located next to the deskclient.log file in the workspace. Only the latest 5 logfiles are kept.
-clientConfigurationFeatureId=If there are unique configurable features within the DeskClient that exclude each other, a select box precedes the login dialog. There, the user has to pick one feature that should be used. To automatically invoke a certain feature, you can specify its ID here. Note, that once the DeskClient has been started with one feature, this selection cannot be undone.
-editorPageDisposeCheckInterval=The interval (in seconds) to check for disposeable editor pages. Default is 30 seconds.
-editorPageDisposeTimeout=After this timeout (in seconds), not visible editor pages are disposed to free system resources. Default is 300 seconds.
-extendedLogin=(De)activate the extended login mechanism (that is: creating a history of used accounts, showing a checkbox to enable auto-login, etc.). This is a comfort feature when using different Sophora installations.
Possible Values: true, false

Note: When activated, the history of used accounts including the user credentials is stored unencrypted in the workspace of the DeskClient. Use this feature only in trusted environments where nobody else has access to the user's workspace files.
-forceAutoUpdateIf an update is available, the update starts without user confirmation
-host=Host URL
-iapClientIdSeparate Client ID to use for accessing Sophora behind an Identity-Aware Proxy if it not the same as in oauthClientSecrets. [since version 4.5.0]
-jxBrowser.chromiumDir=This parameter allows the user to choose a path where the chromium binaries are to be extracted. It has a lower priority than the jxbrowser.useDefaultChromiumDir parameter. Must not be a network drive! [since version 4.5.1]
-jxBrowser.useDefaultChromiumDirUsually, the Chromium binaries are extracted into the workspace folder (e.g. workspace\jxbrowser-<version>\bin). This parameter changes the location into the local user folder (i.e. %LOCALAPPDATA%\JxBrowser\<version>, e.g. C:\Users\<user>\AppData\Local\JxBrowser\<version> on Windows) which is the default of the JxBrowser. [since version 4.3.0]
-jxBrowser.remoteDebuggingPort=Sets the port for remote debugging to open the Chrome DevTools page in a separate Chromium-based browser that allows inspecting HTML, debugging JavaScript etc. For example, if -jxBrowser.remoteDebuggingPort=9222 has been set, the URL http://localhost:9222 (or chrome://inspect) can be called in a stand-alone Chromium-based browser to get an overview of all running JxBrowser instances in the DeskClient and to debug their HTML, JavaScript, etc. Alternatively, the direct remote debugging URL can also be copied from the DeskClient to the clipboard via the context menu of the respective JxBrowser (context menu entry "Copy Remote Debugging URL") in order to then open it in a Chromium-based browser. [since version 4.10.1]

Note: The remote debugging feature is experimental and compatible only with the Chromium version that equals to the version used by JxBrowser library. The Chromium version of the JxBrowser in the DeskClient is logged in the DeskClient logfile.
You should not open the remote debugging URL in other web browser applications such as Mozilla Firefox, Microsoft Internet Explorer, Safari, Opera, etc. This will lead to a native crash in Chromium DevTools web server.
-nlStarts the DeskClient in the given language; currently supported languages are English "-nl en" and German "-nl de" (which is the default).
-noAutoUpdateDeactivate automatic software updates on startup
-noUpdateButtonHide update button in login dialog
-oauthClientSecretsPath to a JSON file which contains client secrets and configuration (see Google Identity-Aware Proxy configuration) [since version 4.5.0]
-password=Login password
-proxyhost=Proxy host URL
-proxypassword=Proxy password
-proxyport=Proxy port number
-proxyuser=Proxy login name
-swtTrackingTriggers debugging for SWT (for Sleak)
-testModeStarts the DeskClient in test mode which presents internal information in the UI like the hashcode or ID of certain objects. May be used for debugging.
-updateUrl=List of update site URLs (separated by semicolon)
-user=Login user

This is an example for using the command line parameters within a Windows shortcut:

C:\Programme\Sophora\DeskClient\deskclient.exe -user=smith -password=secret

Additional parameters are explained in the Eclipse documentation.

Workspace and Configuration Directory

To separate the actual software and the user specific information (workspace and configuration), the parameters -data and -configuration can be used. Both parameters need a path to a certain directory as argument. These directories contain information like the postion and size of views, saved search runs or bookmarks. On a Windows computer, these parameters can be used in combination with environment variables, e.g. to point to the individual home directories of different users:

deskclient.exe -data %HOMEPATH%/sophora/data -configuration %HOMEPATH%/sophora/configuration

This behaviour can be enabled by creating a shortcut and handing in these parameters as explained in the section above.

DeskClient Customization

You can customize the login screen with your own image (e.g. a logo). It will be placed in the bottom right corner. You just have to put an image file named branding.png in the folder from which the DeskClient is started.

On Windows, it's normally the folder containing the deskclient.ini file.

On macOS, the image file must be placed in the /Contents/MacOS folder of the DeskClient app bundle. The image should be a transparent PNG not larger than 207 x 71 pixels.

Maximum size of branding logo is 207 x 71 pixels
Sophora Login (Image: subshell/CC BY)

Last modified on 10/16/20

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