Overview

The SharePoint Connector for Mendix enables your application to integrate

with Microsoft SharePoint Online using the Microsoft Graph API and OAuth2

client credentials. No user login is required — the connector authenticates

as your registered Azure application, making it suitable for automated

workflows and server-side operations.

SECURE BY DESIGN — SITES.SELECTED PERMISSION MODEL

this connector uses Microsoft's recommended Sites.Selected permission. With Sites.Selected,

your app has zero access to any SharePoint content until a SharePoint

administrator explicitly grants it access to a specific site — one site

at a time.

WHAT IT DOES

Once configured, the connector provides five core operations:

- List Files — retrieve all files from any SharePoint folder and display

them in a Mendix data grid

- Upload Files — send any Mendix FileDocument to a specified SharePoint

folder (up to 4 MB)

- Download Files — pull a file from SharePoint into a Mendix FileDocument

for viewing or further processing

- Delete Files — permanently remove a file from SharePoint by item ID

- Create Folders — build new folder structures in your document library

WHAT'S INCLUDED

The connector ships with a ready-made File Browser page (SP_FileBrowser)

with Upload, Download, Delete, Create Folder, and Refresh out of the box

— no extra configuration needed for a working UI.

A Configuration page lets you enter your Azure credentials and test the

connection with one click. An operation log entity automatically records

every action taken, giving you a full audit trail.

SETUP SUMMARY

1. Register an app in Azure Portal and grant Sites.Selected as an

Application permission with admin consent

2. Install this connector from the Marketplace

3. Use Graph Explorer to run a one-time POST granting your app access

to your specific SharePoint site only

4. Enter your Tenant ID, Client ID, Client Secret, Site ID, and Drive ID

in the Configuration page

5. Click Test Connection — done

The included README provides the exact Graph API request body needed for

the site access grant and step-by-step instructions for each setup stage.

REQUIREMENTS

- Mendix Studio Pro 9.18 or higher

- Microsoft 365 tenant with SharePoint Online

- Azure App Registration with admin-consented Sites.Selected permission

- SharePoint administrator access to run the site permission grant

USE CASES

Contract management, HR document portals, project file repositories,

invoice archiving, compliance document systems, and any application

requiring secure centralised file storage in SharePoint.

Documentation

# SharePoint Connector for Mendix

Connect your Mendix application to Microsoft SharePoint Online and perform file operations — upload, download, delete, list files, and create folders — using the Microsoft Graph API.

> **Security model:** This connector uses `Sites.Selected` (Application permission) which scopes access to **only the specific SharePoint site you designate**. Your app cannot read or write any other site in your tenant. This follows Microsoft's recommended approach for production integrations.

---

## Table of Contents

- [Prerequisites](#prerequisites)

- [Step 1 — Register an Azure App](#step-1--register-an-azure-app)

- [Step 2 — Install the Connector](#step-2--install-the-connector)

- [Step 3 — Configure the Connector](#step-3--configure-the-connector)

- [Step 4 — Find Your Site ID and Drive ID](#step-4--find-your-site-id-and-drive-id)

- [Step 5 — Grant Site-Level Access to Your App](#step-5--grant-site-level-access-to-your-app)

- [Step 6 — Test the Connection](#step-6--test-the-connection)

- [Available Actions](#available-actions)

- [Using the File Browser Page](#using-the-file-browser-page)

- [Using Actions in Your Own Microflows](#using-actions-in-your-own-microflows)

- [Domain Model Reference](#domain-model-reference)

- [Security Design](#security-design)

- [Troubleshooting](#troubleshooting)

---

## Prerequisites

Before installing the connector you need:

- A Mendix app running on **Mendix 10.24.2 or higher**

- A **Microsoft 365 / Azure Active Directory tenant** (a work or school account — not a personal Microsoft account)

- A **SharePoint Online site** already created

- Global Administrator or Application Administrator access to your Azure tenant (to grant API permissions and run the site-access grant)

---

## Step 1 — Register an Azure App

The connector authenticates using **OAuth2 client credentials** (app-to-app, no user login required). You must register an app in Azure AD.

### 1.1 — Create the App Registration

1. Go to **https://portal.azure.com**

2. Click **Microsoft Entra ID → App registrations → New registration**

3. Fill in:

- **Name:** `MendixSharePointConnector` (or any name you prefer)

- **Supported account types:** `Accounts in this organizational directory only`

- **Redirect URI:** leave blank

4. Click **Register**

5. Copy and save from the Overview page:

- **Application (client) ID** → your `Client ID`

- **Directory (tenant) ID** → your `Tenant ID`

### 1.2 — Create a Client Secret

1. Click **Certificates & secrets → New client secret**

2. Enter a description and choose an expiry period

3. Click **Add**

4. **Immediately copy the Value** — it is only shown once

- This is your `Client Secret`

### 1.3 — Grant API Permission (Sites.Selected only)

> ⚠️ Use **only** `Sites.Selected`. Do not add `Sites.ReadWrite.All` or `Files.ReadWrite.All` — those grant access to your entire tenant which is a serious security risk.

1. Click **API permissions → Add a permission → Microsoft Graph → Application permissions**

2. Search for `Sites.Selected` → tick it → click **Add permissions**

3. Click **Grant admin consent for [your organisation]** → confirm

4. Verify it shows ✅ **Granted** next to `Sites.Selected`

`Sites.Selected` alone gives the app **no access to anything** until you explicitly grant it access to a specific site in Step 5. This is by design.

---

## Step 2 — Install the Connector

1. Open your Mendix app in **Studio Pro**

2. Click the **Marketplace** icon → search **SharePoint Connector**

3. Click **Download** — Studio Pro imports all module files automatically

### What Gets Added

| Item | Type | Purpose |

|---|---|---|

| `SPConfig` | Entity | Stores Azure and SharePoint credentials |

| `SPFile` | Entity | Represents a file in SharePoint |

| `SPFolder` | Entity | Represents a folder in SharePoint |

| `SPOperationLog` | Entity | Logs all connector operations |

| `SPUploadHelper` | Entity | Temporary object used by the upload popup |

| `SPFolderHelper` | Entity | Temporary object used by the create folder popup |

| `SP_Configuration` | Page | Configuration form |

| `SP_FileBrowser` | Page | File browser with upload, download, delete, create folder |

| `ACT_SP_ListFiles` | Microflow | Lists files from SharePoint |

| `ACT_SP_UploadFile` | Microflow | Uploads a file to SharePoint |

| `ACT_SP_DownloadFile` | Microflow | Downloads a file from SharePoint |

| `ACT_SP_DeleteFile` | Microflow | Deletes a file from SharePoint |

| `ACT_SP_CreateFolder` | Microflow | Creates a folder in SharePoint |

| `ACT_SP_TestConnection` | Microflow | Tests the SharePoint connection |

---

## Step 3 — Configure the Connector

### 3.1 — Add Pages to Navigation

1. Open your app's **Navigation**

2. Add a menu item pointing to `SharePointConnector.SP_Configuration`

3. Add a menu item pointing to `SharePointConnector.SP_FileBrowser`

### 3.2 — Set the After Startup Microflow

1. Go to **App → App Settings → Runtime tab**

2. Set **After startup** to `SharePointConnector.ASu_InitializeConfig`

3. Click **OK**

### 3.3 — Add Security Roles (if your app uses security)

For each user role that should access SharePoint, grant access to the `SharePointConnector` module role under **App → Security**.

---

## Step 4 — Find Your Site ID and Drive ID

### 4.1 — Open Graph Explorer

Go to **https://developer.microsoft.com/en-us/graph/graph-explorer** and sign in with your organisation account.

### 4.2 — Grant Permissions in Graph Explorer

Click **Modify permissions** → find `Sites.Read.All` → click **Consent**.

### 4.3 — Get the Site ID

```

GET https://graph.microsoft.com/v1.0/sites/yourtenant.sharepoint.com:/sites/yoursitename

```

Copy the full `id` field from the response — it looks like:

```

yourtenant.sharepoint.com,xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

```

This is your **Site ID**.

### 4.4 — Get the Drive ID

```

GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives

```

Copy the `id` value from the drive where `"name"` is `"Documents"`. It looks like `b!abc123...`. This is your **Drive ID**.

---

## Step 5 — Grant Site-Level Access to Your App

This is the key security step. You are telling SharePoint: *"allow this specific app to access this specific site only."*

This is a one-time operation per site. It must be performed by a SharePoint administrator.

### 5.1 — Run This POST in Graph Explorer

Change the method to **POST** and use:

```

POST https://graph.microsoft.com/v1.0/sites/{your-site-id}/permissions

```

Set the **Request body** to:

```json

{

"roles": ["write"],

"grantedToIdentities": [

{

"application": {

"id": "YOUR_CLIENT_ID",

"displayName": "MendixSharePointConnector"

}

}

]

}

```

Replace `YOUR_CLIENT_ID` with your Application (client) ID from Azure Portal.

Click **Run query**. A `201 Created` response confirms success.

### 5.2 — Verify the Grant

```

GET https://graph.microsoft.com/v1.0/sites/{your-site-id}/permissions

```

Your app should appear in the list with `"roles": ["write"]`.

> **What `write` means:** The app can read, create, update, and delete files and folders on this site. If you only need read access, use `"roles": ["read"]` instead.

---

## Step 6 — Test the Connection

1. Run your Mendix app (**F5** in Studio Pro)

2. Navigate to the **SharePoint Configuration** page

3. Fill in all fields:

| Field | Value |

|---|---|

| Tenant ID | Directory (tenant) ID from Azure Portal |

| Client ID | Application (client) ID from Azure Portal |

| Client Secret | The secret value copied when creating it |

| Site ID | The comma-separated string from Step 4.3 |

| Drive ID | The `b!...` string from Step 4.4 |

| Site URL | `https://yourtenant.sharepoint.com/sites/yoursitename` |

4. Click **Save** → **Test Connection**

A successful connection checks **Is configured** ✅ and sets **Last tested date**.

---

## Available Actions

### List Files — `ACT_SP_ListFiles`

Lists all files in a SharePoint folder and stores them as `SPFile` records.

| Parameter | Type | Description |

|---|---|---|

| `FolderPath` | String | Folder path. Use `''` for the root Documents library |

**Returns:** `List of SPFile`

---

### Upload File — `ACT_SP_UploadFile`

Uploads a Mendix FileDocument to SharePoint.

| Parameter | Type | Description |

|---|---|---|

| `TargetFolder` | String | Destination folder. Use `''` for root |

| `FileDocument` | FileDocument | The Mendix file object to upload |

**Returns:** `String` — SharePoint item ID of the uploaded file

> Maximum file size: **4 MB** (simple upload)

---

### Download File — `ACT_SP_DownloadFile`

Downloads a file from SharePoint into a Mendix FileDocument.

| Parameter | Type | Description |

|---|---|---|

| `ItemID` | String | SharePoint item ID (from `SPFile.FileId`) |

| `FileDocument` | FileDocument | Empty Mendix object to receive the file |

| `FileNAme` | String | Name to assign the downloaded file |

**Returns:** `Boolean` — true if successful

---

### Delete File — `ACT_SP_DeleteFile`

Permanently deletes a file from SharePoint.

| Parameter | Type | Description |

|---|---|---|

| `ItemID` | String | SharePoint item ID (from `SPFile.FileId`) |

**Returns:** `Boolean`

> ⚠️ This permanently deletes the file. It does not go to the Recycle Bin.

---

### Create Folder — `ACT_SP_CreateFolder`

Creates a new folder in SharePoint.

| Parameter | Type | Description |

|---|---|---|

| `Parentpath` | String | Parent folder path. Use `''` for root |

| `FolderName` | String | Name of the new folder |

**Returns:** `String` — SharePoint item ID of the new folder

---

## Using the File Browser Page

`SP_FileBrowser` is a ready-made page you can add directly to your navigation.

| Button | Action |

|---|---|

| **Upload File** | Opens popup — browse for a file and upload to SharePoint root |

| **Create Folder** | Opens popup — enter folder name and optional parent path |

| **Refresh** | Reloads the file list from SharePoint |

| **Download** (Actions column) | Downloads the file in that row |

| **Delete** (Actions column) | Permanently deletes the file in that row |

---

## Using Actions in Your Own Microflows

### Upload after form save

```

1. User submits a form with a FileDocument input

2. Call ACT_SP_UploadFile:

TargetFolder = 'Submissions'

FileDocument = $YourForm/FileDocument

3. Store the returned item ID: $YourForm/SharePointItemId = $ItemId

4. Commit and show success message

```

### Download on button click

```

1. Create a new FileDocument object: $TempFile

2. Call ACT_SP_DownloadFile:

ItemID = $SPFile/FileId

FileDocument = $TempFile

FileNAme = $SPFile/FileName

3. Download file activity pointing to $TempFile

```

---

## Domain Model Reference

### SPConfig

| Attribute | Type | Description |

|---|---|---|

| `TenantId` | String | Azure Directory (tenant) ID |

| `ClientId` | String | Azure Application (client) ID |

| `ClientSecret` | String | Azure client secret value |

| `SiteId` | String | SharePoint Site ID |

| `DriveId` | String | SharePoint Drive ID |

| `SiteUrl` | String | Full SharePoint site URL |

| `IsConfigured` | Boolean | Set to true after a successful test |

| `LastTestedDate` | DateTime | Timestamp of last successful test |

### SPFile

| Attribute | Type | Description |

|---|---|---|

| `FileId` | String | SharePoint item ID — required for download and delete |

| `FileName` | String | Display name including extension |

| `FilePath` | String | Folder path within the drive |

| `FileSize` | Long | Size in bytes |

| `MimeType` | String | e.g. `application/pdf` |

| `WebUrl` | String | URL to open in SharePoint |

| `DownloadUrl` | String | Direct download URL |

| `ModifiedDate` | DateTime | Last modified timestamp |

---

## Security Design

### Why Sites.Selected?

Earlier versions of this connector (and many online tutorials) recommend `Sites.ReadWrite.All` or `Files.ReadWrite.All` as Application permissions. While these work, they grant your app access to **every SharePoint site in your entire tenant**. This bypasses Microsoft's access control layer and is not appropriate for production use.

`Sites.Selected` follows Microsoft's recommended approach:

| Permission | What it can access |

|---|---|

| `Sites.ReadWrite.All` ❌ | Every site in the entire tenant |

| `Sites.Selected` ✅ | Only sites explicitly granted via the permissions API |

With `Sites.Selected`, your app has **zero access** to any SharePoint site until a SharePoint admin explicitly grants it — one site at a time. This means:

- A compromised Client Secret cannot be used to access any other site in your organisation

- IT and compliance teams can audit exactly which sites each app can access

- You can grant `read` access to some sites and `write` access to others

### Adding More Sites

If you need the connector to access additional SharePoint sites in the future, repeat Step 5 for each new site — no Azure Portal changes needed.

### Revoking Access

To remove the app's access to a site, run:

```

GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions

```

Find the permission entry for your app, copy its `id`, then:

```

DELETE https://graph.microsoft.com/v1.0/sites/{site-id}/permissions/{permission-id}

```

---

## Troubleshooting

### "SiteId is required"

The SPConfig record has empty fields. Open the SharePoint Configuration page, fill in all fields, and click Save.

### "InvalidAuthenticationToken" / JWT error

The Client ID or Tenant ID does not match the Azure app. Verify them against Azure Portal → App registrations → your app → Overview. Also check the Client Secret has not expired.

### "Status 401 Unauthorized"

Admin consent for `Sites.Selected` has not been granted, or the site-level permission POST in Step 5 has not been run yet. Complete both steps and try again.

### "Status 403 Forbidden"

The site-level permission grant was not run (Step 5), or it was run with the wrong Client ID. Run the GET on `/permissions` to verify your app appears in the list.

### Files exist in SharePoint but the grid is empty

The connector lists files in the root of the Documents library by default. If your files are in a subfolder, pass the correct `FolderPath`. Also confirm the Drive ID corresponds to the `Documents` library.

### Spinner never stops on File Browser

Set the Data Grid **Refresh time** to `0` in Studio Pro and redeploy.

---

## Licence

Apache 2.0 — see `LICENSE` for details.