Easily deploy organisational-wide settings, dictionaries, auto-text and more, and enable users to personalise their document editing for greater efficiency.
Server-side Settings is a low-effort, extra hook for integrators that enables many settings options for both users and sysadmins. Centrally managed by the sysadmin, Server-side Settings make it easy to deploy consistent, organisation-wide settings, such as custom dictionaries, role-specific autotext (which are pre-defined text blocks added to documents with a short-cut), company document themes, document signing, extensions and AI assistance (which is off by default).
Built for Integrators #
Server-side Settings was developed with our integration partners in mind. This method avoids the issues associated with storing settings in the browser, where settings can be lost on browser refresh, browser switching and reinstalls, and where a local storage solution cannot handle cross-device syncing.
WOPI-based Settings API #
To make many settings easily accessible to both users and admins, Collabora Productivity developed a WOPI-based Settings API, which enables partners to integrate a host of Server-side Settings options for office documents smoothly and directly into their own platform. In the same way that the integrator owns document storage as a WOPI host, they also own Settings storage, saving them in the relevant file formats, such as .bua, .dic, .json, .theme and xcu. To understand how Collabora’s WOPI-like protocol works read this guide.
Step by Step: How User Settings Load
Settings are initially loaded, when a browser opens a document. CheckFileInfo advertises two URIs: SharedSettings (which is the admin’s settings applied across an organisation and/or per tenant) and UserSettings (which holds per user settings only), see diagram, below.
- coolwsd (the WOPI client) initiates a CheckFileInfo request to the integrator’s WOPI host the host returns a configuration JSON to coolwsd.
- coolwsd sends the relevant UserSettings URI to the WOPI Host.
- WOPI Host sends a response and coolwsd requests the various Settings files, such as .bua, .dic and so on, and sends the settings onto the browser (and the iframe) via WebSocket.
When UserSettings need updating, the browser updates its caches and queues a ‘settings change’ event. Using the WebSocket, the browser sends the new JSON file to coolwsd and once coolwsd validates the file, it is sent on to the WOPI host. Coolwsd also sends the update onwards to any active browser sessions for the same user.
Settings files are addressed with a structured path: /settings/{TYPE}/{CATEGORY}/{NAME}.{EXT} where {TYPE} is the scope:
- systemconfig — admin/system-wide presets applied to everyone
- userconfig — per-user preferences
Server-side Settings are embedded in iframes, making them easy to access and alter by both an organisation’s administrators and users. There are two ways for users to access their personal setting iframe: inside the document editor itself via File > Options dialog, or through on the partner platform via Profile > Personal Settings > Office. Current supported Server-side Setting categories for users are listed, below and we will cover each one in detail:
- Interface Settings
- Document Settings
- Zoom Behaviour
- AI Assistant
- Autotext
- Custom Dictionaries
- Document Themes
- Extensions
- Document Signing
- Zotero Integration
The panel for administrator’s Server-side Settings is located in Administration Settings > Office on the partner platform. These options focus on shared settings, such as Document Settings, shared Autotext snippets, shared group or organisation-wide Custom Dictionaries, Document Themes and Extensions. It does not include elements that an individual may select for themselves, such as Interface Settings (e.g., where a user can choose to turn on Automatic Spell Checking or a Dark Mode), AI Assistant, Document Signing and Zotero integration.
Coolwsd Configuration Settings #
In addition to the Server-side Settings in the UI, which are stored on the WOPI Host, the administrator has access to server configuration settings for coolwsd stored in file coolwsd.xml, where features can be centrally activated, disabled and enforced across a Collabora Online instance. The configuration settings in the coolwsd.xml are enforced regardless of a user’s Personal Settings (userconfig). As per the Settings Examples diagram, below, this includes, for example, access to AI, and selecting Notebookbar or Compact as the default view.
Server-side Settings Categories #
While there are many Server-side Settings that are visible in the UI now—and they are constantly being updated and improved—some settings require an integrator add-on to include them as UI options, for example, restricting usage, editing or commenting to specified user groups, enabling access to external apps via WOPI requests, Custom Fonts and Global Templates. You can find out more about this in the Collabora Online Integration SDK.
Now let’s dive in and take a closer look at the different Settings categories and the advantages Server-side Settings can provide to administrators.
Interface Settings #
Options in Interface Settings eliminates many ‘first-thing’ setting tweaks and common IT support calls for administrators. Users can customise their document editor, which will persist across sessions, all devices and browsers, e.g., they can choose from the NotebookBar (Tabbed) or Compact View for all devices at once.
Other user interface options include, turning on Dark Mode (Light Mode is the default), setting Zoom to a default size or using Smart Zoom (which will fit an opened document to the viewpoint width) and smooth scrolling. There are a host of interface options for each application, dictating whether UI elements are visible or not, such as the Navigator, Sidebar and Comments. For Accessibility requirements, users can turn on an in-document Screen Reader, such as NVDA on Windows, ORCA on Linux or VoiceOver on Mac, (once Accessibility features are activated by an admin in the coolwsd.xml file), and enforce the Accessibility Checker in each application.
Document Settings
By controlling how documents are set up and handled, Collabora Online’s user experience stays consistent with professionally-configured software that meets your organisation’s requirements automatically. It also avoids creeping changes, ensuring your training and documentation can be relied on for all user onboarding.
Both users and administrators can choose from an array of default Document Settings, presented in a simple-to-use matrix that covers each application (Writer, Calc, Impress and Draw). For example, in Calc, users have a Show Grid option and Print settings for pages, such as whether to Print Empty Pages, All Sheets and Force Breaks options. Administrators have additional Grid behaviour options in Calc, such as Snap to Grid and Synchronize Axes.
Zoom Behaviour
A user can set Zoom Behaviour via File > Options in the document editor or via the Administration Settings > Office (pictured below). When the first checkbox is enabled, the user hands zoom behaviour control to the settings specified by the administrator in coolwsd.xml. When the checkbox is disabled, the second checkbox is enabled along with the dropdown menu, where a user can activate Smart Zoom and specify the default zoom.
AI Assistant
Collabora Online uses an AI Integration path that runs inside the editing session via WebSocket through an AI Chat Sidebar (which opens on the right-hand side of a document). AI is turned off by default in coolwsd.xml. and must be enabled by an administrator. (Read the AI Assistant section SDK for more details.
Where administrators want to centrally control and configure the AI API, they can choose to supply the AI credentials via WOPI UserPrivateInfo and the integrator-supplied defaults in CheckFileInfo or configure AI once for all users in coolwsd.xml in the block. Once activated, all users on a Collabora Online instance gain AI features without needing to configure them individually. Read the AI Assistant section in the SDK for more details, and our AI features in CODE 26.04 blog to discover all AI-powered assistance in Writer, Calc and Impress.
Once activated and permitted by the administrator, a user’s AI Assistant can either be set-up via File > Options or through their Personal Settings > Office panel on the partner platform.
AI provider credentials are defined for text generation and image generation separately or both generators can use the same provider. Configuration simply requires selecting from a dropdown menu of AI providers, which are currently:
- OpenAI
- Groq
- Together AI
- Mistral AI
- Custom OpenAI compatible (including, for instance, local/self-hosted models (Ollama, vLLM and LM Studio).
Once an AI provider is selected and an API key is added, Collabora Online queries the end server for a list of models for the specific provider and the user can select one from a dropdown menu. For document actions (inspecting and editing), Collabora Online recommends choosing a model with native function/tool calling, such as gpt-4o, llama3.1, or qwen2.5, butusers should also bear in mind to choose the most stable models available, not simply the latest model. Where a model does not have function / tool calling (e.g., base llama3, gemma), users can still chat with AI but cannot access document tools, for example, to transform a document based on a user prompt.
If the Image generation is set to ‘Same as text AI’, then it’s a case of selecting a ‘Model’ from the dropdown menu as no API key is required the second time. If another AI provider for image generation is preferred then the user can chose from the list as before. Next, image sizes can be specified, defaulting to 1024 x 1024 pixels.
The final step is to set the request timeout (seconds), which defaults to 300 seconds. This provides LLMs with enough time to process heavy system prompts, execute complex reasoning tasks, and prevent premature connection terminations while supplying a sufficient enough delay for models to fail smoothly if a server outage happens.
Watch our guides to the AI assistance features now available in:
When activated, AI assistant provides troubleshooting formula errors in Calc, formula validation (in a sandbox), sanity checking for anomalies, outliers and inconsistencies, batch formula insertions and more.
Writer’s AI-powered assistance includes text suggestions, improvements, and other writing-oriented workflows, and the AI assistance in Impress includes help with verifying and summarising information, converting paragraphs into presentable bullet points, and turning ideas into clearer presentation content that is easier to shape into slides.
AutoText – F3 Completion
AutoText enables users and admins to save predefined text blocks, for use by the individual user or shared across the organisation. These reusable text snippets are uploaded as an AutoText element file (.bau), which need to be prepared externally in Collabora Office Classic.
Watch our video guide to AutoText
An Autotext is created by highlighting text in a document, choosing Tools > Autotext. Once a new dialog box appears, you must give the Autotext a shortname, choose a shortcut key and select or create a new category for the Autotext. Clicking the Autotext dropdown menu at the bottom of the dialog box provides the option to create a new Autotext, which is saved into a file. You can change the file path with the ‘Path..’ button, by default Autotext entries in Collabora Office Classic are saved into /opt/collaboraoffice/program/../share/autotext/common, which can be uploaded by users or administrators.
Once set up, an Autotext is inserted instantly by typing the shortcut or phrase, followed by the F3 key. This feature is ideal for professional use cases where repetitive writing tasks are common, such as healthcare, legal services, customer service and academia, and can now be deployed across your entire organisation offering harmonised configurations and tools that can be utilised by the entire workforce through standard training.
Custom Dictionaries
At Collabora Productivity, we know that central deployment of custom dictionaries to end-user’s browsers can be challenging, but we also know every industry has its own collection of unique terms, words and names that need to be catered for. This industry jargon appears in documents as annoying red underlines. Instead of wrestling with tools like OpenText ZENWorks or modifying registries underneath Tivoli Access Manager to configure hundreds of Windows end-points, admins can upload a Custom Dictionary (.dic) file that will eliminate false spell-cote. heck errors for good across your organisation.
How to Create a Custom Dictionary
Initially, a .dic file is created using Collabora Office Classic, but once uploaded, any new words that are red-lined can be added to dictionary by right-clicking and selecting ‘Add to Dictionary’. To create a new dictionary, choose Tools > Options and in User-defined Dictionaries select ‘New’. Finish the process by giving the custom dictionary (or ‘Book’) a name and either select ‘All’ or a language from the dropdown list.
The newly created .dic files are found here:
- Linux: ~/.config/libreoffice/4/user/wordbook/
- Windows: %APPDATA%\LibreOffice\4\user\wordbook
- macOS: ~/Library/Application Support/LibreOffice/4/user/wordbook/
Server-side Settings enables users to upload custom dictionaries alongside any organisation-wide dictionaries that an administrator wishes to create, saving time for everyone. Users can upload a .dic via File > Option > Custom dictionaries or Profile > Person Settings > Office pictured below.
Document Themes
Collabora Online ships a number of built-in document themes. Again, both administrators and users can add custom themes. Users can achieve this through through Format > Theme > Add and selecting colours and accents from a series of palettes. Alternatively, an administrator can add custom themes using a small XML with the .theme extension using the following format:
<?xml version="1.0" encoding="UTF-8"?><theme name="MyTheme"><theme-colors name="MyTheme"><color name="dark1" color="#1c1c1c" /><color name="light1" color="#ffffff" /><color name="dark2" color="#262626" /><color name="light2" color="#f2f2f2" /><color name="accent1" color="#2a6099" /><color name="accent2" color="#7eaf16" /><color name="accent3" color="#bf7600" /><color name="accent4" color="#a90000" /><color name="accent5" color="#592e8b" /><color name="accent6" color="#0095bb" /><color name="hyperlink" color="#0066cc" /><color name="followed-hyperlink" color="#996600" /></theme-colors></theme>
Collabora Online persists user or admin-supplied themes across editing sessions, and stores .theme files on the WOPI Host.
Extensions – Experimental and Under Active Development
Collabora has developed an extension framework, enabling administrators to add iframe-hosted extensions to the document editor. Again, these can be uploaded per-user through File > Options from the document editor or administrators can upload them through the Administration panel in the integrated partner platform.
Extensions need to be packaged as ZIP files and are subsequently unpacked on the coolwsd server. Each extension ZIP is comprised of three files:
- icon.svg – which is either displayed in the Extensions tab row in notebookbar view or listed in the Extensions submenu in the menubar in Compact View.
- manifest.json – currently, provides details of the extension’s name, the entry HTML file name that will be rendered in the extension iframe, icon file name, version number and indicates which apps the extension supports (so it will only run in those apps).
- Index.html – holds the extension script itself, which the user activates in the document editor by clicking an extension icon or selecting it from a submenu.
Activating an extension opens a foldable sidebar panel (extension iframe) on the right-hand side of the document, which sits above any core sidebar deck that’s open (such as Styles and Properties). The sidebar panel embeds the entry HTML into a sandboxed iframe. The full browser surface is available for the iframe for use with, for example, React, fetch and IndexedDB, but remains isolated from the document’s own JavaScript.
For an extension to be able to interact with a document, Collabora Online uses cool.js, a messaging helper. For a more detailed explanation on how this works read our Developer blog: Extending Collabora Online with iframe-hosted extensions.
Document Signing
Collabora Online’s Document Signing enables integrators to support user signing inside the document workflow, which avoids having to send an organisation’s most sensitive documents to a third-party signing service, as well as the need for an additional storage layer (which could also raise digital sovereignty issues depending on where documents are stored).
Document Signing is available to setup for users via File > Options and Personal Settings by pasting a PEM certificate, private key and a CA chain into the relevant fields (pictured, below). The details are stored in UserPrivateInfo on the WOPI Host and are confirmed fresh for each session.
Note: Collabora Online’s Qualified Electronic Signing is a separate feature, which is for PDF files. It is provided in partnership with eID Easy and a recognised form of e-signature under EU law. Electronic Signing is per-server integrations credientials and they are stored in ServerPrivateInfo and different from per-user settings.
Zotero Integration
Zotero is an open-source reference management software. Once linked to a user account, Collabora Online can browse all the existing records in an account’s Zotero library, enabling users to insert, remove, and refresh references, citations, and notes or to automatically generate bibliographies. This makes Collabora Online an excellent solution for research and academia alike, as well as an ideal option when working with Zotero research assistant.
Users can create or edit their API keys by logging into zotero.org and heading to Zotero account API settings. Users can specify an API key through File > Options > Zotero in the document editor or through their Personal Settings panel accessed through their profile on the partner platform.
Integrate Today! #
As you can see, Server-side Settings provides extensive customisation options to users and administrator’s seekingfaster and better platform control. Ready to transform your document collaboration from generic to genuinely professional? You can see Server-side Settings working in Collabora Online in our free demo, or you can explore our SDK documentation to quickly add custom settings into your platform.
If you need more advice, contact our engineering sales team today.