> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/product-reference/dialogue-studio/dialogue-studio-example-flows/connect-sharepoint-with-microsoft-graph.md).

# Connect to SharePoint sites and lists with Microsoft Graph

Import a flow in Dialogue Studio that uses Microsoft Graph application permissions (Sites.Selected) to read, update, and create SharePoint list items.

This example connects Dialogue Studio to SharePoint using Microsoft Graph application permissions with Sites.Selected. It resolves site IDs and performs GET, PATCH, and POST operations against SharePoint lists. Use it as a starting point for reading or updating SharePoint-backed configuration or list data from a flow.

## What it does

The flow requests a Graph access token using client credentials, resolves the Graph site ID for a site or subsite, and then reads, updates, or creates items in SharePoint lists using that site ID. Because the runtime app only has Sites.Selected permission, it can only reach sites it has explicitly been granted access to.

{% hint style="warning" %}
Entra app registration secrets expire and must be maintained in both the Entra app registration and the Dialogue Studio environment variables. Sites.Selected does not grant automatic access to every SharePoint site; the runtime app must be granted access to each target site or subsite separately.
{% endhint %}

## Prerequisites

* Create an Entra app registration that will be used by the Dialogue Studio flow.
* Grant the correct Microsoft Graph application permissions and admin consent.
* Grant site-specific access to the runtime app for every SharePoint site or subsite the flow needs to read or update.
* Create a client secret and store its value, along with the other required values below, in Dialogue Studio environment variables using your approved secret handling process ("Credentials for Security").
* The [node-red-contrib-chronos](https://flows.nodered.org/node/node-red-contrib-chronos) palette must be installed, since one part of this example uses a chronos scheduler node.

## Recommended app model

This scenario uses two separate Entra app registrations:

1. **Runtime app**, used by the Dialogue Studio flow to request a token with the client credentials grant and call Microsoft Graph.
   * Microsoft Graph application permission: `Sites.Selected`.
   * Used for resolving site IDs, reading list items, updating list items, and creating list items.
   * Must be explicitly granted access to each required SharePoint site.
2. **Admin app**, used once to grant the runtime app access to specific sites. It is not used by the live flow itself, only during setup.
   * Microsoft Graph application permission: `Sites.FullControl.All`.
   * Used for granting site-level permissions to the runtime app.

See [Understanding Resource Specific Consent for Microsoft Graph and SharePoint Online](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins-modernize/understanding-rsc-for-msgraph-and-sharepoint-online) for background on this permission model.

## Environment variables required

| Variable              | What it contains                       | Notes                                                        |
| --------------------- | -------------------------------------- | ------------------------------------------------------------ |
| `CUST_TENANT_ID`      | Customer tenant ID / realm             | Copied from the customer tenant                              |
| `SPO_GraphApp_ID`     | Client ID of the runtime Entra app     | App has Graph application permission Sites.Selected          |
| `SPO_GraphApp_SECRET` | Client secret of the runtime Entra app | Must be renewed before expiry and updated in Dialogue Studio |

Store all three values in Dialogue Studio environment variables using your approved secret handling process. Never paste a real tenant ID, client ID, or client secret directly into a flow you plan to export, share, or debug.

## Preview

![SharePoint Graph app registration](https://2627137428-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FscZpnEdBjDgQmlVn1iLr%2Fuploads%2Fgit-blob-fda7e1dc56c7107c9e1e521a391fee187c784cb6%2Fsharepoint-graph-app-registration.png?alt=media)

## Import the flow

1. Log in to your Dialogue Studio environment.
2. Confirm the `node-red-contrib-chronos` palette is installed.
3. Open or create a tab for the flow.
4. From the menu in the top right, select **Import** and add the JSON from [`flows/sharepoint-graph-list-operations.json`](https://github.com/AnywhereNow/atlas-docs/tree/main/product-reference/dialogue-studio/dialogue-studio-example-flows/flows/sharepoint-graph-list-operations.json).
5. Set the three environment variables above in Dialogue Studio.
6. Update the placeholder values in the flow, for example the `global.set` names, the placeholder UCC name (`ucc-name-here`), and the placeholder tenant hostname (`your-tenant-here.sharepoint.com`), to match your own tenant and site naming.
7. If your target list is in a subsite, use the subsite resolution group and its returned site ID rather than the parent site ID. A parent site ID and a subsite ID are not interchangeable.
8. Deploy the flow.

## How the flow works

* **Get Graph token**: reads the tenant ID, client ID, and client secret from environment variables and posts to the Microsoft identity platform token endpoint using `grant_type=client_credentials` and the scope `https://graph.microsoft.com/.default`. The returned access token is stored in global context for later Graph requests.
* **Get the Site Details for a Specific Site**: calls a Graph URL such as `https://graph.microsoft.com/v1.0/sites/{tenant}.sharepoint.com:/sites/{ucc-name}` and stores the returned site ID in global context, for use by later list operations.
* **Get the Site Details for a Specific SubSite**: resolves a subsite path directly when your list lives below the main site, storing that returned ID instead.
* **Get the Site Details for all nested Subsites of a Site Collection**: walks a site collection's subsites recursively and stores the results, useful when you need to operate across many subsites rather than one specific site.
* **GET / PATCH / POST via Graph** (example groups):
  * A GET example reads items from a `Holidays` list, using `$expand=fields($select=...)` so only the needed columns are returned. This is a good production pattern: only request the columns you use.
  * A PATCH example reads a `Settings` list item, extracts its item ID, and updates a value on it.
  * Two POST examples create new items: one adds a single new `Agents` list item, and one adds the same item across every site ID collected by the subsite-walk group.
* Some SharePoint filters may require the header `Prefer: HonorNonIndexedQueriesWarningMayFailRandomly`. This is used in the function named **Get from Test UCC site**.

## Example Graph patterns used in the flow

* `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token` - token request
* `/sites/{hostname}:/sites/{path}` - resolve a site ID
* `/sites/{site-id}/lists/Holidays/items?$expand=fields($select=Title,wsp_ucc_holidays_startdatetime,wsp_ucc_holidays_enddatetime)` - GET items from a Holidays list
* `/sites/{site-id}/lists/Settings/items/{item-id}/fields` - PATCH a Settings item
* `/sites/{site-id}/lists/Agents/items` - POST to create an Agents item

## Permissions summary

| App         | Permission type             | Permission              | Why it is needed                                                                        |
| ----------- | --------------------------- | ----------------------- | --------------------------------------------------------------------------------------- |
| Runtime app | Microsoft Graph Application | `Sites.Selected`        | Used by the flow to call Graph against only the sites that have been explicitly granted |
| Admin app   | Microsoft Graph Application | `Sites.FullControl.All` | Used beforehand to grant site-specific access to the runtime app                        |

## Safe fallback behavior

The runtime app can only reach sites it has been explicitly granted access to through Sites.Selected. If a site has not been granted, Graph requests against it fail rather than silently succeeding against the wrong site, which limits the blast radius of a misconfigured flow. Debug nodes throughout the flow surface the raw Graph response so failures are visible during testing rather than hidden.

## Pre-deployment checklist

* Runtime app created and admin consent granted.
* `Sites.Selected` added to the runtime app.
* Site permissions granted to the runtime app for every required site or subsite via the admin app.
* `CUST_TENANT_ID`, `SPO_GraphApp_ID`, and `SPO_GraphApp_SECRET` added in Dialogue Studio using your approved secret handling process.
* Secret expiry date recorded and monitored.
* Correct site ID or subsite ID stored in global context.

## Verification

1. Trigger the **Get Graph token** group and confirm the debug output shows a valid token response.
2. Trigger the site resolution group for a site you have granted access to, and confirm the site ID is returned and stored.
3. Trigger a GET example against a real list and confirm the expected items are returned.
4. Trigger a PATCH or POST example against a test list first, and confirm the change is reflected in SharePoint before pointing the flow at a production list.
5. Test against a site that has not been granted access, and confirm the request fails safely rather than succeeding unexpectedly.

## Related topics

* Go to [Connect to Microsoft Graph as an application](/product-reference/dialogue-studio/dialogue-studio-example-flows/connect-microsoft-graph-application.md) for the simpler application-permission token pattern this scenario builds on.
* Go to [Dialogue Studio example flows](/product-reference/dialogue-studio/dialogue-studio-example-flows.md) for the full gallery of example flows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://atlas.anywhere.now/product-reference/dialogue-studio/dialogue-studio-example-flows/connect-sharepoint-with-microsoft-graph.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.