WOPI Coauthoring: A Technical Guide to Real-Time Multi-User Document Editing

WOPI Coauthoring

Real-time collaborative document editing has become a baseline expectation for modern productivity platforms. Users who experience simultaneous editing in Google Docs or Microsoft 365 expect the same capability everywhere they work with documents. For ISVs and SaaS platforms that embed Microsoft Office document editing through the WOPI protocol, implementing coauthoring is both the most technically demanding and the most commercially valuable capability available.

This guide provides an in-depth technical walkthrough of WOPI coauthoring implementation, covering the protocol mechanics, lock management strategies, conflict resolution, and the architecture patterns that separate production-grade implementations from fragile prototypes.

What Is WOPI Coauthoring?

WOPI coauthoring enables multiple users to simultaneously view and edit the same document within an Office Online (or Office for the web) session, all mediated through the WOPI protocol. When a WOPI host supports coauthoring, the Office application coordinates changes between users in real time, merging edits at the paragraph and cell level without requiring users to manually resolve conflicts.

From the WOPI host’s perspective, coauthoring introduces additional protocol requirements beyond single-user editing. The host must support specific discovery properties, implement robust lock management, handle coauthoring status callbacks, and manage file storage in a way that supports concurrent access without data corruption.

For ISVs building real-time document editing capabilities via the WOPI protocol, coauthoring is the feature that transforms embedded Office from a convenient viewer into a genuine collaboration platform.

Discovery Properties for Coauthoring

Before Office Online will attempt coauthoring for a document, it checks specific properties returned by the WOPI host in the CheckFileInfo response. These properties signal to the Office application that the host is capable of managing concurrent editing sessions.

The critical discovery properties include:

• SupportsCoauth: When set to true, this tells Office Online that the host supports multiple users editing simultaneously. Without this flag, Office falls back to single-user editing with exclusive locks.
• SupportsLocks: Coauthoring requires lock management. This property must be true for coauthoring to function.
• SupportsUpdate: The host must accept file updates via PutFile. This is required for any editing scenario, but is worth confirming explicitly in a coauthoring context.
• SupportsGetLock: Enables Office Online to query the current lock state, which is essential for managing the transition between single-user and multi-user editing modes.

If any of these properties are missing or set to false, Office Online will not attempt coauthoring — it will either fall back to single-user editing or open the document in read-only mode.

Lock Management: The Foundation of Coauthoring

Lock management is the single most critical implementation detail in WOPI coauthoring. The difference between a reliable coauthoring implementation and one that loses data or corrupts documents almost always comes down to how locks are handled.

Understanding WOPI Lock Types

In a coauthoring scenario, WOPI uses collaborative locks rather than exclusive locks. The distinction is fundamental:

• Exclusive locks prevent any other user from editing the document. They are appropriate for single-user editing scenarios.
• Collaborative locks allow multiple users to hold a lock on the same document simultaneously. Office Online manages the coordination between users, and the WOPI host manages the lock state.

When Office Online initiates a coauthoring session, it sends a Lock request with a lock identifier. The host must store this lock identifier and associate it with the document. Subsequent users joining the same coauthoring session will present the same lock identifier — the host should recognise this and allow the operation.

The Lock and UnlockAndRelock Operations

The Lock operation is straightforward in concept but requires careful implementation:

1. Lock: Office Online sends a lock request with an X-WOPI-Lock header containing the lock identifier. If the document is unlocked, the host should apply the lock and return HTTP 200. If the document is already locked with the same identifier, the host should return HTTP 200 (this is a valid coauthoring scenario). If the document is locked with a different identifier, the host should return HTTP 409 with the current lock identifier in the X-WOPI-Lock response header.

2. UnlockAndRelock: This operation atomically replaces one lock with another. It is used when Office Online needs to transition a document between editing sessions. The host receives both the old lock identifier (in X-WOPI-OldLock) and the new lock identifier (in X-WOPI-Lock). The host must verify the old lock matches, then atomically replace it with the new lock.

The atomicity of UnlockAndRelock is critical. If the unlock and relock are implemented as separate operations with a gap between them, another process could acquire the lock in that window, leading to data loss.

Lock Expiration and Refresh

Locks have a limited lifetime. Office Online periodically refreshes locks by sending new Lock requests with the same lock identifier. If a lock expires because the host has not received a refresh within the expected timeout period (typically 30 minutes), the host should release the lock.

However, lock expiration in a coauthoring context requires careful handling. If multiple users are editing and the lock expires due to a network interruption with Office Online, releasing the lock could allow a conflicting operation to proceed. A robust implementation logs lock expirations and, where possible, delays lock release to provide a grace period.

Conflict Resolution Strategies

Even with proper lock management, conflicts can arise in coauthoring scenarios. The most common situations include:

• Network partitions: A user’s connection to Office Online drops temporarily, and their changes are queued locally. When the connection is restored, the queued changes may conflict with changes made by other users.
• Concurrent PutFile operations: In rare cases, the host may receive near-simultaneous PutFile requests from different coauthoring sessions.
• External modifications: A system process or API call modifies the document outside of the Office Online session.

Last-Writer-Wins vs Merge Strategies

The simplest conflict resolution strategy is last-writer-wins: the most recent PutFile overwrites the previous version. This is acceptable for many implementations, particularly when Office Online is managing the merge internally and sending consolidated updates.

However, for hosts that maintain version histories or support offline editing, a merge strategy may be more appropriate. This involves:

1. Storing the base version that each editing session started from.
2. When a PutFile arrives, comparing it against the base version to identify changes.
3. Merging changes from multiple sessions where possible.
4. Flagging irreconcilable conflicts for user resolution.

For most WOPI hosts, relying on Office Online’s built-in merge capabilities and implementing last-writer-wins at the storage layer provides the best balance of reliability and implementation complexity.

The Coauthoring Status Callback

Office Online provides a coauthoring status mechanism that allows the host to understand the current state of the editing session. The host can query:

• How many users are currently editing the document.
• Whether the document has unsaved changes.
• Whether any users are in a conflicted state.

This information is valuable for building user-facing indicators (such as showing who is currently editing a document) and for making operational decisions (such as whether to allow a batch process to modify the document).

Architecture Patterns for ISVs

Implementing WOPI coauthoring at scale requires architectural decisions that go beyond the protocol mechanics. Here are the patterns we see in successful production implementations.

Centralised Lock Store

For hosts running multiple application instances behind a load balancer, lock state must be centralised. A common pattern is using a distributed cache (such as Redis) or a database row-level lock to store WOPI lock identifiers. The lock store must support:

• Atomic read-modify-write operations (for UnlockAndRelock).
• TTL-based expiration (for automatic lock cleanup).
• High availability (a lock store outage blocks all editing).

File Storage Considerations

Coauthoring places specific demands on file storage:

• Atomic writes: PutFile operations must be atomic. A partial write that is visible to other readers or sessions will cause corruption.
• Version tracking: Maintaining a version counter or hash for each document enables conflict detection and supports the X-WOPI-ItemVersion header.
• Read-after-write consistency: After a PutFile completes, subsequent GetFile requests must return the updated content. Eventually-consistent storage backends can cause coauthoring anomalies.

Cloud storage services like Azure Blob Storage and Amazon S3 can support these requirements, but specific configuration is needed. For example, S3’s strong read-after-write consistency (available since December 2020) is essential for WOPI coauthoring workloads.

Scaling for High-Concurrency Sessions

Documents with many simultaneous editors (such as collaborative meeting notes or shared project plans) generate high volumes of WOPI requests. The host must handle:

• Frequent Lock refresh requests (every few minutes per session).
• Multiple GetFile and PutFile operations as Office Online synchronises changes.
• CheckFileInfo requests as new users join the session.

Connection pooling, request queuing, and horizontal scaling of the WOPI endpoint are all important considerations for hosts expecting high-concurrency coauthoring workloads.

Performance Considerations

Performance in a coauthoring scenario is user-visible in a way that single-user editing is not. When User A types a sentence, User B expects to see it appear within seconds. The latency chain includes:

1. User A’s browser to Office Online servers.
2. Office Online servers to the WOPI host (PutFile or coauthoring sync).
3. WOPI host processing and storage write.
4. Office Online servers fetching the updated content.
5. Office Online servers to User B’s browser.

Steps 2 and 3 are the only parts the WOPI host controls. Minimising PutFile processing time and ensuring fast GetFile responses directly impacts the perceived responsiveness of coauthoring.

Benchmarking your WOPI endpoint under concurrent load is essential before enabling coauthoring in production. We recommend testing with at least 10 simultaneous editors on a single document, with automated scripts generating edits at realistic intervals.

Common Implementation Mistakes

Having implemented WOPI coauthoring for multiple SaaS platforms, we consistently see the same mistakes:

1. Non-atomic lock operations: Implementing UnlockAndRelock as separate Unlock followed by Lock calls, creating a race condition window.
2. Ignoring lock refresh failures: Not handling the case where Office Online fails to refresh a lock, leading to premature lock expiration during active editing.
3. Blocking PutFile on validation: Running synchronous content validation or virus scanning during PutFile, adding seconds of latency that users experience as coauthoring lag.
4. Inconsistent lock store: Using an eventually-consistent data store for locks, causing phantom lock conflicts when requests hit different replicas.
5. Missing SupportsCoauth property: Forgetting to set the discovery property, resulting in single-user editing despite implementing all the coauthoring mechanics.

Moving Forward with WOPI Coauthoring

WOPI coauthoring implementation is a substantial engineering effort, but the commercial return is significant. For SaaS platforms, embedded real-time document editing via the WOPI protocol eliminates the need for users to download, edit, and re-upload documents — a workflow that is both error-prone and increasingly unacceptable to users accustomed to cloud-native collaboration.

As Microsoft continues to push Microsoft 365 interoperability for CSPP partners and the broader ecosystem, the expectation for seamless coauthoring will only grow. ISVs that invest in robust coauthoring implementations now will have a significant competitive advantage.

McKenna Consultants has deep expertise in WOPI protocol implementation, including coauthoring, lock management, and high-concurrency architecture design. If you are planning to add coauthoring to your WOPI integration or need help troubleshooting an existing implementation, contact us to discuss your requirements.