# SharePoint

The **SharePoint Node** in StackAI allows you to search for files stored in your SharePoint environment. You can specify search queries, filter by file types, and control the number of results returned. This is ideal for automating document retrieval, content management, and knowledge discovery. Sharepoint allows you to search for files stored in your Sharepoint, as well as Sharepoint News.

**Example of Usage**

Suppose you want to find all PDF reports related to "Quarterly Sales" in your SharePoint. You would set up the node as follows:

* **Input Example:**
  * Search Query (string, required): "Quarterly Sales"
  * File Types (string array, optional): \["pdf"]
  * Max Results (integer, optional): 10

The node will return a list of matching files, including their names, URLs, types, modification dates, and more.

***

### Which SharePoint Connection Should I Use?

When creating a SharePoint connection in StackAI, there are 3 available methods: through OAuth connection, an App-only (API key) connection, or an NTLM connection.

* **OAuth Connection (Delegated Access)**: An OAuth connection uses Microsoft’s OAuth 2.0 flow to authenticate on behalf of a user. StackAI accesses SharePoint using the permissions of the signed-in user.
* **App-Only Connection**: An App-Only connection uses an Azure App Registration with application permissions. So StackAI authenticates as an application, not a user.
* **NTLM Connection**: This is a legacy Microsoft authentication protocol commonly used in on-prem SharePoint or environments that do not support OAuth. 

We recommend using a **SharePoint OAuth2 or App-Only Connection:**

* Use OAuth if you want access scoped to individual users.
* Use App-only if you want centralized control over permissions, or want access scoped to enterprise service accounts.

***

### Configure Applications for App-Only Connection

App-only connection requires two applications:

1. An application that has admin permissions over Sharepoint ("Admin App"): This application likely already exists. It is only used by the IT team of the enterprise to manage the permissions of all applications in the organization, including the SharePoint app for StackAI. StackAI platform won’t have access to this application.
2. A separate application specifically configured for StackAI to access ("StackAI SharePoint App"): This app requires Microsoft Graph `sites.selected` permission. 

The Admin App is used to grant permission to specific sites for the StackAI SharePoint App.

#### Step 1: Set up an Admin App (Optional)

1. Go to App Registrations on Microsoft Azure ([link](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade))
2. Create a new app registration
   1. Add a name to the app
   2. Select “Accounts in this organizational directory only (`your org name` only - Single tenant)
   3. Register

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2Fvb7ySfKe2M7tPeQJqa48%2Fimage.png?alt=media&#x26;token=028bd7a6-9d48-49e0-9e13-4401149e0c79" alt="" width="375"><figcaption></figcaption></figure></div>

3. Set up the app API permissions:

Under `Manage` go to `API permissions`

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FvYEOVGLSUS4o5UWG3wb0%2Fimage.png?alt=media&#x26;token=7fffb1f9-4d56-4a2f-8abe-4ea462588f29" alt="" width="375"><figcaption></figcaption></figure></div>

Click on “Add a permission”

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FiWSeRCqPWTCQW0eTKdpY%2Fimage.png?alt=media&#x26;token=20fef52e-0030-4fe4-8eea-4660d6e84a89" alt="" width="375"><figcaption></figcaption></figure></div>

Select Microsoft Graph

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2F9QNmvtda5n33WD5epZai%2Fimage.png?alt=media&#x26;token=32a5efcf-403e-46e4-97b6-059e27d02a66" alt="" width="375"><figcaption></figcaption></figure></div>

Select “Application permissions”

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2F43L8ysXlspt9bvJ77FfA%2Fimage.png?alt=media&#x26;token=08452c1d-d8b3-4290-aaa6-cd7b204e3d7c" alt="" width="375"><figcaption></figcaption></figure></div>

Add `Sites.FullControl.All` permission

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FXSlXrGQ7CXCuyRcQ8onB%2Fimage.png?alt=media&#x26;token=de619261-9444-40f9-9394-60bbe2be604b" alt="" width="375"><figcaption></figcaption></figure></div>

Grant admin consent to the app

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2F7saknsGNi4478Wy8G3e1%2Fimage.png?alt=media&#x26;token=f6b7e5ef-7429-4074-9bf5-08aa82b363f4" alt="" width="375"><figcaption></figcaption></figure></div>

#### Step 2: Register a SharePoint app in Azure Active Directory (Microsoft Entra)

1. Sign into the [Azure Portal](https://portal.azure.com/) with admin credentials.
2. Navigate to **Azure Active Directory > App registrations**.
3. Click **New registration**.
4. Enter your application name
5. Select “Accounts in this organizational directory only (`your org name` only - Single tenant)
6. (Optional) Set the **Redirect URI** (type: Web). This can be your application's URI or **`http://localhost`** for dev/test.
7. Click **Register**.

#### Step 3: Configure Permission Scope

1. Navigate to **API permissions** > **Add a permission** > **Microsoft Graph**

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FXHkLBK0JgZsA3UnYCyRe%2Fimage.png?alt=media&#x26;token=17954bd2-48e4-4d2b-9833-4abff1d3a7c9" alt="" width="375"><figcaption></figcaption></figure></div>

2. Select **Application permissions** and add `Sites.Read.All` , `Sites.Read`, and `Sites.Write` permissions

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2F18O8QXPywl8MlBsCmEty%2Fimage.png?alt=media&#x26;token=4575b558-412a-454b-9947-09c353f720d5" alt="" width="375"><figcaption></figcaption></figure></div>

3. Grant admin consent&#x20;

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FWE0RPHXkccObU6iXLWGi%2Fimage.png?alt=media&#x26;token=4f2161d6-b13c-4482-9d3a-c52cd065ca2f" alt="" width="375"><figcaption></figcaption></figure></div>

If admin consent is not granted, the connection may appear as **Unhealthy** in StackAI.

{% hint style="info" %}
**Notes on SharePoint App permission**

We generally recommend your Azure App Registration to include the following Microsoft Graph permissions:&#x20;

* `Sites.Read`: Read files and folders
* `Sites.Read.All`: Discover SharePoint sites
* `Sites.Write`: Create or update Word and Excel files as part of workflows

The minimum permission required to read specific SharePoint sites is `Sites.Selected`.&#x20;

* With `Sites.Selected` enabled, `Sites.Read` and `Sites.Read.All` are not necessary.&#x20;
* However, using `Sites.Selected` permission would require IT admins to keep track of the sites given to this app.&#x20;
* Dynamic dropdowns in StackAI Sharepoint actions will not work with the `Sites.Selected` scope as there are not enough permissions to allow site discovery. Instead, users will need to manually enter the Site ID in order to make requests to the sites. See section [Available Actions](#available-actions) below for details.
  {% endhint %}

#### Step 4: Create Client Secret

1. Under your app registration, go to **Certificates & secrets** > New client secret&#x20;

   <div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FRqYLmRVlM1DiuvZu83kq%2Fimage.png?alt=media&#x26;token=4fd6de85-c40b-4c7e-ac98-a1deb420335c" alt="" width="375"><figcaption></figcaption></figure></div>
2. Add a description and select an expiry period.
3. Copy the generated **secret** **value** (not secret ID) immediately and store it securely. This is your **`sharepoint_client_secret`**. You won't be able to view it again after leaving the page.

   <div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FzokG66BQ3PENTCabQZxZ%2Fimage.png?alt=media&#x26;token=349967db-a824-491d-a292-20f10bea0a8e" alt="" width="375"><figcaption></figcaption></figure></div>

#### Step 5. Grant SharePoint Site Access to the SharePoint App

Each SharePoint site has a unique set of Microsoft Graph IDs. We will use these identifiers to grant permission to the specific sites.

For a sample site `https://<your organization domain>.sharepoint.com/sites/<site name>`, there are three components to construct the full ID.

1. Host Name: This is in the site URL. Example: `<your organization domain>.sharepoint.com`&#x20;
2. Site Collection ID:&#x20;
   1. Add `_api/site/id` to the end of the site URL. Example: `<your organization domain>.sharepoint.com/sites/<site name>/_api/site/id`&#x20;
   2. Press Return key to run this url, and you will see an XML file. The `Guid` field is the Site Collection ID.

```xml
<d:Id xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
xmlns:georss="http://www.georss.org/georss" 
xmlns:gml="http://www.opengis.net/gml" 
m:type="Edm.Guid">xxxxxxxxxxxx</d:Id>
```

3. Site Web ID:
   1. Add `_api/web/id` to the end of the site URL. Example: `<your organization domain>.sharepoint.com/sites/<site name>/_api/web/id`&#x20;
   2. Press Return key to run this url, and you will see an XML file. The `Guid` field is the Site Web ID.

```xml
<d:Id xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
xmlns:georss="http://www.georss.org/georss" 
xmlns:gml="http://www.opengis.net/gml" 
m:type="Edm.Guid">xxxxxxxxxx</d:Id>
```

4. Construct the full ID: Append all three idetifications together in the order of `Host Name,Site Collection ID,Site Web ID` separated by comma. Example: `<your organization domain>.sharepoint.com,12345678-90ab-cdef-1234-567890abcdef,abcdef12-3456-7890-abcd-ef1234567890`

To grant permission to the specific sites, you will first need the access token from the Admin App. Note, this is different from the Client Secret.

You can find the Tenant ID, Admin App Client ID from the Azure Portal > Overview.

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FcTyFHEztHHUsuJiGNFDG%2Fimage.png?alt=media&#x26;token=178e3c34-2ab9-431d-8afc-37488590cbb1" alt="" width="375"><figcaption></figcaption></figure></div>

You can find the Client Secret from the **Azure Portal** > **Manage** > **Certification & Secrets**.

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FF8WxviyaiSPSj1WOMNYo%2Fimage.png?alt=media&#x26;token=9b42cebb-ad78-4261-9b69-f5895dfe8b3b" alt="" width="375"><figcaption></figcaption></figure></div>

Below is the command to obtain the access token from the Admin App.&#x20;

```bash
curl -sS -X POST "https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<ADMIN_APP_CLIENT_ID>" \
  -d "client_secret=<ADMIN_APP_CLIENT_SECRET>" \
  -d "grant_type=client_credentials" \
  -d "scope=https%3A%2F%2Fgraph.microsoft.com%2F.default"
```

With the access token, run the following command to grant read permission to the site. Run the command for each site you would like to add to the SharePoint app.&#x20;

* Use the full site ID constructed in the previous step.&#x20;
* Target App Client ID is the Client ID of the SharePoint app.

```bash
curl -sS -X POST "https://graph.microsoft.com/v1.0/sites/<SITE_ID>/permissions" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
   "roles": ["read"],
   "grantedToIdentities": [
     {
       "application": {
         "id": "<TARGET_APP_CLIENT_ID>",
         "displayName": "Target App"
       }
     }
   ]
  }'
```

***

### **Setting Up App-Only Connection in StackAI**

<div align="left"><figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FOesety7S2OONzMv3RXwa%2Fimage.png?alt=media&#x26;token=1ffc9088-be3f-4c91-a145-73d7101a5480" alt="" width="375"><figcaption></figcaption></figure></div>

The connection requires several key pieces of information:

**1. Client ID** (string, required)

* **What it is:** A unique identifier for your Azure AD application (also called "Application (client) ID").
* **Where to find it:** In the Azure portal, under "Azure Active Directory" > Under "Manage" select "App registrations" > \[Your App] > "Overview".
* **Example:** `b1a7c8e2-1234-4f56-9abc-1234567890ab`

**2. Client Secret** (string, required)

* **What it is:** A password-like value generated for your Azure AD application, used to authenticate your app.
* **Where to find it:** In the Azure portal, under "Azure Active Directory" > "App registrations" > \[Your App] > "Certificates & secrets". You must create a new client secret and copy the value. Make sure you copy the Client Secret Value, not the Secret ID.
* **Example:** `wJ8Q~abc1234efgh5678ijklmnop9qrstuvwx`

**3. Tenant ID** (string, required)

* **What it is:** The unique identifier for your Microsoft 365 tenant (organization).
* **Where to find it:** In the Azure portal, under "Azure Active Directory" > "Overview" > "Tenant ID".
* **Example:** `72f988bf-86f1-41af-91ab-2d7cd011db47`

**4. SharePoint Site ID** (string, optional if the Entra App permission is `Sites.Read.All` and required if the permission is `Sites.Selected`)

* **What it is:** The unique identifier for the SharePoint site you want to access. This is not the site URL, but an internal ID.&#x20;
* **Where to find it:** See [Step 5](#step-5.-grant-sharepoint-site-access-to-the-sharepoint-app) above on how to obtain the Site ID.&#x20;
* **Example:** `contoso.sharepoint.com,12345678-90ab-cdef-1234-567890abcdef,abcdef12-3456-7890-abcd-ef1234567890`&#x20;

***

### **Available Actions**

{% hint style="info" %}
Dynamic dropdowns in StackAI Sharepoint actions will not work with the `Sites.Selected` scope as there are not enough permissions to allow site discovery.&#x20;

Users can change the Site parameter in **Inputs** to `string` type and enter the Site ID to make requests to the sites. See [Step 5](#step-5.-grant-sharepoint-site-access-to-the-sharepoint-app) above on how to obtain the Site ID.

&#x20;![](https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FRfVmaW2Yf6m2r6ejEv6Y%2Fimage.png?alt=media\&token=a51ef033-3622-4470-8c9c-03786bf91a40)
{% endhint %}

#### 1. List SharePoint Content

List the contents of SharePoint

**Inputs**

| Name         | Description                                   | Example           | Required |
| ------------ | --------------------------------------------- | ----------------- | -------- |
| Search Query | The search string to find files and documents | "Quarterly Sales" | Yes      |
| File Types   | List of file types to filter by               | \["pdf", "docx"]  | No       |
| Max Results  | Maximum number of results to return           | 10                | No       |

* **Search Query** (string, required): The keywords or phrase to search for in file names and content.
* **File Types** (array of strings, optional): Filter results by file extensions (e.g., "pdf", "docx", "xlsx").
  * You can include any file extension that is supported by your SharePoint environment.
  * Common examples include:
    * `"pdf"` (PDF documents)
    * `"docx"` (Word documents)
    * `"xlsx"` (Excel spreadsheets)
    * `"pptx"` (PowerPoint presentations)
    * `"txt"` (Text files)
    * `"csv"` (Comma-separated values)
    * `"jpg"`, `"png"`, `"gif"` (Image files)
    * `"zip"` (Compressed archives)
    * ...and any other file extension that your SharePoint instance stores
* **Max Results** (integer, optional, default: 20): Limit the number of files returned.

**Outputs**

* Each file in the output includes:
  * **File ID** (string): Unique identifier for the file.
  * **File Name** (string): Name of the file.
  * **File URL** (string): Direct link to access the file.
  * **File Type** (string): File extension/type (e.g., "pdf").
  * **Modified Date** (string): Last modified date.
  * **File Size** (integer): File size in bytes.
  * **Author** (string): File author or creator.
* **Total count** (integer): Total number of files found

**Example Output:**

```json
{
  "files": [
    {
      "file_id": "12345",
      "file_name": "Quarterly_Report_Q1.pdf",
      "file_url": "https://contoso.sharepoint.com/sites/finance/Shared%20Documents/Quarterly_Report_Q1.pdf",
      "file_type": "pdf",
      "modified_date": "2025-06-15T10:23:45Z",
      "size": 1048576,
      "author": "Jane Doe"
    },
    {
      "file_id": "67890",
      "file_name": "Budget_2025.pdf",
      "file_url": "https://contoso.sharepoint.com/sites/finance/Shared%20Documents/Budget_2025.pdf",
      "file_type": "pdf",
      "modified_date": "2025-07-01T14:05:12Z",
      "size": 2097152,
      "author": "John Smith"
    }
  ],
  "total_count": 2
}
```

#### 2. Create Word Document

This action creates a new Microsoft Word (DOCX) file in a specified SharePoint site and folder, with the content you provide (in Markdown format). Typically used to automate report generation, meeting notes, or any document creation directly into your SharePoint library.

**Inputs**

<table><thead><tr><th>Name</th><th width="269.02734375">Description</th><th width="215.33203125">Example</th><th>Required</th></tr></thead><tbody><tr><td>File Name</td><td>Name of the Word document to create (must end in <code>.docx</code>).</td><td><code>Report.docx</code></td><td>Yes</td></tr><tr><td>Site</td><td>Select the SharePoint where your document will be created</td><td><sub><kbd>contoso.sharepoint.com/sites/Finance</kbd></sub></td><td>Yes</td></tr><tr><td>Content</td><td>Document body text in <strong>Markdown</strong> format.</td><td><code># Q2 Report\nSummary...</code></td><td>Yes</td></tr></tbody></table>

**Outputs**

On success, the action returns:

* **File ID** (string): Unique identifier of the created file.
* **File URL** (string): URL to open the document in SharePoint/OneDrive.
* **File Size** (number): Size of the created file in bytes.

#### 3. Get File

This action downloads a file from SharePoint and extracts its text content.

**Inputs**

<table><thead><tr><th>Name</th><th width="269.02734375">Description</th><th width="215.33203125">Example</th><th>Required</th></tr></thead><tbody><tr><td>Site</td><td>Select the SharePoint site that contains the file</td><td><sub><kbd>contoso.sharepoint.com/sites/Finance</kbd></sub></td><td>Yes</td></tr><tr><td>Drive</td><td>Select the drive or document library within the selected site</td><td><sub><kbd>contoso.sharepoint.com/sites/Finance/Shared%Documents</kbd></sub></td><td>Yes</td></tr><tr><td>File</td><td>Select the file to download (dropdown displays up to 500 files)</td><td><code>Report.docx</code></td><td>Yes</td></tr></tbody></table>

**Outputs**

On success, the action returns:

* **File ID** (string): Unique identifier of the created file.
* **File Name** (string): Name of the file.
* **SharePoint URL** (string): Web URL to access the file in SharePoint.
* **File Content** (string): Extracted text content of the file (no OCR).
* **Download URL** (string): Pre-authenticated download URL (expires in 1 hour).

#### 4. Get Page

This action downloads a SharePoint page and extracts its text content in markdown format.

**Inputs**

<table><thead><tr><th width="117.28125">Name</th><th width="409.25390625">Description</th><th width="135.96484375">Required</th></tr></thead><tbody><tr><td>Site</td><td>Select the SharePoint site that contains the file</td><td>Yes</td></tr><tr><td>Page</td><td>Select the page to download (dropdown displays up to 500 pages)</td><td>Yes</td></tr></tbody></table>

**Outputs**

On success, the action returns:

* **Page ID** (string): Unique identifier of the page.
* **Page Title** (string): Title of the page.
* **SharePoint URL** (string): Web URL to access the file in SharePoint.
* **Page Content** (string): Extracted text content of the page (markdown format).

#### 5. Upload File to SharePoint

This action uploads a file to SharePoint. Supports URLs and base64 content up to 250MB.

**Inputs**

<table><thead><tr><th width="131.76171875">Name</th><th width="471.58984375">Description</th><th width="120.5703125">Required</th></tr></thead><tbody><tr><td>File Name</td><td>Name of the file to upload.</td><td>Yes</td></tr><tr><td>File URL</td><td>URL of the file to upload. If blank, will use base64_file_content.</td><td>No</td></tr><tr><td>Base64 File Content</td><td>Base64-encoded file content. Required if File URL is not provided.</td><td>No</td></tr><tr><td>Site</td><td>Select the SharePoint site where the file will be uploaded.</td><td>Yes</td></tr><tr><td>Folder Path</td><td>Path to the folder to upload the file. Leave empty for root folder.</td><td>No</td></tr><tr><td>Content Type (MIME)</td><td>MIME type of the file (auto-detected if omitted)</td><td>No</td></tr></tbody></table>

**Outputs**

On success, the action returns:

* **File ID** (string): Unique identifier of the uploaded file.
* **File URL** (string): URL to open the file in SharePoint/OneDrive.
* **File Size** (number): Size of the uploaded file in bytes.

***

#### **Advanced Settings**

1. Retry on Failure: Enable retrying when the node execution fails
2. Fallback Branch (integer): Create a separate branch that executed when this node fails, allowing you to handle errors gracefully

***

#### **Best Practices**

* Always provide a clear and specific search query for best results.
* Use file type filters to narrow down results when searching for specific document formats.
* Adjust the max results parameter to control the volume of data returned.