Link your Xakia matters directly to folders in SharePoint Online.
This article includes:
It also outlines each function of the Xakia SharePoint Online integration and how each function can be configured in the SharePoint Online configuration page in Xakia.
Once your SharePoint Online integration has been set up, it will automatically link any new matter to SharePoint Online by creating a folder in SharePoint Online that corresponds to the Matter in Xakia.
Any updates to Xakia matters are automatically pushed through to the SharePoint Online folder as well.
This can be seen as follows:
- Create a matter and click 'Save'
- Once saved, click on the SharePoint Online icon on the core matter form
- A slide-out will appear showing the status of the link to SharePoint Online. When the link completes, the slide-out will display an 'Open in SharePoint Online' button which can be clicked on to take you directly to the SharePoint Online folder.
Any updates to the matter in Xakia will automatically be reflected on the folder in SharePoint Online. For example, if you change the name of the matter in Xakia and then save, a few moments later the name of the folder in SharePoint Online will have been updated accordingly.
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.
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'
You will need to complete the following steps under each of the relevant tabs displayed:
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 to use when creating and updating folders in SharePoint Online. See the 'Folder Naming Convention' section below for more details.
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 the confidential group in SharePoint Online. It is expected that administrators will need to maintain the group membership accordingly.
Folder Naming Convention
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
The Authentication tab of the SharePoint Online configuration page in Xakia allows for two separate mechanisms for authenticating to SharePoint Online: Add-In or Azure Active Directory.
The recommended approach is to use Azure Active Directory, because it is very easy to set up and maintain.
The key difference between the two authentication mechanisms is that Azure Active Directory can only grant access to the entire SharePoint Online tenant, whereas an 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:
Setting up a SharePoint Online add-in is a much more complex option, hence we recommend using 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.
Azure Active Directory Authentication:
The Azure Active Directory authentication model is the recommended approach.
To set it up you will require a user with Global Administrator privileges in your tenant.
To set it 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.
The Add-in authentication model is more complex and should only be used in scenarios where the tenant-wide access of the 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.
Add-ins can be registered in SharePoint Online with the following steps:
- 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.
- Generate a Client ID and Client Secret and give the add-in a suitable name
- Under App Domain enter app.xakiatech.com
- Under Redirect URI enter https://app.xakiatech.com
- Click 'Create'
- 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 it 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:
- In a web browser, navigate to <site collection url>/_layouts/15/AppInv.aspx
- Enter the Client ID of the add-in you generated above in the 'App Id' field and click 'Lookup'
- 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:
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.
Fields from a matter can be copied into custom site columns on the folder in SharePoint Online, allowing you to search for Xakia matter metadata from 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
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.
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.
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:
- URL: https://xakiatech.sharepoint.com/sites/sales/leads
- 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.