Co-authoring using Office for the web

Important

Participants in the Office 365 - Cloud Storage Partner Program must support document editing and multi-user co-authoring.

Office for the web supports multiple users editing a document at the same time. Co-authoring in Office for the web 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 for the web take a lock on the file to ensure that only Office for the web 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 for the web, users are never locked out of editing a document.

Second, while Office for the web 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 for the web 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 for the web provides benefits for single-user editing as well.

How co-authoring works in Office for the web

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

When a user attempts to edit a document, Office for the web 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 for the web 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 for the web to verify users still have edit permissions periodically.

The answers to these questions differ between the Office for the web 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 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 for the web 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 for the web 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 for the web 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 for the web will make two PutFile requests, each using the access token of the user who made the change.

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

Excel for the web co-authoring behavior

Auto-save frequency: Every 2 minutes.

PutFile access token: Excel for the web 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 for the web 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 for the web will verify that a user has permissions by calling RefreshLock at least every 15 minutes while the user is in an active session.

PowerPoint for the web 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 for the web will not call PutFile until document changes are made again.

Note

During a single-user editing session, PowerPoint for the web 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 for the web 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 for the web 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 for the web will make two PutFile requests, each using the access token of the user who made the change.

Permissions check frequency: PowerPoint for the web 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 for the web 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 for the web may make additional WOPI calls beyond those described below. These scenarios are meant only to illustrate the key behavioral aspects of the Office for the web 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 for the web calls CheckFileInfo using User A’s access token to verify the user has edit permissions.

  3. Office for the web calls Lock using User A’s access token.

  4. User B tries to edit the same document.

  5. Office for the web calls CheckFileInfo using User B’s access token to verify the user has edit permissions.

Key points

  • Office for the web 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 for the web 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 for the web

User A, since User B is not editing.

Excel for the web

User B

PowerPoint for the web

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 for the web

Either access token may be used, depending on which user changed the document most recently during the auto-save interval.

Excel for the web

User B

PowerPoint for the web

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 for the web application or navigating away.

  2. User B continues editing the document.

  3. User C tries to edit the same document.

  4. Office for the web 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 for the web

Any access token may be used, depending on which user changed the document most recently during the auto-save interval.

Excel for the web

User C

PowerPoint for the web

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 for the web

User A, since User B is not editing.

After no more than 5 minutes, Word for the web 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 for the web

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 for the web

User A, since User B is not editing.

After no more than 5 minutes, PowerPoint for the web 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 for the web

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 for the web 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 for the web

User B

Same as scenario 4.

PowerPoint for the web

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 for the web 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 for the web

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 for the web 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 for the web

User B

After no more than 15 minutes, Excel for the web 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 for the web

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 for the web 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.