Published
Restructure the office server How-tos of the Exports topic around a shared properties reference
Last modified by Eleni Cojocariu on 2026/08/21 12:18
Preview the image
Second part of the review of the administrator Exports topic against 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.
The duplication that forced the restructure. Connect to an Internal Office Server and Connect to an External Office Server carried:
- the same 40-line xwiki.properties block, quoted verbatim on both, although each page only sets two or three of those properties;
- the same two opening steps, "Install LibreOffice or OpenOffice" and "Navigate to xwiki/WEB-INF/ and open xwiki.properties";
- 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.
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.
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.
Five things the pages stated that the sources do not support. Read from OfficeServerConfiguration, DefaultOfficeServerConfiguration, DefaultOfficeServer, xwiki.properties.vm and XWiki.OfficeImporterAdmin:
- 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.
- 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.
- 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.
- 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.
- 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.
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.
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.
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.
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.
Deliberately not in this change request:
- 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.
- 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.
- 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.
-
Eleni Cojocariu created this Change Request with changes for Connect to an Internal Office Server
2 months ago
-
Eleni Cojocariu added a new change for Connect to an External Office Server
2 months ago
-
Eleni Cojocariu added a new change for Office Server Properties
2 months ago
-
Eleni Cojocariu added a new approval review
2 months ago
-
Eleni Cojocariu changed the status of the Change Request from ready for review
to ready for publication
2 months ago
-
Eleni Cojocariu changed the status of the Change Request from ready for publication
to published
2 months ago
All changes
Summary
-
Page properties (5 modified, 0 added, 0 removed)
-
Attachments (0 modified, 1 added, 0 removed)
-
Objects (0 modified, 3 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Connect to an Internal Office Server - Parent
-
... ... @@ -1,0 +1,1 @@ 1 +documentation.xs.admin.exports.WebHome - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,10 @@ 1 +An internally managed office server is an office process that XWiki starts and stops itself; to connect to one you run yourself, [[connect to an external Office Server>>documentation.xs.admin.exports.connect-external-office-server.WebHome]] instead. To connect your wiki to an internally managed office server: 2 + 3 +1. Install [[LibreOffice>>https://www.libreoffice.org/]] or [[OpenOffice>>https://www.openoffice.org/]] on the server that runs XWiki. 4 +1. Open ##xwiki/WEB-INF/xwiki.properties## in a text editor and find the [[office server properties>>documentation.xs.admin.exports.office-server-properties.WebHome]]. 5 +1. Uncomment ##openoffice.autoStart## and set it to ##true##. 6 +1. Uncomment ##openoffice.homePath## and ##openoffice.profilePath## and set them to the [[installation and profile directories>>documentation.xs.admin.exports.office-server-properties.WebHome||anchor="office-paths"]] of the office suite you installed. 7 +1. Save the file and restart XWiki. 8 +1. [[Administer the wiki>>documentation.xs.admin.base.content-organization.administer-wiki.WebHome]], select "Content" and then "Office Server". The "Server type" reads "Internally managed (local)" and the "Server state" reads "Connected":((( 9 +{{image reference="office-server-internally.png" size="large" alt="The Office Server administration section reporting an internally managed server in the Connected state"/}} 10 +)))
- office-server-internally.png
-
- Author
-
... ... @@ -1,0 +1,1 @@ 1 +XWiki.elenicojocariu - Size
-
... ... @@ -1,0 +1,1 @@ 1 +44.1 KB - Content
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,15 @@ 1 +== Can I start and stop the office server without restarting XWiki? == 2 + 3 +Yes, the "Office Server" administration section offers "Start server (connect)", "Stop server (disconnect)" and "Restart server" for an internally managed server. 4 + 5 +== Why does the server state stay "Not Connected" after XWiki restarts? == 6 + 7 +With ##openoffice.autoStart## left at its default of ##false##, XWiki does not start the office server on its own: start it from the "Office Server" administration section, or set the property to ##true##. 8 + 9 +== Why must ##openoffice.homePath## stop at the installation directory? == 10 + 11 +Because the office executable is looked up //inside// it: the conversion library appends ##program/soffice.bin## on Linux, ##program/soffice.exe## on Microsoft Windows and ##program/soffice## or ##MacOS/soffice## on macOS. A ##homePath## that already ends in ##program## therefore fails, reporting that the directory does not contain ##soffice.bin##. This holds on every operating system, not only on Microsoft Windows. 12 + 13 +== My office suite is version 24, so why does its profile path end in ##4##? == 14 + 15 +That ##4## is the profile format version, which has not changed since LibreOffice 4, and not the product version. LibreOffice 24.2 still keeps its profile in ##.config/libreoffice/4##. - Related
-
... ... @@ -1,0 +1,4 @@ 1 +* [[Connect to an External Office Server>>documentation.xs.admin.exports.connect-external-office-server.WebHome]]. 2 +* [[Office Server Properties>>documentation.xs.admin.exports.office-server-properties.WebHome]]. 3 +* [[Import Office Documents into Wiki Pages>>documentation.xs.user.base.page.create.import-office-documents.WebHome]]. 4 +* [[Export a Page in ODT or RTF Formats>>documentation.xs.user.exports.export-page.export-odt-rtf.WebHome]]. - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +howto
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-office-ui
- DocApp.Code.DocumentationViolationClass[0]
-
- Violation Message
-
... ... @@ -1,0 +1,1 @@ 1 +There are more than 5 FAQ entries in this page. This probably indicates that some documentation pages should be added. - Severity
-
... ... @@ -1,0 +1,1 @@ 1 +Warning
Summary
-
Page properties (5 modified, 0 added, 0 removed)
-
Attachments (0 modified, 1 added, 0 removed)
-
Objects (0 modified, 3 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Connect to an External Office Server - Parent
-
... ... @@ -1,0 +1,1 @@ 1 +documentation.xs.admin.exports.WebHome - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,17 @@ 1 +An externally managed office server is an office process you start and stop yourself, which XWiki only connects to, so its startup parameters and its lifetime are yours to control; to have XWiki manage the process instead, [[connect to an internal Office Server>>documentation.xs.admin.exports.connect-internal-office-server.WebHome]]. To connect your wiki to an externally managed office server: 2 + 3 +1. Install [[LibreOffice>>https://www.libreoffice.org/]] or [[OpenOffice>>https://www.openoffice.org/]] on the server that runs XWiki. 4 +1. Open ##xwiki/WEB-INF/xwiki.properties## in a text editor and find the [[office server properties>>documentation.xs.admin.exports.office-server-properties.WebHome]]. 5 +1. Uncomment ##openoffice.serverType## and set it to ##1##. Leave ##openoffice.homePath## and ##openoffice.profilePath## commented out, since an externally managed server ignores them. 6 +1. Save the file and restart XWiki. 7 +1. Start the office server in headless mode, on the first of the ports set in ##openoffice.serverPorts##:((( 8 +{{code language="none"}} 9 +soffice --headless --accept="socket,host=127.0.0.1,port=8100;urp;" --nofirststartwizard 10 +{{/code}} 11 + 12 +where ##soffice## is the office suite executable, for example ##C:/Program Files/LibreOffice/program/soffice.exe## on Microsoft Windows. 13 +))) 14 +1. [[Administer the wiki>>documentation.xs.admin.base.content-organization.administer-wiki.WebHome]], select "Content" and then "Office Server", and click "Connect". 15 +1. Check that the "Server type" reads "Externally managed (local)" and the "Server state" reads "Connected":((( 16 +{{image reference="office-server-externally.png" size="large" alt="The Office Server administration section reporting an externally managed server in the Connected state"/}} 17 +)))
- office-server-externally.png
-
- Author
-
... ... @@ -1,0 +1,1 @@ 1 +XWiki.elenicojocariu - Size
-
... ... @@ -1,0 +1,1 @@ 1 +36.7 KB - Content
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,11 @@ 1 +== When is an externally managed office server the better choice? == 2 + 3 +When you need to control the office process's startup parameters, or to manage its lifetime separately from XWiki's, for example to run it under its own service manager. 4 + 5 +== The server environment does not let the office suite create its user profile. What can I do? == 6 + 7 +Prepare the profile directory on another machine, copy it to the server running XWiki, and pass it to the office process with ##-env:UserInstallation=file:///path/to/profile##. The ##openoffice.profilePath## property has no effect on an externally managed server. 8 + 9 +== Can XWiki start the external office server for me? == 10 + 11 +No. With ##openoffice.serverType## set to ##1##, the "Office Server" administration section only offers "Connect" and "Disconnect": starting and stopping the process itself is yours to do. - Related
-
... ... @@ -1,0 +1,4 @@ 1 +* [[Connect to an Internal Office Server>>documentation.xs.admin.exports.connect-internal-office-server.WebHome]]. 2 +* [[Office Server Properties>>documentation.xs.admin.exports.office-server-properties.WebHome]]. 3 +* [[Office Importer installation notes for Fedora>>extensions:Extension.Office Importer Application Linux]]. 4 +* [[Export a Page in ODT or RTF Formats>>documentation.xs.user.exports.export-page.export-odt-rtf.WebHome]]. - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +howto
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-office-ui
- DocApp.Code.DocumentationViolationClass[0]
-
- Violation Message
-
... ... @@ -1,0 +1,1 @@ 1 +There are more than 5 FAQ entries in this page. This probably indicates that some documentation pages should be added. - Severity
-
... ... @@ -1,0 +1,1 @@ 1 +Warning
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Office Server Properties - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,26 @@ 1 +The office server that converts documents for the [[Office Importer>>extensions:Extension.Office Importer Application.WebHome]] and produces the [[ODT and RTF exports>>documentation.xs.user.exports.export-page.export-odt-rtf.WebHome]] is configured in ##xwiki/WEB-INF/xwiki.properties##, in the section "Settings for the OpenOffice server instance consumed by the OfficeImporter component". Every property there ships commented out, showing its default value, so a property only takes effect once its line is uncommented. The ##openoffice.## prefix is historical: the same properties configure a LibreOffice installation. 2 + 3 +|=Property|=Default|=Description 4 +|##openoffice.serverType##|##0##|##0## for a server XWiki starts and stops itself, see [[Connect to an Internal Office Server>>documentation.xs.admin.exports.connect-internal-office-server.WebHome]]. ##1## for a server you start yourself, see [[Connect to an External Office Server>>documentation.xs.admin.exports.connect-external-office-server.WebHome]]. Any other value leaves the office server unusable, reporting the state "Invalid Configuration". 5 +|##openoffice.serverPorts##|##8100,8101##|The ports used to reach the office server. An internally managed server starts one office process per port; an externally managed one is only reached on the first port of the list. 6 +|##openoffice.autoStart##|##false##|##true## to have XWiki start, or connect to, the office server when it starts up, instead of leaving that to the "Office Server" administration section. 7 +|##openoffice.homePath##|the installation XWiki detects|The directory the office suite is installed in. Set it to the installation directory itself, not to its ##program## subdirectory. Used by an internally managed server only. 8 +|##openoffice.profilePath##|the profile the office suite computes|The office user profile directory the server runs with. Used by an internally managed server only. 9 +|##openoffice.maxTasksPerProcess##|##50##|The number of conversions one office process handles before it is recycled. Used by an internally managed server only. 10 +|##openoffice.taskExecutionTimeout##|##60000##|The time, in milliseconds, a single conversion may take before it is abandoned. Used by an internally managed server only. 11 +|##officeimporter.presentation.imageFormat##|##jpg##|The image format the slides of an imported presentation are converted to. 12 +|##officeimporter.presentation.quality##|##95##|The quality of those images, from ##0## to ##100##. It overrides any filter configured for HTML presentations in ##custom-document-formats.json##, and it is ignored when the image format is ##png##. 13 +|##officeimporter.presentation.slideWidth##|##1920##|The width, in pixels, of those images. 14 + 15 +When ##openoffice.homePath## is left unset, XWiki reads the ##XWIKI_OFFICE_HOME## environment variable, and falls back to detecting the installation itself. 16 + 17 +{{id name="office-paths"/}} 18 + 19 +== Typical Office Installation Directories == 20 + 21 +|=Operating system|=##openoffice.homePath##|=##openoffice.profilePath## 22 +|Linux|##/usr/lib/libreoffice##|##/home/{user}/.config/libreoffice/4## 23 +|Microsoft Windows|##C:/Program Files/LibreOffice##|##C:/Users/{user}/AppData/Roaming/LibreOffice/4## 24 +|macOS|##/Applications/LibreOffice.app/Contents##|##/Users/{user}/Library/Application Support/LibreOffice/4## 25 + 26 +On Fedora, see the [[Office Importer installation notes>>extensions:Extension.Office Importer Application Linux]].
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,19 @@ 1 +== Do I need to install the Office Importer application in XWiki? == 2 + 3 +No, the [[Office Importer application>>extensions:Extension.Office Importer Application.WebHome]] comes pre-bundled, so no manual installation is required. 4 + 5 +== How does the Office Importer convert a document? == 6 + 7 +It hands the document to the running office server, which converts it to HTML, and then transforms that HTML into XWiki syntax. This is what lets office files such as ##DOCX## and ##XLSX## be imported and displayed in XWiki. 8 + 9 +== Why set ##homePath## and ##profilePath## by hand rather than let XWiki work them out? == 10 + 11 +The computed values are derived from the operating environment and are not accurate on every system, so setting both explicitly avoids an office server that fails to start for no visible reason. 12 + 13 +== Do these properties take effect without restarting XWiki? == 14 + 15 +No, ##xwiki.properties## is read when XWiki starts. The "Office Server" administration section can start, stop or reconnect the server, but it cannot change these values. 16 + 17 +== What is the difference between an internally and an externally managed office server? == 18 + 19 +Internally managed, ##openoffice.serverType## ##0##, means XWiki starts and stops the office process itself. Externally managed, ##openoffice.serverType## ##1##, means you start the process and XWiki only connects to it, which is what you want when its startup parameters or its lifetime have to be yours to control. - Related
-
... ... @@ -1,0 +1,4 @@ 1 +* [[Connect to an Internal Office Server>>documentation.xs.admin.exports.connect-internal-office-server.WebHome]]. 2 +* [[Connect to an External Office Server>>documentation.xs.admin.exports.connect-external-office-server.WebHome]]. 3 +* [[Import Office Documents into Wiki Pages>>documentation.xs.user.base.page.create.import-office-documents.WebHome]]. 4 +* [[Export a Page in ODT or RTF Formats>>documentation.xs.user.exports.export-page.export-odt-rtf.WebHome]]. - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +reference
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-office-ui
Aug 21, 2026, 12:18:30 PM
Approved by Eleni Cojocariu
Approvers
Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.
