> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cymph.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SharePoint

> Import playbooks from SharePoint documents, and publish playbook documentation back to a site.

## What Cymph uses it for

Cymph connects to SharePoint through the Microsoft Graph API for two purposes:

1. **Importing content** — browses your sites, document libraries, and pages, and reads file contents so documents can be imported as playbooks. *(read)* See [Import a playbook](/howto/import_playbook).
2. **Publishing documentation** — uploads a playbook's documentation into a document library as Markdown or PDF. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks).

A single app registration can serve either or both purposes. **If you only import, Cymph needs read access; publishing requires an additional write permission** — see [Permissions](#permissions) below.

## Requirements

The integration requires the following information from a registered Entra ID application:

| Field             | Description                                              |
| ----------------- | -------------------------------------------------------- |
| **Tenant ID**     | Your Entra ID (Azure AD) tenant ID                       |
| **Client ID**     | Application (client) ID of the registered application    |
| **Client secret** | A client secret generated for the registered application |

## App registration setup

You can see the steps on how to create an Entra ID application [here](https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread).

1. In **Entra ID → App registrations**, create (or reuse) an app registration.
2. Under **Certificates & secrets**, create a **client secret** and copy its value.
3. Under **API permissions**, add the Microsoft Graph **application** permission for the access you need (see below) and grant admin consent.
4. Note the **Application (client) ID** and **Directory (tenant) ID** from the app's Overview page.

## Permissions

Cymph requests tokens using the **`.default`** scope, which means it asks for no scopes of its own: the access it gets is exactly the set of application permissions already consented on your app registration. You control access entirely from the Azure side.

| If you want to                       | Grant                 | Type            |
| ------------------------------------ | --------------------- | --------------- |
| Import content only                  | `Sites.Read.All`      | **Application** |
| Import **and** publish documentation | `Sites.ReadWrite.All` | **Application** |

`Sites.ReadWrite.All` supersedes `Sites.Read.All` — grant one or the other, not both. Either is an application permission (app-only, no signed-in user) and requires **admin consent** in your tenant.

<Tip>
  Start with `Sites.Read.All`. You can raise it to `Sites.ReadWrite.All` later without recreating the integration — the connector picks up the broader consent on its next token request.
</Tip>

<Warning>
  Graph's `Sites.Selected` permission — which restricts an app to individually approved sites — is **not** compatible with this integration. Cymph discovers sites by calling the tenant-wide site-search endpoint, which `Sites.Selected` does not authorise, so both Test Connection and site listing will fail. Tenant-wide access is required.
</Warning>

<Note>
  Cymph never deletes anything in SharePoint. Publishing writes a file to the library path you select; nothing already in your document libraries is removed.
</Note>

## What Cymph reads and writes

### Reads

| Purpose                          | Graph endpoint                                         |
| -------------------------------- | ------------------------------------------------------ |
| Test the connection              | `GET /v1.0/sites?search=*&$top=1`                      |
| List sites                       | `GET /v1.0/sites`                                      |
| List a site's document libraries | `GET /v1.0/sites/{site_id}/drives`                     |
| Browse a library's contents      | `GET /v1.0/drives/{drive_id}/root/children`            |
| Browse a folder's contents       | `GET /v1.0/drives/{drive_id}/items/{item_id}/children` |
| Read file metadata               | `GET /v1.0/drives/{drive_id}/items/{item_id}`          |
| Look up an item by path          | `GET /v1.0/drives/{drive_id}/root:/{path}`             |
| Download file content for import | `GET /v1.0/drives/{drive_id}/items/{item_id}/content`  |
| List site pages                  | `GET /v1.0/sites/{site_id}/pages`                      |

File content is fetched on demand when you import a document — Cymph does not mirror or continuously sync your SharePoint content.

### Writes

| Purpose                       | Graph endpoint                                      |
| ----------------------------- | --------------------------------------------------- |
| Upload playbook documentation | `PUT /v1.0/drives/{drive_id}/root:/{path}:/content` |

Publishing to a path that already holds a file **overwrites** it. Cymph returns the resulting item's `webUrl`, which becomes the "navigate to the pushed playbook" link in Deploy History.

## Publishing formats

SharePoint accepts both documentation formats:

| Format          | What it contains                                                                  |
| --------------- | --------------------------------------------------------------------------------- |
| **Markdown**    | The playbook's documentation blocks, rendered as Markdown                         |
| **Summary PDF** | The full playbook summary report — metadata, contributors, and the workflow image |

Image blocks are omitted from the Markdown format.

## Testing the connection

**Test Connection** acquires a token and then searches for a single site, so it verifies both the credentials and read access:

| Message                                              | Meaning                                                                            |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Valid SharePoint credentials**                     | Authentication succeeded and the app can read sites                                |
| **Authorization failed**                             | The token was rejected (`401`) — usually a missing or unconsented `Sites.Read.All` |
| **Failed with response status *N***                  | Graph answered with another error status                                           |
| **Connection timed out**                             | No response within 5 seconds                                                       |
| **Target does not seem to be a SharePoint instance** | The request failed before a status could be read                                   |

<Note>
  Test Connection only exercises **read** access. If you intend to publish documentation, a successful test does not confirm that `Sites.ReadWrite.All` has been consented — the first publish attempt is what surfaces that.
</Note>