Administering the MobileClient

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.

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 
  bannerImage: 
    imagePath: /path/to/image.png 
    altText: Production Instance
  dataDir: data
  maximumSessionsPerUser: 1
  sessionTimeoutInMinutes: 1440
  enableXsrfProtection: true
  enableHsts: true

webclient:
  supportedTabs:		...
  url: 					    ...
  document: 			...
  image: 				    ...

configuration-sets: ...

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 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
    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 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 describes how the MobileClient 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 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.

Banner Image

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.

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.

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 the Sophora Mobile Client to use HSTS by turning on the property backend.enableHsts. This requires the Mobile Client 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 the Mobile Client.

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

Additionally supported input field types

The MobileClient 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'

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

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

search

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

filterOptions: Each of the MobileClient'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

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.

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 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, 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:

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.

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

The optional Sophora action delete and restore can also added to documentToolbar as below.

Example

configuration-sets:
	embed:
		documentToolbar:
			- id: save
			  tooltip: Save
			- id: publish
			  tooltip: Publish
			- id: offline 
			  tooltip: Set Offline
 			- id: propose
			  tooltip: Propose
 			- id: move 			
			  tooltip: Move
 			- id: delete
			  tooltip: Delete
 			- id: restore			 
			  tooltip: Restore

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. The MobileClient supports the regular copytext configuration like allowed paragraph styles and default style.
• 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. 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: 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. 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.
• 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.
• 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.
• 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.
• 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.

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.

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)

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 the Sophora Tools Guide.

Modules

Liveblogs Module

We assume that you have already configured Sophora Liveblogs in the Sophora DeskClient. To configure the Liveblogs module in the MobileClient, you need to add a few lines to the MobileClient's application.yml.

Make Liveblogs Creatable

Make sure that Liveblog documents are creatable. The relevant nodetype is sophora-liveblogs-nt:liveblog (or your own liveblog nodetype). Here is an example configuration:

creatable:
    - primaryType: sophora-content-nt:story
    - primaryType: sophora-liveblogs-nt:liveblog

Liveblog entries can be created directly from the live liveblog view. However you still might want to add your nodetype for liveblog entries to the list.

Make Liveblogs Searchable

Make sure that Liveblog documents are searchable. The relevant nodetype is sophora-liveblogs-nt:liveblog (or your own custom liveblog nodetype). Here is an example configuration:

 search:
  sort: "sophora:modificationDate descending"
  searchable:
    - "sophora-content-nt:story"
    - "sophora-liveblogs-nt:liveblog"
    - "sophora-extension-nt:image"

Liveblog entries can be accessed via the liveblog. You could additionally make them directly searchable as well.

Enable the Scripts for Pins and Top Entries

Marking document entries as top entries or pinning them is controlled by the two client scripts clientscriptdocument-liveblogs-toggle-pinned-entry and clientscriptdocument-liveblogs-toggle-top-entry. The MobileClient will implicitly allow you to use these scripts from the live blog view, which is also the preferred way of controlling top and pinned entries.

Additionally you might want to enable these two scripts for live blog entries as regular document actions. You can add them to the MobileClient's toolbar as shown in the following example:

documentToolbar:
  # (...)   
  - id: script
    label: "Toggle Pin Entry"
    tooltip: "Toggle Pin Entry"
    scriptExternalId: "clientscriptdocument-liveblogs-toggle-pinned-entry"
    supportedNodeTypes:
      - "sophora-content-nt:liveblogEntry"
    iconName: "pin-outline"
    iconData: null
    canExecuteOnDirtyDocument: true
    activeOnUnpublishedDocumentsOnly: false
    shortcut: null
   
  - id: "script"
    label: "Toggle Top Entry"
    tooltip: "Toggle Top Entry"
    scriptExternalId: "clientscriptdocument-liveblogs-toggle-top-entry"
    supportedNodeTypes: 
      - "sophora-content-nt:liveblogEntry"
    iconName: "octagram-outline"
    iconData: null
    canExecuteOnDirtyDocument: true
    activeOnUnpublishedDocumentsOnly: false
    shortcut: null

If you want to be able to use existing scripts in the Liveblog entries, add your Liveblog entry nodetype to the relevant script configurations. Here is an example configuration:

documentToolbar:
  - id: "script"
    label: "Resolve Twitter"
    tooltip: "Resolve Twitter"
    scriptExternalId: "social-media-script-resolve-twitter-urls"
    supportedNodeTypes:
      - "sophora-content-nt:liveblogEntry"
      - "sophora-content-nt:story"
# (...)