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 📱

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.

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
• maxFileSize: The maximum file size allowed per image upload in KiB (1024KiB = 1MiB)
• 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
  maxFileSize: 10240
  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.