XWiki and ONLYOFFICE document editing

The core thing to understand is that XWiki never renders the office editor itself. When a user opens a Word, Excel or PowerPoint attachment, the OnlyOffice Connector in XWiki prepares a request for the attachment and hands the document to the OnlyOffice Document Server. The Document Server then serves the editor to the browser, and the edits made in that session are sent back to XWiki through the connector. Each step has a different owner, and each one needs to be planned in your infrastructure before users depend on it.

Browser to Document Server. The editor's JavaScript, and the live co-editing traffic that follows, come from the Document Server, not from XWiki. That means the user's browser must be able to reach the Document Server's public or internal address directly. A design that works from the XWiki server but blocks the browser from reaching the Document Server will appear to load XWiki correctly and then fail when the editor opens. Confirm the address the browser will use, the DNS name behind it and any proxy or firewall rules between the user network and the Document Server before testing with real attachments.

XWiki to Document Server. The connector also needs to reach the Document Server from the XWiki side, for example to request the document conversion and to pass the document location. The address XWiki uses for the Document Server can differ from the address the browser uses, particularly when the two sit on different networks or behind different load balancers. Keep these two addresses in your configuration plan as separate items, and check the cross-origin settings on the Document Server, which the connector documentation for the installed version describes as a prerequisite.

Save path and ownership. When an editing session ends or autosaves, the Document Server sends the updated file back through the connector, and XWiki stores it as a new version of the attachment. XWiki remains the system of record for the attachment, its version history, its page location and the permissions that decide who can open it. The Document Server holds the document only while a session is active. That split matters for backup and retention: back up the XWiki database and attachment storage as the authoritative copy, and treat Document Server working data as transient.

What to confirm before you build. The exact handshake, the request fields, and any JWT signing or shared secret settings differ between connector and Document Server versions. Do not assume a signing setup is optional or that a default secret is acceptable. Read the connector documentation for the XWiki version you plan to install, confirm the supported Document Server range (the connector has been tested with Document Server 8.2 through 9.0.4 and needs XWiki 15.10 or later), and verify the request flow in a staging environment that uses the same hostnames and TLS setup as production.

The XWiki OnlyOffice Connector edits .docx, .xlsx, .pptx, .odt, .ods and .odp attachments natively. It can also convert legacy .doc, .xls and .ppt files so they can be edited. For your team, the first decision is which of these two paths each attachment type will take, and whether your users accept editing a converted copy rather than the file they uploaded. Confirm the exact behavior with the connector documentation on the XWiki Store before you write this into a standard.

Conversion changes what is edited. The connector works on a converted copy, so the original attachment is not the file people change during a session. Ask the vendor and test in your own environment how the original is kept, how the converted copy is saved back, whether attachment version history is retained, and what happens when two people open the same file. Those answers determine the access rules, retention settings and user guidance you need to write before rollout.

Fidelity is the second risk. Legacy binary formats often show differences in layout, fonts, tables, embedded objects, comments and tracked changes after conversion or round-trip save. Build a test set from real sample files taken from your document stores, including the most complex templates, spreadsheets with many formulas and presentations with embedded media. Have the document owners compare the original and the edited result and record which differences are acceptable. Keep that record, because it becomes the basis for the decision on which legacy files must be migrated to a modern format first.

Before the build starts, inventory your attachments by type and count. Export a list of file extensions across the spaces you plan to migrate or connect, and count how many .doc, .xls and .ppt files exist compared with the modern formats. Also note the largest files and the spaces that hold them. A small number of legacy files may need only a spot check, while a large legacy population calls for a sampling plan, named reviewers, a conversion schedule and a clear owner for exceptions. The inventory is also the input you need to ask a partner for a fixed-scope quote, because it sets how much testing and governance the rollout requires.

Plan the governance around that inventory. Decide who approves the list of supported and conversion-dependent formats, who signs off on fidelity for each document class, and what users are told about editing converted copies. Confirm with the ONLYOFFICE Document Server and XWiki versions you will run that the connector behavior matches the tested configuration. Documenting these decisions now prevents disputes about which copy is authoritative once people start co-editing.

Before users rely on co-editing, run a documented test plan that covers every office format you intend to support, every user role that will touch those files, and every upgrade path you expect to take. The OnlyOffice Connector runs natively on .docx, .xlsx, .pptx, .odt, .ods and .odp files and can convert .doc, .xls and .ppt for editing, so build a sample set that includes each of these types. Include legacy .doc, .xls and .ppt files that came out of a migration or an old file share, because conversion behavior on those is where surprises usually appear. Record which files open, which convert, which fail, and whether formatting, comments, tables and embedded objects survive a save back to the attachment.

Run the multi-user checks with at least two accounts editing the same document at the same time, then add a third account that holds read-only rights on the page. The reader must not be able to open the editor, must not see save controls, and must not be able to change the attachment through a direct URL or a replaced version. Confirm this against the XWiki rights you have set for the space and page, not only against the visible interface. Also test large files and files that another user has locked, because lock handling and timeouts are where co-editing sessions tend to stall. Note the file sizes and page counts you tested so the results can be compared when you change settings.

Check save and version history next. After a series of edits by two users, open the attachment history in XWiki and confirm that each save produced the version you expect, that authors are recorded correctly, and that restoring an earlier version returns the content you intended. Then restart or fail over the Document Server while a session is open. Watch how the editor reconnects, whether unsaved changes are recovered, and whether XWiki still reaches the Document Server after the restart. Document what the users see at each step, because the recovery message will be the first thing they ask about.

Plan to repeat this full test after every XWiki upgrade and every Document Server upgrade, not only after the first installation. The connector is tested against a stated range of Document Server versions, currently 8.2 through 9.0.4 according to the connector listing, and it requires XWiki 15.10 or later. Before you upgrade either side, confirm that the target versions still fall inside the tested range, and check the connector release notes for any change. If you run a version outside that range, treat it as untested and widen your own test cycle accordingly. Keep the results from each run in a dated record so that a later failure can be compared against a known good state.

Assign ownership for the test before the pilot begins. A wiki administrator should own the permission and version checks, and whoever runs the Document Server should own the restart and failover test and the CORS and network checks. Agree in advance what counts as a pass, including acceptable recovery behavior for an open session after a restart, and what triggers a rollback. If you hire a partner to run the plan, ask for the test cases, the sample files and the results record in the written scope, and confirm who keeps them after the engagement ends.