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.
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.
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.
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.
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.
Confidential matters can also have a SharePoint Online group assigned to them that maps to the Xakia group that the matter belongs to. Users with 'Group Matters including Confidential' access can be assigned to the SharePoint Online group in order to grant them access to the confidential folders in SharePoint.
Note: Entra ID security groups and Microsoft 365 groups are not supported. The groups specified above can only be SharePoint Online groups.
Note that when Xakia breaks role inheritance on confidential folders, this does not stop administrators or owners from being able to access the folder in SharePoint Online. If you can still see confidential content in SharePoint Online that you should not have access to, check if you are a member of an administrators or owners group in SharePoint Online.
Note: There is no feature available to automatically sync users from Xakia with 'All Matters including Confidential' access in Xakia to the confidential group in SharePoint Online. It is expected that administrators will need 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
Allow filing from Outlook
If you have the SharePoint Online integration set up and the Outlook Add-in then you can transfer email metadata to SharePoint Online.
Authentication
The Authentication tab of the SharePoint Online configuration page in Xakia allows you to authenticate to SharePoint Online using Microsoft Entra ID. Authenticating Xakia to your SharePoint Online tenant is a once-off process where your Entra ID Global Administrator grants access to the Xakia Application. The Entra ID Global Administrator will then need to authorize each Site Collection in SharePoint Online that Xakia needs to access. Note that Xakia does not require access to all Site Collections in the tenant - you authorize only the Site Collections that you require.
Setting up the authentication to SharePoint Online 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
The following screenshot indicates the permissions that the Entra ID App requires in your SharePoint Online tenant
Once the flow is completed you will be taken back to Xakia
Your SharePoint Online Site Collection Administrator needs to authorize each Site Collection to the Xakia App. This can be accomplished using the below PowerShell script.
Substitute the value of $siteUrl variable with the URL of the Site Collection in your SharePoint Online tenant that you want Xakia to access. Substitute $tenant with your tenant URL.
The script will need to be run once for each Site Collection that you want to authorize.
Please verify that you are using PowerShell 7. You can use the
$PSVersionTablecommand to see which version of PowerShell is open.Before running the below PowerShell script, ensure you have the PnP.Powershell module installed. To install, use the PNP.PowerShell Module install command:
Install-Module PnP.PowerShell -Scope CurrentUser
This script performs the following actions:
It creates an App Registration in your Entra ID tenant. This App Registration is used by the rest of the script to authorize the Xakia application to access the desired site collection. This App Registration is temporary and can be deleted when the script completes.
You will be shown a login window with a prompt that reads "Enter code to allow access". The required code is already copied to your clipboard, you can paste the code and click Next.
You will then be prompted to sign in. Sign in with your Global Administrator account.
You will then be shown a prompt that reads "Are you trying to sign in to Microsoft Azure PowerShell?" Click Continue.You can then close the login window so that the script can continue to run.
After 30 seconds, you will be shown another login window. Sign in with the same Global Administrator account you signed in with above.You will be prompted to grant consent to an Entra ID app. Click Accept.
The login window will close automatically and the script will continue.The script will now authorize the Xakia application to access the desired site collection.
Please note that when the script terminates, the App Registration created in Step 1 is not automatically removed. You will need to open App Registrations in your Entra ID tenant and manually remove the App Registration called "Xakia PnP DeleteMe".
Powershell script
Powershell script
### Enter the URL of the SharePoint Online Site Collection that
### you want to authorize the Xakia SharePoint Online App to access
$siteUrl = "https://contoso.sharepoint.com/sites/YourSite"
$tenant = "contoso.onmicrosoft.com"
################################
# App ID of the Xakia SharePoint Online App in Entra ID
$appId = "501238e9-d4a7-4fa5-af22-23f4370d57f4"
$registrationDetails = Register-PnPEntraIDApp -ApplicationName "Xakia PnP DeleteMe" -Tenant $tenant -OutPath C:\mycertificates -DeviceLogin -SharePointApplicationPermissions "Sites.FullControl.All","User.Read.All" -GraphApplicationPermissions "User.Read.All","Sites.FullControl.All"
Start-Sleep -Seconds 30
Connect-PnPOnline $siteUrl -ClientId $registrationDetails[0].'AzureAppId/ClientId' -Tenant $tenant -CertificateBase64Encoded $registrationDetails[0].Base64Encoded
#First create a Read or Write permission entry for the app to the
#site. Currently unable to Set as FullControl
$grant = Grant-PnPAzureADAppSitePermission -Permissions "Write" -Site $siteUrl -AppId $appId -DisplayName "SitesResourceSpecific"
#Get the Permission ID for the app using App Id
$PermissionId = Get-PnPAzureADAppSitePermission -AppIdentity $appId -Site $siteUrl
#Change the newly created Read/Write app site permission entry to
#FullControl
Set-PnPAzureADAppSitePermission -Site $siteurl -PermissionId $(($PermissionId).Id) -Permissions "FullControl"
Note: If you run the above script and it errors, or hangs or does not complete, this may be occurring due to a bug in Microsofts PnP.Powershell module. You can work around this by running
Uninstall-Module PnP.PowerShell
Install-Module PnP.PowerShell -AllowPrerelease -SkipPublisherCheck -Force
and then run the above script again.
Note: there is also an option to authenticate to SharePoint Online using SPO Add-Ins. Microsoft has announced plans to deprecate SPO Add-Ins. SPO Add-Ins exists as an authentication method in Xakia as a legacy option only. We strongly recommend using Microsoft Entra ID for authentication to SharePoint Online.
Field Mapping
The Xakia SharePoint Online integration supports an optional field mapping feature. Field values from a Xakia matter can be copied into columns on a linked folder in SharePoint Online. This allows you to search for these Xakia values in SharePoint Online.
Example: if you configure the 'Category Name' field to go to a site column called 'Category', the integration will populate the value of the 'Category' column in SharePoint Online folder with the category of the corresponding matter. You can then search for Xakia category names from within SharePoint Online.
Field mapping is entirely optional; you do not need to set up any mapped fields if you do not require them.
You need to set up the required columns in SharePoint Online manually; the integration does not automatically create the columns. You can add a column directly to the Document Library, or you can use SharePoint site columns. Note that the type of the column must be "Single line of text".
The following fields can be mapped to custom site columns:
Matter Name
Matter Number
Matter Manager
Division Name
Sub-Division Name
Category name
Sub-Category name
Group Name
Matter Hyperlink
Matter Status
Internal Contact
Confidential
Note: To search the metadata for attachments we recommend using the title 'Has Attachments' for the column. Please avoid using the column name "Attachments" in your field mappings. SharePoint treats the column named "Attachments" as read-only. If you try to specify a mapping to a column named "Attachments" this will result in none of the metadata being mapped.
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
The Xakia SharePoint Online integration gives you a great deal of flexibility and control over where folders for Xakia matters get created in SharePoint Online. You can create a set of rules that tells the integration where to create folders in SharePoint Online. This feature allows you to integrate Xakia with existing SharePoint Online systems.
Example: You can set up a rule that links matters with category 'Administration' to one location in SharePoint, and then another rule that links matters with category 'Contract & Commercial' to a different location in SharePoint. 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.
If all you require is for all your Xakia matters to go to the same place in SharePoint Online, then you do not need to worry about creating rules. You can simply set up the default location in the 'Otherwise' section - all your Xakia matters will create folders in this location.
How to create Folder Placement Rule
Under the 'Folder Placement' tab click 'Add New Folder Placement Rule'
Select a component from the dropdown menu
Select either 'Equals' or 'Does not equal'
Select the relevant component input
Enter the SharePoint Online URL for the desired location
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.
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:
Folder Path: Contracts
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.
How to Create a Document Library in SharePoint
If you are looking to create a new Folder Path for Xakia Matters, it is recommended to either create a new Document Library within SharePoint or use a folder within an existing Document Library.
To create a Document Library, login to your SharePoint site,
Navigate to 'Site Contents'
Click the 'New' button
Select Document Library and follow the on-screen steps to create the library. Use the library name as the folder path when configuring your Folder Placement Rules within Xakia.
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.