Sophora Web admin guide

Configuring Sophora Web

Sophora Web runs as a standalone Java application. As it ships with a built-in web server, there are no further installation requirements. It gets configured via an application.yml and a configuration system document of the nodetype sophora-nt:sophoraWebConfiguration. The nodetype and a default configuration document are automatically created when first starting a Sophora Web instance. The configuration document to be used can be configured via its externalId in the application.yml. For further information on the configuration document, consult its dedicated section.

How to pass a configuration file

If you prefer to place the application.yml somewhere else then you can provide the path to the directory containing the application.yml using the command line parameter -Dspring.config.additional-location=/path/to/config/directory.

Structure of the configuration file

application.yml

spring:
  application:
    name: Sophora Webclient 📱
  servlet: 
    multipart: 
      max-file-size: 2GB 
      max-request-size: 2GB

logging:
  path: logs

server:
  port: 8080

sophora:
  client:
    server-connection:
      urls:
		- "http://sophora.hostname.com:1996"
		- "https://sophora.hostname.com:1995"
	  username: webclient
	  password: thisIsSecret

backend: 
  redirect:
    domain: sophora.my-news-company.com
    port: 443
    protocol: https
  thumbnailCacheProperties: 
    cacheDirectory: cache/thumbnails 
    maxEntryAgeInHours: 24
  dataDir: data
  maximumSessionsPerUser: 1
  sessionTimeoutInMinutes: 1440
  enableXsrfProtection: true
  enableHsts: true

webclient:
  url: 					    ...
  document: 			...
  image: 				    ...
  configuration:
    configurationDocumentExternalId: ...

Spring configuration

The first group spring creates an identifier for the running application. This name will be displayed in the Sophora Dashboard as well. And yes, you can use Emojis here.

Additionally, two parameters (max-file-size and max-request-size) need to be provided which control how large the file- and image-uploads of users can be. Default: 2GB

Logging configuration

The second group logging can be used to configure the path of the log folder. This path is defaulted to "logs".

Server configuration

The group server contains relevant information about Sophora Web's embedded Tomcat-Server. The only required parameter of this section is the server's port. Sophora Web configured as shown above would listen to incoming HTTP requests on the specified port 8080.

Running Sophora Web with HTTPS

For productive environments we recommend running Sophora Web with HTTPS via a reverse proxy, e.g. nginx. If this is not possible, you can run Sophora Web natively via HTTPS in which case a modification to the configuration and a valid certificate are neccessary.

A modified configuration might look like this:

server:
  port: 8443
  redirectFrom: 8080
  ssl:
    key-store: mobileclient-keystore.p12
    key-store-type: PKCS12
    key-alias: tomcat
    key-store-password: sophora
    protocols: TLS
    enabled-protocols: TLSv1.2
    ciphers: TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Sophora Web then listens to incoming HTTPS requests on port 8443 and redirects incoming HTTP requests from port 8080 to 8443. The parameter for redirecting HTTP traffic is optional.

The above configuration restricts the possible ssl protocols and ciphers to versions considered the most secure. You can change them, but should only do so, if you have clients that don't support TLSv1.2.

Using Security features with Java 11+

Since Java 11, you can profit from the new TLS version 1.3. A secure configuration for TLSv1.3 would look like that:

server:
  ...
  ssl:
    enabled-protocols: TLSv1.3
    ciphers: TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_GCM_SHA256, TLS_AES_128_CCM_8_SHA256, TLS_AES_128_CCM_SHA256

All other configuration options remain unchanged.

Creating a sample certificate

Proper certificates should be retrieved from certificate authorities. For testing purposes however a self signed certificate can be used. Using oracle's keytool a certificate might be created on command line with these arguments:

keytool -genkey -alias tomcat -storetype PKCS12 -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -keystore mobileclient-keystore.p12 -validity 3650

Keytool is interactive and will prompt further input. When asked for your name, you must provide the domain of the host running Sophora Web, e.g. web.sophora.com.

The provided password must match the server's property server.ssl.key-store-password.

Sophora Server configuration

The section sophora describes how Sophora Web connects to a Sophora Server. The corresponding configuration options are listed in the Spring Boot Sophora Commons documentation.

Backend configuration

The backend properties section can be used to setup properties used to configure the backend of Sophora Web.

Redirect

Sophora Web's frontend uses WebSockets to communicate with the backend. In some edge cases where the url in the browser does not match a FQDN it is possible that the WebSocket connection cannot be established properly. To solve this issue, the backend can redirect requests to a desired location. To configure the redirect you can use the redirect section. There you need to active the redirects by setting the domain for Sophora Web. In addition you can configure the port (which per default keeps the port of the incoming request) and the protocol (per default, the protocol of the incoming request is kept).

Thumbnails

Sophora Web calculates it's own image thumbnails for all documents that are displayed e.g. in search results.
Preferrably these thumbnails should be cached for not always having to recreate them. To enable the thumbnail cache, the backend properties must contain the section thumbnailCacheProperties. You can adjust the directory Sophora Web uses to store cached thumbnails with the cacheDirectory property and also set how many hours the cached entries should be valid by using maxEntryAgeInHours. See the section on configuring images for further details on those thumbnails.

Making the branding icon image customizable

The icon design can match the application theme by using the CSS variable --branding-icon-color for the SVG fill:

fill: var(--branding-icon-color);

This ensures the SVG color automatically updates with theme changes and it works best with single-color images.

Data directory

To use a custom data directory simply provide the dataDir property. The slaves.xml file will be generated inside the data directory. Its value has to be a valid directory path relative to the jar file or an absolute path. The default is dataDir: data.

Maximum sessions per user

You can optionally configure a limit on how many active sessions a single user can have at a time with the property maximumSessionsPerUser. This only affects sessions within a single Sophora Web installation. Should the user create more sessions, older sessions will be closed automatically.

Setting the property to zero, any negative number or not setting it at all will disable the session limitation feature.

Session timeout

Sessions time out after 24 hours per default. If you want to customise this you can use the sessionTimeoutInMinutes property and assign it a numeric value.

HTTP Strict Transport Security

You can configure Sophora Web to use HSTS by turning on the property backend.enableHsts. This requires Sophora Web to run with HTTPS in the first place. HSTS is deactivated by default.

Important: HSTS will instruct browsers to prevent unencrypted HTTP traffic to the servers host. So we propose to switch HSTS on as long as you have no services based on HTTP that are accessed under the same hostname as Sophora Web.

Sophora Web configuration

All nodes under webclient which are abbreviated with three dots directly affect the frontend and are discussed per sub section below.

Configuration Document

The configuration document to be used can be set via its externalId.

Tab Configuration

The tabs in documents in Sophora Web can be configured by an administrator. For every Sophora tab document it is possible to choose whether it is visible in Sophora Web or not via a checkbox in the tab document itself. This way it is possible to create tabs which are suited for Sophora Web, the DeskClient or both.

Additionally supported input field types

Sophora Web by default tries to map the configured input field types from the node type configuration to its own input field types (see also the section on supported input field types below).

However, you might extend this mapping. This is useful especially if you are running your own DeskClient-Plugin with custom input fields.

Example

 additionalFormFields:
  plainText:
    - 'com.subshell.sophora.eclipse.myPlugin.myCustomTextField1'
    - 'com.subshell.sophora.eclipse.myPlugin.myCustomTextField2'
  integer:
    - 'com.subshell.sophora.eclipse.myPlugin.myCustomIntegerField'

Sophora Web will then display properties displayed with one of these field types as regular fields. It will support the field configurations that are also available on the Sophora native property configurations, such as "required". If your custom input field comes with custom configuration options then those will be ignored by Sophora Web.

Custom URLs

Using the parameter group url, you have the possibility to define custom URLs. At this point, you can only use this group to provide a custom help page URL in (e.g. to your intranet and customized to your Sophora Web configuration). If this value is set, a Sophora Web user will be able to open the help page by hovering over the Sophora icon in the top right corner and by clicking on the appearing question mark icon. The parameter is optional and if it is missing or set to an empty string, the icon will not be visible. An example configuration of this parameter looks like the following:

Example

url:
  helpPage: https://subshell.com/docs/mobileclient/

Document Save, Search and Templates

Example

document: 
  save:
    externalIdsOfScriptsToExecute:
      - custom-client-script
      - social-media-script-resolve-twitter-urls
    hoursToKeepUnsavedVersions: 4
  search:
    sort: sophora:modificationDate descending
    searchable: 
      - sophora-content-nt:story 
      - sophora-content-nt:liveReporting
    filterOptions: 
	  - byMe
	  - nodeType
	  - other
	  - structureNode
	  - time
	  - status
  creatable:
    - primaryType: sophora-content-nt:story
      requiresTemplate: true
    - primaryType: sophora-content-nt:story
    - primaryType: sophora-content-nt:liveReporting
sophora-mobileclient-administering-guide100
  customMetaPropertyNames:
    - custom:my-date-property
    - custom:other-property

save

This section controls the behaviour during the saving of documents and other saving related configuration.

The first parameter is the list externalIdsOfScriptsToExecute. The external IDs of client scripts to be executed during saving have to be listed here.

Additionally Sophora We, has a feature to store unsaved changes of documents (e.g. in case a browser crashes to prevent loss of unsaved work). The minimum hours to keep a version can be set with the hoursToKeepUnsavedVersions parameter, which defaults to 4.

search

searchable (optional): This allows you to define which node types should be searchable and appear in the search filters. Using the sort property, you can change the order the search results. The results are sorted in descending order by sophora:visibleModificationDate, if it is configured in the Sophora Configuration Document, else the sophora:modificationDate will be used.
If left blank, all available nodetypes are configured automatically. This takes user perssions into account.
Another option is to exlcude certain node types with the - prefix:

webclient:
	document:
		search:
			searchable:
				- "-sophora-content-nt:story"
				- "-sophora-content-nt:blog"

filterOptions: Each of Sophora Web's search views comes with a text field and a number of additional search buttons. This property defines which buttons are available and in which order they appear. Possible search filters:

• byMe: Filter documents created or edited by you
• nodeType: Filter by nodeType
• structureNode: Filter by structure node
• time: Restrict the search to a time range
• status: Filter by document status
• custom: Custom filters

For more information on how these filters work, see the section "Using Search Filters" in the article on searching.

creatable (optional)

This group defines which documents can be created. Each entry must provide a primary type. The optional parameter requiresTemplate indicates whether a document template has to be selected by the user upon document creation (default: false). If requiresTemplate is set to true it is not be possible to create a document without a template.

Documents of node types not listed here, can not be created from the new document page. This however does not restrict implicit document creation through image upload or link creation.

If left blank, all available nodetypes are configured automatically. This takes user perssions into account.
Another option is to exlcude certain node types with the - prefix:

webclient: 
	document:
		creatable: 
			- primaryType: "-sophora-content:story" 
			- primaryType: "-sophora-content:blog"

customMetaPropertyNames

In this group you can list properties that should be visible in the document information dialog under the "custom" tab. Effectively this makes it easy for you to display your custom metadata properties.

It supports string and date properties. String properties will just display the stored value without taking special fields into account. Select values will display the labels of the selected values.

This configuration is global, so it will affect all of your document types. But don't worry: If a document type does not have one of the properties, it will simply not show up. To avoid an information overload, the values will also not be shown if they are empty.

Image Configuration

• maxConcurrentUploads: The maximum number of images allowed to be uploaded concurrently
• imageNodeType: Describes used node types for images and component images for different document types
• thumbnailImageVariant: Determines the image variant to be used when showing thumbnails for documents displayed e.g. in search results or components. For none-image types, thumbnails are generated out of related images, that are configured with the node types thumbnail-xpath. Though technically any image variant will do, we propose using a variant with a 16:9 aspect ratio and a width of around 230 pixel. Using considerably larger variants might decrease Sophora Web's performance.
• newImageTemplate: A map of properties and values which should be used for all newly created images. The usage of such a template allows you to set required properties that should automatically be set for new images.
• newImageTemplateExternalId: Works similar to newImageTemplate, but instead of inlining the template, the external id of an image template document is used. This setting has no effect if newImageTemplate is used.

Example

image:
  maxConcurrentUploads: 10
  imageNodeType: sophora-extension-nt:image
  thumbnailImageVariant: small
  newImageTemplate: '{
			"jcr:primaryType": "sophora-extension-nt:image",
			"sophora:tags": "mobile image",
			"sophora-extension:caption": "Webclient Upload",
			"sophora-extension:alttext": "Webclient Upload"
		}'

Toolbar configuration

The actions in the toolbar can be defined here, as well as their display order. The IDs of default Sophora actions are: save, publish, offline, refresh, preview, propose, clone, and move. A default configuration is used if this option is not defined.

The ID of optional Sophora actions are delete and restore.

Example

webclient: 
  documentToolbar:
    - id: save
    - id: publish
    - id: offline
    - id: refresh
    - id: preview
    - id: propose
    - id: move
	- id: delete
	- id: restore
    - id: change-id-stem

Icons

Default action icons can be overwritten, e.g. the the publish icon can be replaced with a colored one. The icon can be defined as either a path to an SVG file (other formats are not supported) or an icon name from materialdesignicons.com. SVG paths are prioritized over icon names.

webclient:
  documentToolbar:
    - id: publish
      iconName: check
    - id: save
      iconPath: /path/to/custom-save-icon.svg

Scripts

Custom client scripts can be added to the toolbar. They require an external id, a label and an icon. It can also be configured, whether the script can be executed on a document that has unsaved changes or not.

- scriptExternalId: 1c5793aa-7acf-4a3e-b555-9a73dc72e27c
  label: Publish Plus
  iconPath: /path/to/icon.svg
  canExecuteOnDirtyDocument: true

Shortcuts

Shortcuts can be defined for all actions including scripts. The default Sophora shortcuts are used for default actions, but they can be overwritten.

- scriptExternalId: 1c5793aa-7acf-4a3e-b555-9a73dc72e27c
  ...
  shortcut:
    key: F4
    ctrlKey: true
    shiftKey: true
    altKey: true

Shortcut configuration

The following properties can be used to configure shortcuts:

Properties

The following properties can be configured for toolbar actions:

Cross-Site-Request-Forgery Protection (XSRF / CSRF)

XSRF protection is enabled by default. It can be disabled by setting the backend.enableXsrfProtection configuration value to false (this is not recommended). Proxy servers used to access Sophora Web need to forward the corresponding HTTP Header (X-XSRF-TOKEN) or else Sophora Web will not be able to work correctly resulting in many 403 (Forbidden) status codes in the frontend.

Further configuration options

Sophora Web registers itself as a tool towards the Sophora Server and the Sophora Dashboard. You can use general Sophora Tool capabilities to overwrite the hostname and port it uses for doing so as described in the Sophora Tools Guide.

Configuration Document

In addition to configuration via the application.yml, some configuration options for Sophora Web can be changed via a dedicated configuration document, allowing to change these options on-the-fly without needing to restart the application.

The document to be used can be configured via its externalId in the application.yml, under webclient.configuration.configurationDocumentExternalId. The externalId of the default document is 'default-sophora-web-configuration'. That default document is also used as a fallback if the selected configuration document is deleted or set offline. If you want to make changes to the configuration, you have to save and publish the document for the settings to take effect.

The configuration document for Sophora Web can be edited via the Admin View in the Deskclient, under "Sophora Web Configuration", or via Sophora Web in the Toolbar under "Configuration" (only visible for admins). It can be changed on-the-fly, allowing to change configurations while Sophora Web is running. It contains the following configuration options:

Theming

Sophora Web's front-end offers a default color theme with light and dark modes and, when enabled, is automatically switching to light or dark mode according to the user's system settings.

Furthermore, Sophora Web installations support custom branding themes, enabling a unique visual identity tailored to specific requirements, such as corporate branding. A configured branding theme takes precedence over the default theme. Users can switch between the default and branding themes after login; their selection is stored in the browser.

Our theming leverages Material Design, generating themes based on provided color values. For detailed information and color experimentation, please refer to the Material Design theme builder or the Material Design website. Especially the theme builder can give a useful preview of what a theme could look like in Sophora Web.

Branding is configured within the configuration document.

If only the primary color is specified, the remaining colors are automatically generated. Omitting the properties from the configuration document disables custom branding.

Sophora Web field types

List of fieldtypes

This list includes all input field types and provides basic information on how to use them.

• Copytext: This is the field used to edit paragraphs in the copy text. Sophora Web supports the regular copy text configuration, such as allowed paragraph styles and default style.
• Text (with Styles): The rich text editor lets you insert multi-line formatted text that supports bold and italic text, as well as ordered and unordered lists.
• Text: Allows you to enter unformatted plain text.
• Long: This field type can be Integer, Text, or Selection Value. You can enter integers and longs.
• Double: This field type can be a Floating-point number or Text. We recommend using the Floating-Point Number input field type for double properties. Your browser's language settings determine whether a comma or a period is used as a delimiter.
• URL: Used for external URLs, such as https://subshell.com.
• Checkbox: Allows you to check or uncheck a value.
• Color: Color Picker to select RGB colors.
• Date: This input field allows you to pick a date and/or time. Supported date formats: Date and time in hours and minutes (default) Date and time in hours, minutes and seconds (dateAndTimeWithSeconds)
• Dynamic Table: The dynamic table input field type allows you e.g. to create news tickers. You can add rows to the dynamic table via the "Add row" button at the top of the table and you can edit existing entries by opening them via a click. The buttons on the right-hand side of existing rows allow you to rearrange or to delete these individual rows. To keep the table sleek and lightweight, only five rows are visible. To see more rows you can conveniently navigate through them by using the pagination buttons below the dynamic table. Collapsed rows will just show the content of the first column. You can change this by configuring a property as the title property. To do so, use the Sophora DeskClient and edit the NodeType configuration for the column nodetype. There you can edit the property document title for this nodetype.
• File: File upload for binary data
• Selection Value: The supported selection values intelligent, list, list (editable) allow you to choose from one or more predefined values by clicking on the field and selecting the entries shown. Since version 3.5.0, the select value form field also supports custom text if the editable configuration is enabled or list (editable) is used.
• Taxonomies: An input field of this type can be used to enter multiple values which can be reused (tags). These values can be any kind of text, words or phrases. There needs to be a backing system document in which all entered values are stored. Please note: The input field type Taxonomies is only available to those users who purchased themodule Taxo.
• Reference: Allows you to create a reference to another document.
• Image focus: The image focus is an input field type designed to be used just with image documents. It allows you to mark a spot on the image as it's focus point. All variants of this image will be calculated such that their center is as close to this point as possible.
• Tags: Allows you to enter tags into a basic text field, separated by spaces.
• Text (with Teaser Image and Style): Allows you to enter text with styles. Sophora Web will not show the teaser image alongside the text (though it will appear on the components tab). Field support has been added for compatibility reasons mainly.
• Text (with Teaser Image): Allows you to enter text with styles. Sophora Web will not show the teaser image alongside the text (though it will appear on the components tab). Field support has been added for compatibility reasons mainly.
• Text (Fixed Size): Sophora Web supports a simplified non-WYSIWYG version of this field. The number of characters and lines are displayed. In the background the text is hyphenated, based on the configuration of this field. The hyphenated text is not shown in the field. Teletext-specific features are not supported. All existing Teletext characters will be removed.
• Form Field Group: A Form Field Group is a group of input fields, it consists of one or multiple of the other input fields listed here. The input fields that are part of a Form Field Group can be used just as they are used outside of Form Field Groups.

Sophora Web: Embedded mode

The embedded mode enables you to embed a stripped down version of Sophora Web as a document editor into another web application.

• The navigation panel is disabled, therefore you can't navigate to the search page, create new documents or change the current user.
• Links are disabled, referenced documents can only be opened in a new tab.
• The mode change button includes a section to open the current document in a new tab.

To enable the embedded mode:

• Append the parameter ?embed=true to the URL of a document.

Read-only mode in Sophora Web

The read-only mode enables editors to open a document without locking it.

To enable the read-only mode:

• Append the parameter ?readonly=true to the URL of a document.