Configuring Collaborative Authoring

Collaborative authoring connects Vault to Microsoft 365 to allow multiple users to edit a document at the same time using the Microsoft 365 desktop software or browser apps. Collaborative Authoring can be used with Microsoft Word (*.docx), Excel (*.xlsx and *.xlsm), and PowerPoint (*.pptx) documents.

See FAQ: Collaborative Authoring for a list of frequently asked questions related to using collaborative authoring.

Configuration Overview

To configure collaborative authoring as a new customer or in a new Vault, you need to:

Demo: Configuring Collaborative Authoring

The following video demonstrates how to configure collaborative authoring for new customers or new Vaults:

Configuring Microsoft 365 Using the PowerShell Script

We have provided a PowerShell script (collab_auth_setup_script.ps1) to simplify the process of configuring the necessary updates in Entra ID and SharePoint. While many of the updates can be done without PowerShell, granting the Entra ID application Write access to the SharePoint site can only be done using PowerShell. We have incorporated all steps into the PowerShell script to ensure all steps are done correctly. See the PowerShell script’s included README for detailed information about running the script.

The script performs the following actions:

  • Creates a temporary admin application in Entra ID with the AllSites.FullControl permission to be used to grant the necessary permissions. This application is deleted automatically when the script completes.
    • All permissions must be granted admin consent
  • Creates an Entra ID application for Vault to use and apply the necessary API permissions, including:
    • Sites.Selected permission (required)
    • Optional for automatic external user invites: Directory.ReadWrite.All and User.Invite.All
    • Optional for automatic adding of participants during workflows: User.Read.All
    • The above permissions are application permissions for Microsoft Graph
  • Creates a SharePoint site.
  • Applies security hardening to the SharePoint site to prevent non-admin access to the site directly in SharePoint.
    • Disables member sharing. Only site owners will be allowed to share files, folders, and the site.
    • Disables requesting access to the site and the site’s files.
    • Disables deleting files for members with the Contribute permission level.
    • Removes member and visitor groups from the documents library. Only the owner group will have default access.
  • Grants the Entra ID application Write permission to the SharePoint site (using the app’s Sites.Selected permission).

Configuring Microsoft 365 for External Collaboration

External users are collaborators with email addresses from different domains. In order to use collaborative authoring with external users, you must enable automatic invitations through Entra ID in your Vault. Once automatic invitations are enabled, Vault sends external users an email invitation when they click Edit to start or join a collaborative authoring session, automatically adding them to the session. External users can then join or start the session by clicking Edit. External users do not need to accept the email invitation to collaborate and join a session.

To enable automatic invitations in Microsoft 365:

  1. Ensure your app registration has the Directory.ReadWrite.All and User.Invite.All permissions with admin consent granted.
  2. Enable external collaboration at a SharePoint tenant level:
    1. Log into Office365 Admin Center.
    2. Navigate to SharePoint Admin Center.
    3. Under Policies, click Sharing.
    4. In the External sharing > Content can be shared with section, allow for sharing with external users by selecting an option other than Only people in your organization.
  3. Enable external collaboration at the site collection level:
    1. In SharePoint Admin Center, click Active Sites.
    2. Locate your Vault’s site.
    3. Select the Policies tab.
    4. Click Edit in the External Sharing section.
    5. In the External sharing > Content can be shared with section, allow for sharing with external users by selecting an option other than Only people in your organization.

Connecting Your Vault to Your Microsoft 365 Account

Once you have configured Microsoft 365 to work with Vault, you must connect your Vault to your Microsoft 365 account.

To connect your Vault to Microsoft 365 in Entra ID:

  1. In Entra ID, on the application page for the app registration for your Vault, click Certificates & Secrets.
  2. Create a new client secret and ensure that you record the Value. This value only remains visible for a few minutes.

To connect your Vault to Microsoft 365 in Vault

  1. In your Vault, navigate to Admin > Settings > Checkout Settings and click Edit in the Collaborative Authoring with Microsoft Office section.
  2. Fill in the following fields:
    • Directory (tenant) Id: The automatically-generated Tenant ID listed on the App Overview page of the Vault application you created in Entra ID.
    • Application (client) Id: The automatically-generated Client ID listed on the App Overview page of the Vault application you created in Entra ID.
    • Client Secret: The client secret Value generated in Step 2.
    • Collaboration Drive: The URL to the Documents folder on the SharePoint team site you created. This URL should end in /Shared%20Documents. You do not need to include /Forms/AllItems.aspx.
  3. Optional: Select the Auto Invite External Users checkbox if you configured Microsoft 365 for external collaboration.
  4. Click Authorize. When the checkout settings are authorized, the Integration Status is displayed as Verified.
  5. Click Save.

Configuring Collaborative Authoring Workflows in Vault

You can use workflow and lifecycle actions to automatically start, end, and cancel collaborative authoring sessions from a document workflow. The actions include:

  • Check Out to Microsoft Office
  • Check In From Microsoft Office
  • Cancel Editing in Microsoft Office

To configure collaborative authoring actions on a workflow, you must add a System Action step. The System Action drop-down displays each action for you to select. You can also configure these actions as entry actions on document lifecycle states. These actions are available in workflow configuration by default, but you cannot activate workflows containing one or more of these actions if your Vault is not configured and verified for collaborative authoring.

When the workflow enters a lifecycle state or workflow step configured with one of these actions, Vault immediately executes it for any document in the workflow. For example, if the In Authoring state is configured with the Check Out to Microsoft Office entry action, Vault checks any documents in the workflow out to Microsoft 365 as soon as the workflow enters In Authoring.

Vault always considers the Workflow Owner as the user who executes collaborative authoring actions. It is recommended that you include both the Check Out to Microsoft Office and Check in From Microsoft Office actions in the collaborative authoring workflow configuration as it ensures the Workflow Owner checks in and checks out documents. If only one of these actions is included, it could cause issues in the workflow.

For example, if a user other than the Workflow Owner clicks Edit in Microsoft Office from the Actions menu, and a Check in From Microsoft Office action is configured on the System Action step or as a lifecycle entry action later in the workflow, an error will occur when the check in executes. This error happens because the Workflow Owner did not check the document out. The user who checks out and checks in the document must be the same. In addition, the Workflow Owner must have Edit permission on the lifecycle state configured with the collaborative authoring action.

If a document is already checked out when the collaborative authoring action runs or checked in before the workflow is complete, Vault will take no collaborative authoring action.

Automatic Mentioning in Workflows

When using the automatic check-out option with a workflow, users can tag workflow participants in Microsoft Office files using the @mention functionality, without authors needing to open the document in collaborative authoring first.

To enable automatic mentioning, ensure your Entra ID application has the User.Read.All permission. Vault uses this permission to give workflow participants Write access to the checked out documents.

Vault can also grant new workflow participants the necessary permissions to be tagged with the @mention functionality when added as part of the Add Participants action or when added as a task owner through task reassignment.

When configuring the workflow, ensure that your workflow participants are being granted the necessary permissions in Vault to participate in collaborative authoring before the Check Out to Microsoft Office step.

For instance, if your workflow adds participants to the Author role as part of the Task step, and that Task step comes after the Check Out action, Vault may fail to grant participants Write access due to Vault permissions being granted after checkout completes. The following examples demonstrate an improperly configured workflow:

Automatic mentioning in workflows

Automatic mentioning in workflows

Workflow Limitations

The following limitations apply to using collaborative authoring workflows:

  • When adding workflow participants during the Check Out to Microsoft Office workflow action, Vault can only grant Write permission to up to 15 participants. When adding more than 15 participants, none of the participants are granted Write permission.
  • Microsoft 365 does not support @mentioning external users (users who are not part of your organization’s directory).
  • Vault supports automatic mentioning through workflows only. If a workflow is not used, users can only be mentioned in the file after they have opened the document in collaborative authoring.
  • Users must have permissions in Vault to participate in collaborative authoring before the Check Out to Microsoft Office workflow step.
  • When a collaborative authoring action is executed through a System Action step, the audit trail displays System as the Workflow Owner.
  • If the Workflow Owner changes while a document is checked out, the new Workflow Owner must be a Vault Owner or have the All Document Actions permission to check the document in.
  • Vault executes the collaborative authoring actions asynchronously. Users may need to refresh their browser if the action’s results do not immediately appear on screen.
  • Vault encounters an error if the SharePoint unique permission limit of 50,000 is reached. Ensure documents where users have Edit permission are checked back in after collaborative authoring is complete to avoid encountering this error.

Configuring Notifications for Workflows Actions in Vault

Admins can configure a summary notification to be sent out upon completion of a collaborative authoring workflow action. If the action is configured on a System Action step, the notification is sent to the Workflow Owner. If the notification is configured on an entry action, a notification is sent to the user who initiated the state change. Select one of the following options from the Send Notification upon (action) Completion drop-down:

  • Always: A notification is always sent after the action completes.
  • Only upon failure: A notification is sent if the action fails.
  • Never: A notification is never sent for the action.

The notification includes the following information about each document in the workflow:

  • Total number of documents that failed and succeeded
  • Name of the specific action
  • Date and time in your Vault’s time zone the action started
  • Collaborative authoring session duration in hours, minutes, and seconds

The total number of failed and successful documents displays as a link that downloads the results to a CSV file. Use this file to view additional information, such as error descriptions when an action fails.

Related Permissions

To participate in collaborative authoring, users require the indicated permissions for the following functionality:

Functionality Required Permissions
Edit a Document using Collaborative Authoring Users with the Edit Document role-based permission can click Edit or All Actions > Edit in Microsoft Office to edit a document using collaborative authoring.
Check In The user who started the collaboration session, the Document Owner, Vault Owners, and users with the All Document Actions permission can click Check In to check in a document and end the collaboration session.
Save to Vault Users with the Edit Document role-based permission can click Save to Vault to save their document edits to Vault without checking in the document or ending the collaboration session.
Cancel Editing The following users can click Cancel Editing to cancel a collaboration session, discard unsaved edits, and end the session for all users:
  • The Document Owner (requires the Edit Document role-based permission)
  • The user who started the collaboration session (requires the Edit Document role-based permission)
  • A user with both the Edit Document role-based permission and the Application: Document: Cancel Checkout permission
  • Vault Owners or users with the All Document Actions permission
View the Collaborative Authoring Error Log Users with the Admin: Logs: Collab Auth Error Logs permission can view the Collaborative Authoring Error Log.

Appendix

PowerShell Configuration Scripts

We have provided several PowerShell scripts to streamline several aspects of the collaborative authoring configuration process. Download the SharePoint Site Management .ZIP file, which contains the following files:

  • README: This text file describes the purposes of each script, the variables you need to update in each script, and how to run the scripts. Ensure that you read the README before running the scripts.
  • collab_auth_setup_script.ps1: This script performs the actual updates in Entra ID and SharePoint. You can use this script for new setups and for migrating from the legacy configuration.

See this document for details and screenshots about what information the PowerShell script prompts for.