Co-authoring using Office Online

Office Online supports multiple users editing a document at the same time. Co-authoring in Office Online includes real-time content updates between all users editing the document, as well as presence information and real-time cursor tracking for each user.

There are no unique WOPI host requirements beyond those described in this documentation in order to support co-authoring. However, the guidelines around file IDs and locks, as described in the Key concepts section, are very important in order to enable co-authoring.

Benefits from co-authoring support

Editing documents requires that Office Online take a lock on the file to ensure that only Office Online is writing to the file. In cases where co-authoring is not supported, this causes two problems.

First, users are unable to make changes to the file while someone else is editing it. This problem is avoided when co-authoring is supported. With co-authoring in Office Online, users are never locked out of editing a document.

Second, while Office Online makes every attempt to unlock files after users have finished editing documents, there are circumstances where this may not happen. If Unlock is not called successfully, then the file will stay locked until the lock times out. This can mean that a user can be locked out of editing a file even if they were the one that originally locked it. When co-authoring is supported, the fact that the file is locked is not a problem; Office Online will allow the user to edit the document as if he or she is ‘co-authoring with him/herself’.

Thus, in addition to the obvious benefits for multi-user editing that come along with real-time co-authoring, co-authoring in Office Online provides benefits for single-user editing as well.

How co-authoring works in Office Online

When multiple users edit a single document using Office Online, the Office Online service manages the document changes and any necessary merges internally.

When a user attempts to edit a document, Office Online takes a lock using the Lock operation and the access token of the current user. When additional users then attempt to edit the same document, Office Online will verify those users have permission to edit the document by calling CheckFileInfo using each user’s access token. If the CheckFileInfo call succeeds and the user has permissions to edit, they will join the editing session already in progress.

Users who are collaborating will see the document content update in real-time as other users edit. However, Office Online will only call PutFile periodically with the updated document contents. There are three critical questions to consider with respect to co-authoring sessions:

  1. Auto-save frequency: How frequently will the application call PutFile?
  2. PutFile access token: Which user’s access token will be used when PutFile is called?
  3. Permissions check frequency: How often will the application verify that a user still has appropriate permissions to edit the document?

Question 3 is important because PutFile is called using a single user’s access token, so a WOPI host will only be able to check permissions of the user whose access token is used. Hosts rely on Office Online to verify users still have edit permissions periodically.

The answers to these questions differ between the Office Online applications. The table below summarizes the behavior for each application, and the following sections describe this behavior in more detail.

Table 1 Summary of co-authoring behavior for Office Online applications
Application Auto-save frequency PutFile access token Permissions check frequency
Word Every 30 seconds if document is updated. The access token of the user who made the most recent change to the document. At least every 5 minutes.
Excel Every 2 minutes. The access token of the user who joined the editing session most recently. At least every 15 minutes.
PowerPoint Every 60 seconds if document is updated. The access token of the user who made the most recent change to the document. At least every 5 minutes.

Word Online co-authoring behavior

Auto-save frequency: Every 30 seconds if document is updated. In other words, if users are actively editing a document, PutFile will be called every 30 seconds. However, if users stop editing for a period of time, Word Online will not call PutFile until document changes are made again.

PutFile access token: For each auto-save interval, Word Online will use the access token of the user who made the most recent change to the document. In other words, if User A and B both make changes to the document within the same auto-save interval, but User B made the last change, Word Online will use User B’s access token when calling PutFile. The file will have both users’ changes, but the PutFile request will use User B’s access token.

If, on the other hand, User A made a change in one auto-save interval, and User B made a change in another auto-save interval, then Word Online will make two PutFile requests, each using the access token of the user who made the change.

Permissions check frequency: Word Online will verify that a user has permissions by calling CheckFileInfo at least every 5 minutes while the user is in an active session.

Excel Online co-authoring behavior

Auto-save frequency: Every 2 minutes.

PutFile access token: Excel Online will always use the access token of the user who joined the editing session most recently. This user is called the principal user. If the principal user leaves the session, then the last user who joined the session becomes the principal user. In other words, if User A starts editing, then User A is the principal user. If User B then joins the session, User B becomes the principal user, and Excel Online will use User B’s access token when calling PutFile. The file will have both users’ changes, but the PutFile request will use User B’s access token. If User C then joins the session, User C becomes the principal user.

If User C then leaves the session, then User B becomes the principal user, and User B’s access token will be used when calling PutFile.

Permissions check frequency: Excel Online will verify that a user has permissions by calling RefreshLock at least every 15 minutes while the user is in an active session.

PowerPoint Online co-authoring behavior

Auto-save frequency: Every 60 seconds if document is updated. In other words, if users are actively editing a document, PutFile will be called every 60 seconds. However, if users stop editing for a period of time, PowerPoint Online will not call PutFile until document changes are made again.

Note

During a single-user editing session, PowerPoint Online will only call PutFile every 3 minutes. During an active co-authoring session, that frequency is increased to every 60 seconds.

PutFile access token: For each auto-save interval, PowerPoint Online will use the access token of the user who made the most recent change to the document. In other words, if User A and B both make changes to the document within the same auto-save interval, but User B made the last change, PowerPoint Online will use User B’s access token when calling PutFile. The file will have both users’ changes, but the PutFile request will use User B’s access token.

If, on the other hand, User A made a change in one auto-save interval, and User B made a change in another auto-save interval, then PowerPoint Online will make two PutFile requests, each using the access token of the user who made the change.

Permissions check frequency: PowerPoint Online will verify that a user has permissions by calling CheckFileInfo at least every 5 minutes while the user is in an active session.

Scenarios

The following scenarios illustrate the behavior WOPI hosts can expect for each Office Online application when users are co-authoring.

All scenarios described here assume the following baseline flow.

Note

The pattern of WOPI calls described below is not meant to be absolutely accurate. Office Online may make additional WOPI calls beyond those described below. These scenarios are meant only to illustrate the key behavioral aspects of the Office Online applications; they are not an absolute transcript of WOPI traffic between Office Online and a WOPI host.

Scenario baseline

  1. User A begins editing a document.
  2. Office Online calls CheckFileInfo using User A’s access token to verify the user has edit permissions.
  3. Office Online calls Lock using User A’s access token.
  4. User B tries to edit the same document.
  5. Office Online calls CheckFileInfo using User B’s access token to verify the user has edit permissions.

Key points

  • Office Online will always verify each user has appropriate edit permissions to the document by calling CheckFileInfo using that user’s access token before allowing them to join the edit session.
  • Lock will always be called using the access token of the first user to start editing the document.
  • If users leave the editing session while others are still editing, Office Online will call other lock-related operations, such as Unlock or RefreshLock, using the access tokens of other users that are still editing.

Scenario 1

  1. User A continues editing the document.
  2. User B makes no changes.
Table 2 Co-authoring scenario 1
Application PutFile access token used Additional notes
Word Online User A, since User B is not editing.  
Excel Online User B  
PowerPoint Online User A, since User B is not editing.  

Scenario 2

  1. User A continues editing the document.
  2. User B also edits the document.
Table 3 Co-authoring scenario 2
Application PutFile access token used Additional notes
Word Online Either access token may be used, depending on which user changed the document most recently during the auto-save interval.  
Excel Online User B  
PowerPoint Online Either access token may be used, depending on which user changed the document most recently during the auto-save interval.  

Scenario 3

  1. User A leaves the editing session by closing the Office Online application or navigating away.
  2. User B continues editing the document.
  3. User C tries to edit the same document.
  4. Office Online calls CheckFileInfo using User C’s access token to verify the user has edit permissions.
Table 4 Co-authoring scenario 3
Application PutFile access token used Additional notes
Word Online Any access token may be used, depending on which user changed the document most recently during the auto-save interval.  
Excel Online User C  
PowerPoint Online Any access token may be used, depending on which user changed the document most recently during the auto-save interval.  

Scenario 4

  1. User A continues editing the document.
  2. User B is in the session but is not editing the document.
  3. While the editing session is in progress, User B’s permissions to edit the document are removed.
Table 5 Co-authoring scenario 4
Application PutFile access token used Additional notes
Word Online User A, since User B is not editing. After no more than 5 minutes, Word Online will call CheckFileInfo with User B’s access token. That call will indicate that User B no longer has edit permissions, so User B will be removed from the editing session. User A can continue editing the document.
Excel Online User B Once User B’s edit permission is removed, all PutFile requests for the session will fail. In no more than 3 minutes after the first PutFile failure, then all users, including User A, will be removed from the editing session.
PowerPoint Online User A, since User B is not editing. After no more than 5 minutes, PowerPoint Online will call CheckFileInfo with User B’s access token. That call will indicate that User B no longer has edit permissions, so User B will be removed from the editing session. User A can continue editing the document.

Scenario 5

  1. User A continues editing the document.
  2. User B also continues editing the document.
  3. While the editing session is in progress, User B’s permissions to edit the document are removed.
Table 6 Co-authoring scenario 5
Application PutFile access token used Additional notes
Word Online Either access token may be used, depending on which user changed the document most recently during the auto-save interval. If a PutFile request is made using User B’s access token, it will fail, and all users, including User A, will be removed from the editing session. If PutFile is never called with User B’s access token, then after no more than 5 minutes, Word Online will call CheckFileInfo with User B’s access token. That call will indicate that User B no longer has edit permissions, so User B will be removed from the editing session. User A can continue editing the document.
Excel Online User B Same as scenario 4.
PowerPoint Online Either access token may be used, depending on which user changed the document most recently during the auto-save interval. If a PutFile request is made using User B’s access token, it will fail, and all users, including User A, will be removed from the editing session. If PutFile is never called with User B’s access token, then after no more than 5 minutes, PowerPoint Online will call CheckFileInfo with User B’s access token. That call will indicate that User B no longer has edit permissions, so User B will be removed from the editing session. User A can continue editing the document.

Scenario 6

  1. User A continues editing the document.
  2. User B also continues editing the document.
  3. While the editing session is in progress, User A’s permissions to edit the document are removed.
Table 7 Co-authoring scenario 6
Application PutFile access token used Additional notes
Word Online Either access token may be used, depending on which user changed the document most recently during the auto-save interval. If a PutFile request is made using User A’s access token, it will fail, and all users, including User B, will be removed from the editing session. If PutFile is never called with User A’s access token, then after no more than 5 minutes, Word Online will call CheckFileInfo with User A’s access token. That call will indicate that User A no longer has edit permissions, so User A will be removed from the editing session. User B can continue editing the document.
Excel Online User B After no more than 15 minutes, Excel Online will call RefreshLock with User A’s access token. That call will fail since User A no longer has edit permissions, so User A will be removed from the editing session. User B can continue editing the document.
PowerPoint Online Either access token may be used, depending on which user changed the document most recently during the auto-save interval. If a PutFile request is made using User A’s access token, it will fail, and all users, including User B, will be removed from the editing session. If PutFile is never called with User A’s access token, then after no more than 5 minutes, PowerPoint Online will call CheckFileInfo with User A’s access token. That call will indicate that User A no longer has edit permissions, so User A will be removed from the editing session. User B can continue editing the document.