All Collections
Integrations
Document Management Systems
SharePoint Online
SharePoint Online
Updated over a week ago

Link your Xakia matters directly to folders in SharePoint Online.

Once your SharePoint Online integration has been set up, corresponding folders will automatically be generated in SharePoint Online for all new matters created in Xakia. Any updates made to a matter in Xakia will automatically be pushed to this SharePoint Online folder.

This article explores:

SharePoint Functionality

The diagram below shows a high-level overview of how Xakia and SharePoint interact:

xakia-sharepoint-online-flow.jpg

Setting up SharePoint

Follow the steps below to set up your SharePoint:

  • Click on 'Admin' in the top navigation bar

  • Select 'Integrations' from the left -hand menu

  • Select 'Document Management'

  • From the 'Provider' dropdown, select 'SharePoint Online'

To complete the integration, the following steps are required:

General Settings

Root Site Collection URL

This is the URL of the root site collection of your SharePoint Online tenant. It will be in the form of "https://<your-tenant-name>.sharepoint.com/".

Confidential Group Name

This is the name of the Group in SharePoint Online that will be granted access to any folders that correspond to confidential matters in Xakia. This field is optional, and a name can be provided if desired. See the 'Permissions' section below for more details.

Note: If multiple site collections are used, a group with this name is assumed to exist in each site collection that is used by the Xakia SharePoint Online integration.

Folder Name Format

This is the folder naming convention which will be used when creating and updating folders in SharePoint Online. See the 'Folder Naming Convention' section below for more details.

Permissions

Non-confidential matters in Xakia will create folders in SharePoint Online that simply inherit permissions from the parent object. Xakia does not apply any further permissions to the folder for these matters.

Confidential matters in Xakia will create folders in SharePoint Online with unique permissions. Role inheritance will be broken for these matters, and Xakia will explicitly assign roles for the matter manager and any team members from the Xakia matter to the SharePoint Online folder.

Confidential matters also have a special SharePoint Online group assigned to them in order to allow any users with 'All Matters including Confidential' access to the confidential folders in SharePoint.

Note: There is no feature available to automatically sync users from Xakia with 'All Matters including Confidential' access in Xakia to confidential groups in SharePoint Online. It is expected that administrators will to maintain the group membership accordingly.

Folder Naming Conventions

The name used for folders in SharePoint Online can be selected based on one of the following conventions:

  • Matter Name

  • Division Name - Matter Name

  • Subcategory Name - Matter Name

  • Matter Name - Subcategory Name

  • Matter Name - Division Name

  • Matter Name - Subdivision Name

  • Matter Name - Category Name

  • Matter Name - Division Name - Category Name

  • Matter Name - Subcategory Name - Matter Number

  • Matter Number - Matter Name

  • Category Name - Matter Name - Matter Number

  • Matter Number

  • Matter Name - Matter Number

  • Division Name - Matter Name - Matter Number

  • Group Name - Matter Name - Matter Number

  • Subdivision Name - Matter Name

Authentication

The Authentication tab of the SharePoint Online configuration page in Xakia allows for two separate mechanisms for authenticating to SharePoint Online: SPO Add-In, or Microsoft Entra (formerly known as Azure Active Directory).

The recommended approach is to use Microsoft Entra/Azure Active Directory, because it is very easy to set up and maintain.

The key difference between the two authentication mechanisms is that Microsoft Entra/Azure Active Directory can only grant access to the entire SharePoint Online tenant, whereas an SPO Add-In can grant access to a specific set of resources in a tenant, such as a single site.

This is illustrated in the below diagram:

mceclip0.png

Setting up a SharePoint Online Add-In is a much more complex option; hence we recommend using Microsoft Entra/Azure Active Directory wherever possible. The only scenario where an Add-In should be used is when there is a requirement to only allow access to a specific set of resources.

Microsoft Entra/Azure Active Directory Authentication

The Microsoft Entra/Azure Active Directory authentication model is the recommended approach. Setup will require a user with Global Administrator privileges in your tenant.

To set up:

  • Select 'Azure Active Directory' from the 'Authentication Mode' drop-down box

  • Click the 'Get the App' button

  • You will be prompted to sign in with a Microsoft account - sign in with a Global Administrator user

  • You will then be prompted to grant consent to our App, which will access your SharePoint Online resources

  • Once the flow is completed you will be taken back to Xakia.

Add-in Authentication

The Add-In authentication model is more complex and should only be used in scenarios where the tenant-wide access of the Microsoft Entra/Azure Active Directory authentication approach is not acceptable. The Add-In authentication model uses the add-in-only policy of the SharePoint Add-Ins model. More details on this model can be found here.

Note: Microsoft have announced plans to deprecate the Add-In feature of SharePoint Online. This means that Add-Ins are fully supported and will continue to function as expected, however Microsoft are no longer engaging in updating the feature. The Add-In authentication approach is still a supported authentication mechanism by Xakia and Microsoft.

When Microsoft announce an end-of-life date for Add-Ins, alternative authentication approaches will be evaluated, and guidance will be provided to you from Xakia on how to migrate away from Add-Ins.

New SharePoint Online tenants have add-in authentication disabled by default. This can be enabled by a SharePoint Online admin using a this PowerShell command.

Please note that the user completing the following steps must have site collection administrator permissions on the site collection.

Add-Ins can be registered in SharePoint Online with the following steps:

  1. In a web browser, navigate to <site collection url>/_layouts/15/AppRegNew.aspx
    For example, if your SharePoint Online root site collection was https://example.sharepoint.com/, you would navigate to https://example.sharepoint.com/_layouts/15/AppRegNew.aspx.

  2. Generate a Client ID and Client Secret and give the add-in a suitable name

  3. Under App Domain enter app.xakiatech.com

  4. Under Redirect URI enter https://app.xakiatech.com

  5. Click 'Create'

  6. You will be shown a page that summarizes the information that was saved. Be sure to save this information for later reference.

The SharePoint Online Add-In has been created, but we still need to grant it permission to access resources in SharePoint Online.

Which resources you grant the Add-In access to is up to you - you may choose to grant full access to the entire tenancy, or restrict access to certain lists. The authorization can be configured with the following steps:

  1. In a web browser, navigate to <site collection url>/_layouts/15/AppInv.aspx

  2. Enter the Client ID of the add-in you generated above in the 'App Id' field and click 'Lookup'

  3. Enter the desired Permission Request XML in the box at the bottom of the form. The exact permission XML will vary depending on your requirements. For example, to grant access to the whole site collection, use the following:

<AppPermissionRequests AllowAppOnlyPolicy="true">
<AppPermissionRequest Scope="http://sharepoint/content/sitecollection"
Right="FullControl" />
</AppPermissionRequests>

The AllowAppOnlyPolicy="true" attribute is required for the integration to function correctly. Note that the integration requires the "FullControl" right to be granted in order to function correctly.

A useful reference for various permission configurations can be found here.

Once an Add-In is configured in SharePoint Online, the following details of the Add-In need to be provided to the Xakia SharePoint Online Integration:

* Client Id
* Client Secret

For the App URL field, enter https://app.xakiatech.com

Note: When using the Add-In Authentication model, the Client Secret will expire 12 months after the Add-In is created and the Add-In will no longer be able to authenticate. The Add-In needs to be re-created every 12 months to work around this constraint.

Field Mapping

Fields from a matter can be copied into custom site columns on a folder in SharePoint Online, allowing you to search for Xakia matter metadata in SharePoint Online.

The following fields can be mapped to custom site columns:

  • Matter Number

  • Matter Name

  • Matter Description

  • Division Name

  • Sub-division Name

  • Category Name

  • Sub-category Name

  • Group Name

  • Matter Hyperlink

  • Matter Status

  • Internal Contact

  • Confidential

The field mapping can be configured in the 'Field Mapping' tab of the SharePoint Online configuration page in Xakia. Enter the name of a column in SharePoint Online alongside the desired matter metadata field and save. For example, if you configure the Matter Number field to go to a site column called 'Xakia Matter Number', the integration will populate the value of the 'Xakia Matter Number' column on the folder in SharePoint Online with the matter number of the corresponding matter.

Note: The Xakia SharePoint Online integration currently requires the same field mapping configuration on all Document Libraries in use. It is not possible to configure a different field mapping configuration for each Document Library.

Folder Placement

A system of rules is used to determine where in SharePoint Online a folder should be created for a matter. For example, you could configure a rule like "If the matter Group is 'Litigation', then create the folder in the 'Disputes' Document Library in the 'Litigation' site collection". There can be as many rules as required to customize your integration.

The Folder Placement rules can be configured in the 'Folder Placement' tab of the SharePoint Online configuration page in Xakia. Folder Placement rules are evaluated from top to bottom and if no rules are matched, then the destination specified in the 'Otherwise' clause is used.

Note: When specifying the destination for a folder, this is done with two separate fields. The first is the URL to the site or subsite, and the second is the path to the Document Library or folder.

mceclip1.png

For example, if the tenant was xakiatech.com, and there was a site called Sales, and it had a subsite called Leads, and this subsite contained a document library called Contracts, and the intention was to have the integration create folders in the Contracts document library, then the destination would be configured like so:

The folder placement rules are only evaluated when a matter is first linked to SharePoint Online - i.e., when the matter is first created. If any of the matter fields change, the folder is not moved to a different location.

Note: The Xakia SharePoint Online integration will overwrite any changes made to a folder made by end users. Therefore, we encourage users to use Xakia as the source of truth for matter names, metadata, and permissions, and treat SharePoint Online as a read-only store for matter metadata.

Note: The Xakia SharePoint Online integration does not support renaming or restructuring of sites, document libraries or folders in SharePoint Online. Xakia refers to a linked folder by its path in SharePoint Online - therefore, if any element of the path changes in SharePoint Online, Xakia cannot locate the folder and will be unable to update it.

Did this answer your question?