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.

Step 1: 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. Navigate to Home > App Registrations
3. Select New Registration
4. In name specify Veeva Vault Collaborative Authoring
5. Under Redirect URIs, select Web.
6. 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
7. Click Register button
8. Overview Page will be displayed, from Essentials section note values for (these values will be used later in the setup and in setup of additional vaults) Application (client) ID Directory (tenant) ID
9. In left menu Manage Section select + Add permissions
10. Select 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

11. Click Add permissions button
12. In left menu Manage section click Certificates & Secrets.
13. Click new client secret
    • In Description specify: Veeva Vault Collaboration
    • In Expires specify: 730 Days (24 months)
14. Click Add button
15. IMPORTANT note the Secret Value of the new Client Secret before moving to any other screen, once you move to a different page, the Secret Value will be hidden. (this value will be used later in the setup and in setup of additional vaults)

Step 2: Creating the SharePoint Team Site & Granting App Access

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

To create the site and grant app access:

1. Create a new team site in the SharePoint Admin Center. See details about site naming restrictions below
2. In Sharepoint Admin Center, in left menu, go to Sites > Active Sites > Create > Team Site
3. Select a template in From Microsoft section: Standard team
4. Click Use Template button
5. On Give your site a name page
   • Site name: Veeva Vault
   • Group email address: Veeva Vault
   • Site address: will be automatically populated
   • Group Owner: Specify the admin account which you use to manage sharepoint and access Entra
6. Click Next button
7. On Set language and other options page
   • Set the privacy settings for the team site to Private
   • Defaults can be left for Select a language and Time zone
8. Click Create site button (members don’t need to be added)

Step 3: 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 secure the site:

1. Login to sharepoint site we just created using the Administrator account you specified in step 5. In the next steps we will harden the security of the site we’ve created.
   • Url is typically: clientdomain.sharepoint.com/site/VeevaVault
2. Once logged in, click on gear icon in the top left (may take a few moments to show up if logging into the site for the first time)
3. Click Site permissions
4. In Site Sharing section click on Change how members can share link
   • Sharing Permissions: Only site owner can share files, folders and site
   • Allow access requests: Set setting to off
5. Click Save button
6. Click Advanced permission settings
7. Click Permission Levels (in PERMISSIONS tab in top ribbon)
8. Click Contribute link
   • In List Permission section, uncheck Delete Items - Delete items from a list and documents from a document library
9. Click Submit button (on bottom of the page)
10. Click Documents on the left side
11. Click on gear icon on the top left
12. Go to Library settings > More library settings > Permissions for this document library (Under Permissions and Management)
13. Click Stop Inheriting Permissions (click ok to pop up)
14. Check {Site Name} Members and {Site Name} Visitors
15. Click Remove User Permissions (in PERMISSIONS tab in top ribbon), confirm the prompt
16. Click Documents on the left side
17. Copy and note sharepoint URL in browser address bar (will be used later in the setup and in provisioning additional Vaults)

Step 4 Grant Application Access

The Sites.Selected Entra ID application permission specifies the SharePoint sites to which your Entra ID application has access. This permission is only configurable via powershell script and 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 (Basics_SitePnP_Update.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.

To grant application access:

1. Use the Basics_SitePnP.ps1 script to create the Admin Application and grant permissions to the Application for site access.

2. Prior to running the script:

   • Ensure the Administrator executing the script has admin access to Existing Veeva Collaborative Authoring sharepoint site and Administrator access to Entra
   • Install PowerShell 7.0

     1	winget install --id Microsoft.PowerShell --source winget

   • Install PnP module in PowerShell 7 by running PowerShell 7 and executing the following command

     1	Install-Module PnP.PowerShell -RequiredVersion 2.12

   • Confirm PnP.PowerShell module 2.12 is installed by running:

     1	Get-Command -Module PnP.PowerShell

 - Populate the following variables in the script:

   1. Get adminDomainUrl by going to Sharepoint Admin Center and getting the domain of your URL
      ```powershell
      $adminDomainUrl = "client-admin.sharepoint.com"
      ```
   2. Get siteDomainUrl by going to any Active Site > Click on site > get Domain existing site in Sharepoint and getting the domain of that site
      ```powershell
      $siteDomainUrl = "client.sharepoint.com"
      ```
   3. Get from Entra Admin Center > Home > Primary domain
      ```powershell
      $primaryDomain = "domain.com"
      ```
   4. Get by going to Entra app registration Veeva Vault Collaborative Authoring > Overview > Application (client) ID
      ```powershell
      $appId = "xxx-xxx-xxx-xxx"
      ```
   5. Get by going to Entra app registration Veeva Vault Collaborative Authoring > Overview > Display name
      ```powershell
      $displayName = "Veeva Vault Collaborative Authoring"
      ```
   6. Get created sharepoint site URL by going to Shareoint Admin Center > Site > Active Sites > Find your Vault Site > Site Address -- copy the full site Address
      ```powershell
      $siteUrl = "https://test.sharepoint.com/sites/siteAlias"
      ```

3. Ensure the person executing Basics_SitePnP.ps1 script is added as the owner of the share point site used by Collaborative Authoring.

   • SharePoint Admin Center > Site > Active Sites > Find your Vault Site > Membership

4. Once step 2 is completed, execute the script Basics_SitePnP.ps1. You will have multiple prompts to authenticate.

   Note

   If the script returns an error because it is not signed, you can resolve it using either Windows Explorer or Command Line:

   • Via Windows Explorer: Right click on the script > Properties > General tab > Security section. If the file is blocked, you will see a checkbox labeled Unblock. Check the unblock checkbox.
   • Via Command Line:

     1	powershell -ExecutionPolicy Bypass -File "C:\Path\To\Your\Script\Basics_SitePnP.ps1"

Step 5: 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.

Optional External User Collaboration Setup

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.

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.

Enablement in Additional Vault(s)

1. Login as Admin to Azure Active Directory

2. Navigate to Home > App Registrations

3. Find App Registration Veeva Vault Collaborative Authoring

4. From Veeva Vault Collaborative Authoring Page Click Authentication

5. Click Add a platform

6. Select Web as the Application Type

7. Enter your Vault’s Redirect URL as follows: https://{Your Vault DNS}/ui/clientTiles/office365/oauth2

   e.g.: https://yourdomain-clinical.veevavault.com/ui/clientTiles/office365/oauth2

8. Click Configure to save the changes

9. Follow instructions above for Connecting Your Vault to Your Office 365 Account for additional Vault Setup

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

Download the script .ZIP file.

• Basics_SitePnP.ps1: This script is intended for sites that are configuring collaborative authoring for the first time. It grants your Entra ID application access to the created SharePoint team site using the Sites.Selected app permission.