New Collaborate Technical Integration Overview

The New Collaborate feature utilises standard Microsoft 365 and SharePoint features, along with the associated Microsoft 365 APIs, to allow practices to:

• Create SharePoint sites (commonly referred to as "New Collaborate Sites")
• Add clients as Guest Users
• Create client-specific folders
• Manage various security permissions of files and folders

For more information on New Collaborate refer to New Collaborate Overview

This article is intended for IT professionals seeking to understand the relationship between New Collaborate and Microsoft 365, including API usage, and the activity performed in the background when using different elements of New Collaborate.

In this article, the term Guest User represents clients and contacts added to the Share Settings, or contacts when individual documents are shared.

Microsoft Entra Admin Centre Configuration Settings

FYI relies on specific settings within Microsoft Entra to successfully authenticate and manage Guest Users. 

User Administrator Role (optional)

The Microsoft 365 User Administrator allows New Collaborate to automatically delete guest users from Entra when removing guest users from the Share Settings in FYI, or a document is unshared. For more information, refer to Step 3 - Assign the User Administrator Role of Setting up Microsoft 365 for New Collaborate

Practices may have security protocols that prevent enabling this option. Without the User Administrator role assigned, FYI will only remove the guest user from the "Visitors" group on SharePoint, and not Microsoft Entra.

In this situation, a user with access to the Microsoft Entra Admin Centre must manually remove the user from Entra. It's recommended to perform this task regularly, comparing the users in the SharePoint Active User list with the Entra - All Users list. Refer to the Microsoft article Add or delete users. 

SharePoint External Settings

The SharePoint External Settings control the ability for SharePoint to invite and interact with external users not part of your organisation i.e. clients and contacts added as guest users.

Refer to Step 4 - Update SharePoint External Settings (Mandatory) in the article Setting up Microsoft 365 for New Collaborate

OneDrive Admin

Within the OneDrive App configuration settings in FYI, practices must nominate one user account to be the OneDrive Admin Account. This account is used to create and manage the SharePoint site, along with all client files and folders within.

Refer to Link your Practice's OneDrive Admin Account

The permissions required for the OneDrive Admin account are as follows:

New Collaborate Configuration Wizard

When setting up New Collaborate, the Configuration Wizard will utilise the OneDrive Admin to perform a series of tasks.

Configuration Options

The Configuration Wizard will:

• Create a New Collaborate SharePoint site. A SharePoint site within Microsoft 365 will be created based on the name entered in the New Collaborate Setup Wizard. FYI creates a Communications site in line with Microsoft recommendations when sharing content with external parties.
  
  
• Create a Document Library, used for storing client folders and files.
  
  
• Select a Microsoft Group used to manage the internal user access to the SharePoint site. The recommended group, Everyone Except External, is a specially defined Microsoft Group. If the practice chooses to limit who can access the SharePoint site, a different Entra Security Group group can be selected. Microsoft 365 Groups cannot be used.
  
  
• Select the Microsoft 365 Security list. By default, New Collaborate sets this to Guest Users, leveraging the technology of Microsoft Entra ID B2B. This simplifies the sharing process and removes the need to use Secure Links utilised in the Legacy version of Collaborate

Refer to Set up and Create a New Collaborate Site (New Sites only)

Folder Structure

The New Collaborate Configuration Wizard in FYI allows practices to define the folder structure used to contain client files on SharePoint.

The Client Name is enforced as the top-level folder to assist in the clear identification of client folders. 

The use of additional categories is optional and at the discretion of the practice.

Refer to Set up and Create a New Collaborate Site (New Sites only)

Creating the SharePoint Site

After configuring the New Collaborate Folder Structure, clicking the Next button will trigger the Microsoft API to create a new SharePoint site. 

Theme Template

A SharePoint Template created by FYI will be applied by default and can be modified as required. Refer to Customising your New Collaborate site on SharePoint

Note: The Recent Documents view is required to show any documents shared with a Guest. This is particularly important for users with access to individual documents only, and not added to the Sharing Settings in FYI i.e. unable to access client folders. Users will be unable to use the SharePoint site's navigation to access documents, and must use the Recent Documents view

SharePoint site Internal Permissions

The following permissions and group memberships will be automatically set for the following users/groups:

Sharing Settings

Guest User Account created

When an email account is added to the client Share Settings in FYI the user account/email address is created within Entra - Users with the User Type of Guest.

If sharing a document to an email address that matches the client's primary contact's email address (as displayed on the Client Summary tab in FYI), in addition to sharing the document, the email address will automatically be added to the Share Settings (if not previously added). This will create the user within Entra - Users with the User Type of Guest.

The following SharePoint permissions are managed and set for Guests when configured within Share Settings.

Upload Folder

When a client uploads a file to the Upload folder, FYI detects the file using Webhooks subscribed to the Client Upload folders.

The Webhook looks for changes to the contents, and when a change is identified the following events are triggered:

1. The document is imported from SharePoint and added to FYI.
   
   
2. Once imported, the original document is either retained or  deleted from SharePoint, depending on the Collaborate app settings in FYI.
   
   If the "Retain Client Uploads in Collaborate Site" option is set to "Yes", uploaded files will be moved to a "Processed" folder within the client's Upload folder on SharePoint.
   
   If set to "No", the files will be deleted from SharePoint after import.

The detection of new files is normally completed within 1-2 minutes, and performed using the SharePoint/Graph API.

Refer to Upload Experience for Clients using New Collaborate.

Sharing Documents

Sharing using Collaborate

When sharing individual documents with a guest user, the following actions take place:

1. A Client Folder is created in SharePoint as per the structure defined in the New Collaborate Configuration Wizard (if the folder doesn't already exist).
   
   
2. A copy of the shared document is uploaded to the relevant client folder.
   
   
3. Permissions are applied to the document:
   • If the Guest User has already been added to the Share Settings screen, the document will inherit the Read permission from the top-level client folder
   • If the Guest User does not exist in the Share Settings, and is not the Primary Contact, the document will have Read permissions applied directly on the file as a standalone permission (not inherited).
     
     
4. If sharing the Microsoft Office document as a PDF, the file will be converted to a PDF before being created in SharePoint.

Refer to Sharing Documents with Clients and External Users

Client Co-Edit

Documents can be shared via New Collaborate in Co-Edit mode, giving the client Edit access to the document while also allowing team members to work on the document at the same time.

When sharing a document in Co-Edit, the following actions take place:

1. A copy of the document is uploaded to the client folder, as per the folder structure defined in the New Collaborate Configuration Wizard.
   
   
2. The guest users selected in FYI, and the Microsoft Group selected in the New Collaborate Configuration Wizard, are assigned Edit permissions on the document. 
   
   
3. A new version is created in FYI and linked to the SharePoint file. There is no single-user lock created, allowing both internal and external parties to edit the document at the same time. Users from the practice can edit the document from the browser, desktop Microsoft Office apps, or the FYI Desktop app

Refer to Document Version History - Creating a New or Recovering a Document Version

When an FYI user clicks Finish Client Co-Editing the following actions occur:

1. FYI will poll the file to check when it was last modified.
   
   • If the document was modified in the last 30 seconds, an error message is displayed "File in use - Can't finish Co-edit"
   • If it was modified more than 30 seconds ago, FYI will sync the final version back to the Documents are in FYI as a new version of the original document.
     
     
2. The file is deleted from SharePoint.

Removing Sharing

Removing a user from Share Settings

When a guest user is removed from the Share Settings in New Collaborate, the following actions occur:

1. The account is removed from both the Upload folder and the client-specific folder in SharePoint.
   
   
2. A check is performed whether any other clients have been shared with this email address for the guest user account.
   • Yes - the guest user account remains, and is only removed from this particular client.
   • No - the guest user account is deleted from the SharePoint Site Collection, and then attempt to delete the guest user from Microsoft Entra (depending on the User Administrator Role settings). If the guest user cannot be deleted, an event will be added to Practice Activity with a link to the relevant Help article. 
     
     
3. Access to any documents which have been shared as Co-Edit will be removed for this guest user. The document will still be available for Co-Edit by other users.

Delete Sharing

When the Delete Sharing option is selected on the Share Settings window in FYI all guest users and documents shared are removed. The following actions take place:

1. The Client Folder is deleted from SharePoint, including all documents contained within the folder. The source files stored in FYI are not impacted.
   
   
2. Each email address on the Share Settings window is reviewed to determine if they have been assigned to any other Client Share Settings in FYI. 
   • Yes - the guest user account remains and is only removed from this particular client.
   • No - the guest user account is deleted from the SharePoint Site Collection, and then attempt to delete the guest user from Microsoft Entra (depending on the User Administrator role). If the guest user cannot be deleted, an event will be added to Practice Activity with a link to the relevant Help article. 

New Collaborate Status Check

New Collaborate App

The New Collaborate Status Check tool has been designed to assist in verifying the core setup requirements are in place, to allow FYI to interact with SharePoint as expected.

The following checks are performed:

• The practice's OneDrive Admin is connected and has a valid login token.
• The Microsoft 365 permissions have been granted for the Practice OneDrive Admin user.
• The SharePoint Site exists and is connected.
• The Document Library exists.
• The OneDrive Admin is an Owner of the specified SharePoint site.
• The Microsoft Group is a member of the Members Group at the SharePoint Site level and has Read permissions set on the specified Document Library.

For assistance in resolving any detected errors refer to the articles in the Troubleshooting section New Collaborate Status Check

To confirm clients can be created and documents can be uploaded:

1. An attempt will be made to create a test guest user account, Luke Skywalker, in Entra.
   
   
2. If successful, a test client folder will be created in the Document Library with the guest user assigned Direct Access.
   
   
3. If both tests are successful, the test folder will be deleted and the guest user will be removed from the SharePoint Site collection. Depending on the User Administrator role setting, the guest user will be deleted from Entra.
   
   
4. If all tests pass, all Webhooks will be resubscribed to all client folders.

If any of the tests fail, on-screen error messages and links to Help articles will be displayed.

Guest User Account

When a client has already been added as a Guest User via the Share Settings in FYI, an additional Status Check is available for each account. 

The following checks are performed:

• Check the guest user account exists in Entra. Attempts will be made to recreate the account if it doesn't exist.
• Validate the guest user account exists in SharePoint, is a member of the Visitors group, and has been assigned to the Client Folder.
• Confirm the correct permissions have been applied to the Client folders.
  • Read permission at the client folder level (inherited by underlying folders).
  • Write permission for the Upload folder.