Administering the MobileClient

Learn how to configure and administer Sophora's MobileClient.

Table of Contents

Configuring The MobileClient

The Sophora MobileClient runs as a standalone Java application. As it ships with a built-in web server, there are no further installation requirements.

How to pass a configuration file

The Sophora MobileClient is basically configured by a single file called application.yml. By default it should be located next to the sopora-webclient.jar.

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.

The MobileClient comes with a default configuration you can extend and override. If you use the parameter -Dspring.config.location instead of -Dspring.config.additional-location, the default configuration parameters will not be used. We strongly advise you to always use -Dspring.config.additional-location.

Structure of the configuration file

application.yml
spring:
  application:
    name: Sophora Webclient 📱
logging:
  path: logs
server:
  port: 8080
sophora-server:
  username: webclient
  password: thisIsSecret
  host: sophora.hostname.com
  httpPort: 1196
  httpsPort: 1195
backend: 
  redirect:
    domain: sophora.my-news-company.com
    port: 443
    protocol: https
  thumbnailCacheProperties: 
    cacheDirectory: cache/thumbnails 
    maxEntryAgeInHours: 24 
  bannerImage: 
    imagePath: /path/to/image.png 
    altText: Production Instance
  dataDir: data
  maximumSessionsPerUser: 1
  sessionTimeoutInMinutes: 1440
webclient:
  supportedTabs:		...
  url: 					    ...
  document: 			...
  copytext: 			    ...
  image: 				    ...
configuration-sets: ...
Note: To avoid malfunctions, please ensure the configured user has at least read permissions on all documents.

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.

The connection to the Sophora Dashboard requires the MobileClient in version 2.4.48, 2.5.28 or newer.

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 the MobileClient's embedded Tomcat-Server. The only required parameter of this section is the server's port. A MobileClient configured as shown above would listen to incoming HTTP requests on the specified port 8080.

Running the MobileClient with HTTPS

For productive environments we recommend running the MobileClient with 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

The MobileClient 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 new Security features with Java 11

If you run the Sophora MobileClient with 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
    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 the MobileClient, 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-server describes how the MobileClient connects to a Sophora-Server. Connecting to the Sophora-Server can be done through HTTP or HTTPS. If the HTTPS port is configured, the MobileClient will always attempt to connect through HTTPS. Thus is is sufficient to either specify HTTP or HTTPS port.

Backend configuration

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

Redirect

The MobileClient 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 the MobileClient. 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

The MobileClient 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 the MobileClient 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.

To use an instance banner image you need to provide the path to the image using the imagePath property under bannerImage and an alt text (altText) used as a textual representation of the banner image for screen readers or when the image fails to load. The image used as a banner image must conform the the following rules:

  1. The file type must be .svg, .png, .jpg or .gif (.svg or .png are recommended in this order).
  2. To look good on all screen types the minimum image dimensions must be 256x64px.
  3. The aspect ration must be 4:1.

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.

This option is available since version 2.5.23.

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

This feature requires the Sophora MobileClient in version 2.4.45, 2.5.25 or newer.

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.

MobileClient configuration

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

Tab Configuration

A document in the MobileClient only has two "tabs": One for the input fields (the "Document" tab) and one for the component (the "Component" tab). All input fields a MobileClient user can see and edit have to be defined in one single Sophora tab. This tab can be customized for usage in the MobileClient and does not need to be visible to DeskClient users. This can be achieved by not giving the DeskClient user's role the permission to view the specified tab. Using the supportedTabs parameter, each node type can be tied to an individual tab. The following example shows that the tab with the name mobile is assigned to documents with the story node type while the tab with the name promote will be used for documents with the slideshow node type.

Example
supportedTabs:
  "[sophora-content-nt:story]": mobile
  "[sophora-content-nt:slideshow]": promote

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 MobileClient configuration). If this value is set, a MobileClient 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: http://www.subshell.com/en/sophora/documentation/add-ons/mobileclient/index.html

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
  creatable:
    - primaryType: sophora-content-nt:story
      requiresTemplate: true
    - primaryType: sophora-content-nt:story
    - primaryType: sophora-content-nt:liveReporting
  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 the MobileClient 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.

searchable: 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 way the search results are ordered. By default, results are sorted descending by modification date (sophora:modificationDate descending).

creatable

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.

This configuration option is new with Sophora MobileClient version 2.4.46, 2.5.26 or newer.

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.

This configuration option is new with Sophora MobileClient versions 2.5.34, 3.1.0 or newer.

Default Paragraph Styles

The copytext group allows you to set up your defaultParagraphStyle. In the example above the name of the default paragraph style is paragraph.

Example
copytext:
  defaultParagraphStyle: paragraph

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 the MobileClient'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. A default configuration is used if this option is not defined.

Example
webclient: 
  documentToolbar:
    - id: save
    - id: publish
    - id: offline
    - id: refresh
    - id: preview

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:

  • Property: ctrlKey
  • Value: Whether the ctrl (or ⌘) key need to be pressed together with the key. true or false
  • Default: false
  • Property: shiftKey
  • Value: Whether the shift key needs to be pressed together with the key. true or false
  • Default: false
  • Property: altKey
  • Value: Whether the alt key needs to be pressed together with the key. true or false
  • Default: false

Properties

The following properties can be configured for toolbar actions:

  • Property: id
  • Value: save, publish, offline, refresh, preview, propose or clone
  • Overwrites values for default actions: --
  • Default value: --
  • Property: label
  • Value: The action's label displayed in the MobileClient
  • Overwrites values for default actions: No
  • Default value: Only for default actions
  • Property: tooltip
  • Value: The action's tooltip
  • Overwrites values for default actions: There are no default tooltips
  • Default value: --
  • Property: scriptExternalId
  • Value: The external ID of the client script assigned to this action
  • Overwrites values for default actions: --
  • Default value: --
  • Property: iconName
  • Value: The action's Material Design icon name
  • Overwrites values for default actions: Yes
  • Default value: Only for default actions
  • Property: iconPath
  • Value: The path to a SVG file to be used as an icon. Prioritized over iconName.
  • Overwrites values for default actions: Yes
  • Default value: --
  • Property: canExecuteOnDirtyDocument
  • Value: Determines whether this script can be executed while the document has unsaved changes. true or false
  • Overwrites values for default actions: --
  • Default value: false
  • Property: shortcut
  • Value: The action's shortcut.
  • Overwrites values for default actions: Yes
  • Default value: Only for some default actions

Configuration sets

Configuration sets are used to overwrite parts of the MobileClient's default properties. Configuration sets are identified by a key. It is possible to define multiple sets. The only requirement is an unique key. The content of a configuration set is equivalent to the MobileClient's properties or to a subset of those properties.

Please note that defining a property like documentToolbar will replace the whole property including all child properties.

By default, a configuration set is not active. To access or activate the configuration set in the MobileClient, append the URL parameter ?config={key} to the url, where the key is the configuration set's key defined in the application.yml file.

Currently we only support the following top level property: documentToolbar

This option is available since version 2.5.24 and 2.4.44.
Example
configuration-sets:
	embed:
		documentToolbar:
			- id: save
			  tooltip: Save
			- id: publish
			  tooltip: Publish
			- id: offline 
			  tooltip: Set Offline
 			- id: propose
			  tooltip: Propose

List of Fieldtypes

This lists 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.
  • Text (with Styles): The richtext editor allows you to insert multiline formatted text with support for bold and italic text as well as ordered and unordered lists.
  • Text: Allows you to enter unformatted plain text.
  • Long: A long field type may be one of the following types: Integer, Text or Selection Value. Allows you to enter integers and longs.
  • Double: A douple field type may be one of the following types: Floating-point number or Text. It is recommended to use the input field type Floating-Point Number for properties of the type double. The use of a comma or a period as a delimiter is determined by your language settings of your browser.
  • URL: Used for external urls like https://www.subshell.com.
  • Checkbox: Allows you to check or uncheck a value.
  • 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. As of versions 2.4.44, 2.5.24, 2.6.0 and newer 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.
  • Selection Value: Selection Values such as intelligent, list, list (editable) and tree allow you to choose from one or more predefined values by clicking on the field and selecting the entries shown.
  • 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 the add-on Taxo. Available from versions 2.3.36, 2.4.31, 2.5.8 and newer.
  • 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. This is the MobileClients counter part to the DeskClients image clippings input field.
  • Tags: Allows you to enter tags into a basic text field, separated by spaces. Content assist like in the DeskClient is not supported. Available from versions 2.3.35, 2.4.30, 2.5.7, 2.6.0 and newer.
  • Text (with Teaser Image and Style): Allows you to enter text with styles. The MobileClient 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. Available from versions 2.3.35, 2.4.30, 2.5.7, 2.6.0 and newer.
  • Text (with Teaser Image): Allows you to enter text with styles. The MobileClient 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. Available from versions 2.3.35, 2.4.30, 2.5.7, 2.6.0 and newer.
  • Text (Fixed Size): The MobileClient 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. Available from versions 2.5.23 and newer.

Embedded Mode

What Is The Embedded Mode

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

  • The navigation bar 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.
This mode is only intended to directly open a specific document. It is not possible to open the search page in embedded mode.
The embedded mode requires a MobileClient in version 2.4.42, 2.5.23 or newer.

Using The Embedded Mode

The embedded mode can be enabled by appending the parameter ?embed=true to a document's URL.

Read only Mode

What Is The Read Only Mode?

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

Using The Read Only Mode

Appending the parameter ?readonly=true to a document's URL will open that document in read only mode. If editors open a document in a new tab from a document which is in read only mode, the new document will automatically use this URL parameter.

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

As of MobileClient versions 2.5.24 and 2.4.44 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 the MobileClient need to forward the corresponding HTTP Header (X-XSRF-TOKEN) or else the MobileClient will not be able to work correctly resulting in many 403 (Forbidden) status codes in the frontend.

Further configuration options

The Sophora Mobile Client 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 this article.

Overwriting hostname and port requires the webclient in versions 2.5.29, 3.0 or newer.