Skip to content

Microsoft SharePoint Storage Provider

The Microsoft SharePoint storage provider is an optional, separately licensed Clarive feature that enables storing topic attachments and binary assets directly in Microsoft SharePoint Online. It uses the Microsoft Graph API to manage files in a SharePoint site's document library.

Note: This is a paid add-on feature. The mssharepoint module must be installed for the MSSharePointSite resource type to be available.

Prerequisites

Before configuring the SharePoint provider, you need:

  • A Microsoft 365 tenant with SharePoint Online
  • An Azure AD (Entra ID) App Registration with the required permissions
  • The SharePoint Site ID (and optionally a Drive ID)
  • The mssharepoint module installed in your Clarive instance

Azure AD App Registration

Register an application in Azure AD to allow Clarive to access SharePoint:

  1. Go to Azure Portal → Azure Active Directory → App registrations
  2. Click New registration and provide a name (e.g., "Clarive SharePoint Integration")
  3. Under Certificates & secrets, create a new Client secret and copy the value immediately
  4. Under API permissions, add the following Application permissions for Microsoft Graph:
  5. Sites.ReadWrite.All
  6. Files.ReadWrite.All
  7. Click Grant admin consent for the permissions
  8. Note down the following values:
  9. Tenant ID (from the Overview page)
  10. Application (client) ID (from the Overview page)
  11. Client secret value (from step 3)

Finding Your Site ID and Drive ID

Use the Microsoft Graph API to obtain the SharePoint identifiers.

Site ID

curl -H "Authorization: Bearer <access_token>" \
  "https://graph.microsoft.com/v1.0/sites/<tenant>.sharepoint.com:/sites/<site-name>"

The response includes an id field — this is your Site ID.

Drive ID

curl -H "Authorization: Bearer <access_token>" \
  "https://graph.microsoft.com/v1.0/sites/<site-id>/drives"

Each entry in the value array has an id field. Use the one that corresponds to the document library you want. If you only have one library, you can leave Drive ID set to root.

Creating the SharePoint Resource

  1. Navigate to Resources in the Clarive UI
  2. Click New to create a new resource
  3. Select MSSharePointSite from the resource type list
  4. Fill in the configuration fields:
Field Required Description
Active No Enable or disable the provider. Defaults to enabled.
Tenant ID Yes Your Microsoft 365 / Azure AD tenant identifier.
Client ID Yes The Application (client) ID from the Azure AD App Registration.
Client Secret Yes The client secret value from the App Registration. Stored encrypted.
Site ID Yes The SharePoint site identifier obtained from the Graph API.
Drive ID No The document library drive ID. Defaults to root (the default document library).
Root Path No A base folder path. All operations will be scoped under this path.
  1. Click Save

Assigning the Provider to Fields

Once the SharePoint resource is created, assign it to topic attachment fields:

  1. Open the Category editor for the topic type you want to configure
  2. In the field configuration for an Attach Files field, set:
  3. Storage Provider — select your SharePoint Site resource
  4. Storage Folder — the folder path in SharePoint where files will be stored (e.g., /FromClarive)

Files uploaded through that field will be stored in the configured SharePoint location instead of the default GridFS.

Storage Folder Variable Substitution

The Storage Folder path supports dynamic variable substitution using ${variable} syntax. Variables are resolved from the topic data at upload time.

Examples

/Documents/${title}
/Projects/${category}
/Environments/${environment}/Projects/${project}

Variable Resolution Rules

  • Topic fields are available directly: ${title}, ${status}, ${category}
  • Fields that reference other Resources (CIs) are automatically resolved to the resource name
  • Array fields with a single value are treated as scalars
  • For array fields with multiple values, the first value is used

Example

Given a topic with: - Title: "Release v2.0" - Project: "MyProject" (a CI reference) - Environment: "Production" (a CI reference)

And a storage folder configured as: /Projects/${project}/${environment}

The resolved path will be: /Projects/MyProject/Production

How It Works

Authentication

The provider uses OAuth2 Client Credentials flow. Clarive automatically obtains and manages access tokens from Azure AD when performing file operations. No user interaction is required.

File Upload

When a user attaches a file to a topic:

  1. Clarive obtains an OAuth2 access token from Azure AD
  2. A chunked upload session is created via the Microsoft Graph API
  3. The file is uploaded in 3.2 MB chunks
  4. The SharePoint file ID is stored in Clarive's database for future operations
  5. Folder hierarchies are created automatically as needed

File Download

When a user downloads an attached file:

  1. The stored SharePoint file ID is used to request the file content
  2. The file is streamed from SharePoint through Clarive to the user
  3. Original filename and metadata are preserved

File Deletion

When an attachment is removed:

  1. The file is deleted from SharePoint using its stored ID
  2. For folders, contents are removed recursively (files first, then folders)
  3. The operation is idempotent — deleting a non-existent file does not cause an error

Features

  • Chunked uploads — large files are uploaded in 3.2 MB segments, supporting files of any size
  • Native versioning — SharePoint maintains its own file version history; previous versions are not deleted on update
  • Automatic folder creation — folder hierarchies are created on-the-fly during upload
  • Filename sanitization — invalid SharePoint characters (" * : < > ? / \ |) are automatically replaced with underscores
  • URL encoding — special characters like #, %, & are properly encoded
  • Conflict handling — if a naming conflict occurs during upload, the provider retries with replace behavior
  • Root path scoping — all operations can be scoped to a base folder, keeping Clarive files isolated
  • Shortcut support — .url shortcut files in SharePoint are automatically resolved when downloading

Rule Services

The mssharepoint module registers the following services for use in Clarive rules (Rule Designer). All services require a SharePoint Site resource to be selected.

SharePoint: Upload Files

Uploads a local file or directory to SharePoint.

  • Local Path — path to a local file or directory to upload
  • Remote Folder — destination folder path in SharePoint (default: /)

SharePoint: Download File

Downloads a file from SharePoint to a local directory. The file is saved with its original remote filename.

  • File Path or ID — the remote file path or SharePoint item ID
  • Local Destination Directory — local directory where the file will be saved
  • Keep Remote Path — when checked and using a file path (not an ID), recreates the remote directory structure under the local destination directory. For example, downloading /Reports/2024/summary.pdf with this option creates <local_dir>/Reports/2024/summary.pdf instead of <local_dir>/summary.pdf

SharePoint: List Files

Lists files and folders at a given path.

  • Path — the SharePoint folder path to list (default: /)
  • Recursive — when checked, lists contents of subfolders recursively

SharePoint: Remove File or Folder

Deletes a file or folder from SharePoint. Folders are removed recursively.

  • File Path or ID — the remote file path or SharePoint item ID to remove

Creates a .url shortcut file in SharePoint pointing to another item.

  • Source Path or ID — the item to link to
  • Destination Folder — where to create the shortcut

SharePoint: Copy File or Folder

Copies a file or folder to another location in SharePoint. Folders are copied recursively.

  • Source Path or ID — the item to copy
  • Destination Folder — target directory path

Limitations

  • Requires network connectivity from the Clarive server to the Microsoft Graph API (graph.microsoft.com)
  • The Azure AD client secret has an expiration date; it must be renewed before it expires
  • HTTP timeout per request is 300 seconds
  • Chunk size is fixed at 3.2 MB
  • Only one drive per resource configuration (use multiple resources for multiple drives)
  • Upload sessions do not survive a server restart (non-resumable)
  • Download performance depends on Microsoft Graph API response times

Troubleshooting

Authentication Errors (401 / 403)

  • Verify that the Tenant ID, Client ID, and Client Secret are correct
  • Check that admin consent has been granted for the API permissions
  • Ensure the client secret has not expired

File Not Found (404)

  • Verify the Site ID and Drive ID are correct
  • Check that the Root Path exists in SharePoint
  • If using path-based references, check for invalid characters

Upload Failures

  • Ensure the App Registration has Files.ReadWrite.All permission
  • Check that the target folder is writable
  • For large files, verify there is no proxy or firewall limiting request sizes

See Also