Set up Collaborative Authoring

This article is applicable to configuring enhanced collaborative authoring, which was released with 25R1. For users still on legacy collaborative authoring, see collaborative authoring legacy migration

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, the Microsoft 365 mobile apps, or Microsoft 365 on the web. Only users with Edit and Download permissions can edit a document with collaborative authoring. Collaborative authoring can be used with Microsoft Word (.docx), Excel (.xlsx and .xlsm), and PowerPoint (.pptx) documents.

Collaborative authoring is not enabled in your Vault by default. You must configure your Vault to make this feature available to users.

Configuration Overview

To configure collaborative authoring with Microsoft 365, you need to:

• Have a Microsoft 365 tenant.
• Register your Vault as an Entra ID application.
• Create a dedicated SharePoint team site and grant the Entra ID application access to manage the site.
• Secure the SharePoint team site.
• Connect your Vault to your Microsoft 365 tenant.
• Set up automatic invitations for external users.
• Enable external collaboration in SharePoint.

This configuration checklist document provides more details on the setup process above.

Registering Your Vault as an Entra ID Application

Your Microsoft 365 business subscription includes Entra ID. To use collaborative authoring, you must register your Vault as an application in Entra ID. Vault needs certain permissions to access your Microsoft 365 account.

1. Register a new application in Entra ID.

2. Under Redirect URIs, select Web.

3. Enter your Vault’s Redirect URI as follows: https://[Your Vault DNS]/ui/clientTiles/office365/oauth2. For example: https://veeva-qms.veevavault.com/ui/clientTiles/office365/oauth2

4. Click Microsoft Graph > Application permissions. In the Select permission search bar, search for and add following:

   Sites.Selected User.ReadBasic.All

   Optional: For external user access, add a Microsoft Graph permission with the following Application permissions:

   User.Invite.All
   User.ReadWrite.All Directory.ReadWrite.All

5. On the Entra ID application page, click Certificates & Secrets.

6. Create a new client secret and ensure that you record the Value for use later in the configuration process.

Creating the SharePoint Team Site & Granting App Access

The Sites.Selected Entra ID application permission specifies the SharePoint sites to which your Entra ID application has access. This permission must be configured in order to allow Vault to temporarily store collaborative authoring documents while they are being edited.

We have provided a PowerShell script (SitePnP.ps1) to simplify the process of configuring the Sites.Selected permission to grant your Entra ID application access to your SharePoint site. This script uses a separate Entra app with the AllSites.FullControl permission. The app provides the app setup for Vault permissions to manage documents on your SharePoint site.

Naming Restrictions for SharePoint Sites

Follow these rules when naming your SharePoint site:

• In general, your site name should not include the following special characters: ., (, ), {, }, [, ], ', ", <, >, ?. In some cases, you can use some of these characters before .com in your site URL.
• You cannot end your site URL with a forward slash (/).

SharePoint Site Limits

SharePoint allows up to 50,000 unique permissions per site.

To avoid reaching the SharePoint site limit, ensure documents are checked in after collaborative authoring is completed. If multiple documents are left checked out, Vault may encounter the SharePoint site limit.

Securing the SharePoint Team Site

The Microsoft SharePoint team site is a shared document library where your Vault documents are temporarily stored while they are being edited. The SharePoint permissions should not allow users to access or share Vault documents directly through Microsoft 365.

To streamline the SharePoint site configuration process, we have provided a PowerShell script (SiteHardening.ps1) to configure these permissions and settings automatically. You can also create and configure the SharePoint site manually without using the script:

1. Create a new team site in the SharePoint Admin Center. See details about site naming restrictions below.
2. Set the privacy settings for the team site to Private.
3. Click Create Site.
4. Select Settings > Site Permissions > Change How Members Can Share.
5. Select Only site owners can share files, folders, and the site.
6. Set Allow access requests to Off under Access Requests.
7. Click Save.
8. Return to the team site Home.
9. Select Documents > Settings > Library Settings > More Library Settings > Permissions for this Document Library.
10. Click Stop Inheriting Permissions.
11. Click OK.
12. Select users in the Site Members and Site Visitors groups.
13. Click Remove User Permissions.
14. Click OK. Ensure that the Owners group is the only remaining group.
15. Return to the Document Library.
16. Record the SharePoint shared documents library URL for use when configuring the checkout settings in Vault.

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.

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 when registering your Vault in Entra ID.
   • Collaboration Drive: The URL to the Documents folder on the SharePoint team site you created.
3. Click Authorize. When the checkout settings are authorized, the Integration Status is displayed as Verified.
4. Click Save.

Automatically Inviting External Users

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:

1. In your Vault, navigate to Admin > Settings > Checkout Settings.
2. Click Edit in the Collaborative Authoring with Microsoft Office section.
3. Select the Auto Invite External Users checkbox.
4. Click Confirm in the Re-authorization Required dialog.
5. Click Authorize.
6. Click Save.

Enabling External Collaboration in SharePoint

When configuring collaborative authoring, ensure that you enable external collaboration and access to your SharePoint content. To learn more, view the SharePoint documentation.

Configuring Automatic Mentioning

Vault automatically adds workflow participants as editors on collaborative authoring documents, which allows them to be @mentioned in a collaborative authoring session. To use this functionality, ensure that you add the User.ReadBasic.All application permission to the Microsoft Graph permission in the Entra ID application.

Removing Collaborative Authoring with Microsoft 365 Settings

To turn off collaborative authoring, remove the checkout settings. This option is available only when no documents are currently being edited in Microsoft 365.

1. In your Vault, navigate to Admin > Settings > Checkout Settings and click Edit.
2. Click Remove Settings.
3. Click OK to confirm that you want to remove these settings.
4. Click Save.

Migrating from Legacy to Enhanced Collaborative Authoring Configuration

Beginning with 25R1, the collaborative authoring configuration is enhanced to allow Admins to configure collaborative authoring without requiring a Microsoft 365 service account. Customers with collaborative authoring configured prior to 25R1 can migrate from the legacy configuration to the enhanced configuration and can revert back to the legacy settings if needed. Customers who have never configured collaborative authoring must use the enhanced configuration available with 25R1.

See the legacy migration guide for more info.

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 files below.

• 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.
• SitePnP.ps1: This script is intended for sites that are configuring collaborative authoring for the first time. It creates a SharePoint team site and grants your Entra ID application access to the created SharePoint team site using the Sites.Selected app permission.
• SitePnP_update existing site.ps1: This script is intended for sites migrating from the legacy to the enhanced collaborative authoring configuration. It grants permissions for your Entra ID app to manage the SharePoint team site.
• SiteHardening.ps1: This script configures the appropriate permissions and settings of an existing SharePoint team site.