Skip to Content

Published

Last modified by Eleni Cojocariu on 2026/08/21 12:18
Show last authors
1 Second part of the review of the administrator [[Exports>>doc:documentation.xs.admin.exports.WebHome]] topic against [[Documentation.AdminGuide.ImportExport>>doc:Documentation.AdminGuide.ImportExport]] revision 35.1 and against the platform sources at 18.7.0-SNAPSHOT. The first part is the change request "Fix the PDF export and XAR export URL documentation of the Exports topic"; this one covers the two office server How-tos, which needed a restructure rather than an edit.
2
3 **The duplication that forced the restructure.** Connect to an Internal Office Server and Connect to an External Office Server carried:
4
5 * the **same 40-line ##xwiki.properties## block**, quoted verbatim on both, although each page only sets two or three of those properties;
6 * the **same two opening steps**, "Install LibreOffice or OpenOffice" and "Navigate to xwiki/WEB-INF/ and open xwiki.properties";
7 * **six FAQ entries each**, four of them identical on both pages. Both pages already carry an automatic "There are more than 5 FAQ entries" warning recorded by the documentation checker.
8
9 **A new Reference page, "Office Server Properties"**, holds what the two How-tos shared: where the properties live and that each one ships commented out, the ten ##openoffice.## and ##officeimporter.presentation.## properties as a table with their defaults and which server type each applies to, the typical installation and profile directories per operating system, and the questions that were asked on both pages. It is a visible sibling page rather than a hidden fragment, so a reader configuring an office server can read the whole property set in one place. Its directory table carries an ##id## macro, so the two How-tos link the anchor and the link survives a heading rename.
10
11 **Each How-to keeps only its own procedure**, and both end on the result step they already had a screenshot for: the "Office Server" administration section reporting the server connected.
12
13 **Five things the pages stated that the sources do not support.** Read from ##OfficeServerConfiguration##, ##DefaultOfficeServerConfiguration##, ##DefaultOfficeServer##, ##xwiki.properties.vm## and ##XWiki.OfficeImporterAdmin##:
14
15 * **An externally managed server ignores ##openoffice.homePath## and ##openoffice.profilePath##.** ##DefaultOfficeServer## gives its external branch only the port numbers and ##connectOnStart##, so the step that told the reader to set the profile path for an externally managed server had no effect. The replacement passes the profile to the office process itself, with its ##UserInstallation## option, which is what actually works when the server environment will not let the office suite create a profile.
16 * **The ##program## subdirectory is appended on every operating system, not only on Microsoft Windows.** The FAQ entry said Windows. The conversion library looks for ##program/soffice.bin##, ##program/soffice.exe##, ##program/soffice## or ##MacOS/soffice## inside ##homePath## depending on the platform, and reports that the directory does not contain ##soffice.bin## when the path already ends in ##program##. Checked in ##jodconverter-local## 4.4.11, the version shipped in 18.4.3.
17 * **##openoffice.serverPorts## supersedes the deprecated ##openoffice.serverPort##**, and the two server types use the list differently: an internally managed server starts one office process per port, an externally managed one is only reached on the first port. Neither page said so.
18 * **##openoffice.serverType## has a third value that does not work.** ##2##, "Externally managed (remote)", exists on the component role and even has an administration label, but ##DefaultOfficeServer## handles only ##0## and ##1## and sends anything else to the "Invalid Configuration" state. The new page therefore says that only ##0## and ##1## are supported, without advertising a value that cannot be used.
19 * **##openoffice.homePath## is resolved in three steps**, the property, then the ##XWIKI_OFFICE_HOME## environment variable, then the library detecting the installation, which is why the page describes its default as "the installation XWiki detects" rather than quoting a path.
20
21 The administration labels are now quoted as they are shipped, "Server type", "Server state", and the actions each server type offers, and the pages say what that section can and cannot do: it starts, stops or reconnects the server, it does not change the configuration. The command line for an externally managed server was run for real against LibreOffice 24.2.7.2 and checked to be listening on the configured port.
22
23 **Obsolete examples replaced.** OpenOffice 3, LibreOffice 3.4, Ubuntu 10.04, Windows XP, Vista and 7, and the 32-bit against 64-bit split, all from 2011 or earlier, become one three-row table of installation and profile directories. The **property names and the shipped defaults are left alone**, including ##/opt/openoffice.org3/##, because that is still what ##xwiki.properties## ships. The Linux row was checked on a machine running LibreOffice 24.2; the Microsoft Windows and macOS rows are the standard LibreOffice 4 and later locations and were not checked here.
24
25 **No FAQ entry is dropped.** The seven distinct questions the two pages asked all have a home: the four shared ones and the internal against external comparison move to Office Server Properties, the ##program## question and the profile path version move to the internal How-to, and "when is an externally managed server useful" stays on the external one. Two of the seven change their answer rather than their wording: the ##program## entry because it was wrong about Windows, and "how should I adapt the example paths to my version", whose version-numbered examples are gone, so what remains of it is answered where the reader now meets a version number, why a profile directory ends in ##4## when the product is version 24.
26
27 **Mechanical.** The Technical ID is prefixed on both How-tos and set on the new page, without which the Extension badge at the bottom of the page does not resolve. "Related pages" was empty on the internal How-to. The two links to the office suite home pages are now https.
28
29 **Deliberately not in this change request:**
30
31 * **The hub link.** "Office Server Properties" is a new child of the Exports hub, and a topic page must name and link every page it introduces, but that hub is a file change of the first change request. Branching it from the live version here would revert that rewrite, so the link is a small follow-up once the first change request is merged.
32 * **The "does exporting replace a proper backup?" FAQ entry**, which is verbatim on three hubs, administrator Exports, user Exports and Imports. Giving it one home spans three trees.
33 * **The Imports topic**, where "Customize a XAR File" has the same missing Technical ID and missing result step. It is a sibling topic, not this one.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected