How to Set Up and Use a SharePoint Documents Adapter

This article reviews set up and expected behavoir of a SharePoint Documents Adapter.

Written By Ed Kinne

Overview

The SharePoint adapter keeps your signage in sync with a SharePoint Online document library.

Add, edit, rename, or delete a file in SharePoint, and Korbyt updates the Media Library, playlists, and screens on the next sync.
Library columns can drive tags, playlists, play order, duration, and start and end dates.

NOTE: The SharePoint adapter works with cloud-only and hybrid Microsoft 365 tenants. Libraries on on-premises SharePoint Server are not supported

This article reviews a specific Data Adapter; for more general information, see Data Integration and Data Adapters

How the Data Flows

SharePoint to Korbyt - 4 Steps of Data Flow

Sign in. Korbyt signs in through your Entra ID app and gets a read-only access token, renewed automatically.
Check for changes. Every refresh interval, Korbyt reads the file list and mapped column values and compares them to the last sync. New and changed files download over HTTPS.
Update the Media Library. Korbyt adds and updates files, applies tags, dates, and duration, updates playlists, and removes deleted files (when Remove Missing Keys = True).
Play. Screens pick up changes at their next check-in.

Authentication Flow

Authentication flow · setup and every sync

The service account signs in on Microsoft's page once, during setup in the CMS. After that, Korbyt keeps the connection alive on its own: it uses the access token to pull content each sync and the refresh token to get a new access token when the old one expires. Every SharePoint call is a read-only GET request.

What Korbyt Can Access

Read-only. The app uses delegated read permissions (Microsoft Graph User.Read, SharePoint AllSites.Read). Korbyt never creates, edits, or deletes anything in SharePoint.
Limited to the authorizing account. Korbyt syncs only the folders you map, but the token can read anything the authorizing account can read. Use a service account with access only to the libraries meant for screens.
Your app, your control. The app registration lives in your Entra ID tenant. Delete its client secret or the app registration to revoke access at any time.
What Korbyt stores: the files in mapped folders, their file properties (name, size, version, modified date), and the values of the columns you map. No other columns are copied.
Encryption: all traffic uses HTTPS. Downloaded files are encrypted at rest with AES-256. Sign-in tokens are stored securely. Columns listed in Encrypted Columns are encrypted in the Korbyt database.
Korbyt never sees the service account password. Sign-in happens on Microsoft's page. Korbyt receives only tokens.

Before You Start

An Entra ID administrator to register the app.
A service account with read access to the libraries you want on screens (recommended).
At least one file in every folder you plan to map, before you save the adapter.

Item Type / Data Value	Supported
Images	PNG, JPG, GIF
Video	MP4
Documents	PDF, PPTX (each page becomes an image)
Columns for tags	Single line of text, Choice, Number, Managed Metadata
Other optional columns	Start date, end date, duration (number), sort order, playlist name

Step 1: Register an App in Microsoft Entra ID

In these steps you will be navigationg your Microsoft Entra ID, configuring Korbyt as an application that can connected and collecting information that will be used in Step 2.

Sign in to portal.azure.com and open Microsoft Entra ID > App registrations > New registration.
Enter a name (for example, Korbyt SharePoint Adapter). Set Supported account types to Accounts in this organizational directory only (Single tenant).
Set Redirect URI to platform Web and URL https://www.korbyt.com/oauth/sharepoint_adapter_redirect Click Register.
On the app's Overview page, copy the Application (client) ID and Directory (tenant) ID.
Go to Certificates & secrets > New client secret.
1. Copy the Value now; it is shown only once.
2. Note the expiry date. When it expires, syncing stops until you enter a new secret in Korbyt.
Go to API permissions. Confirm Microsoft Graph > User.Read and SharePoint > AllSites.Read, are type Delegated. Add any that are missing. Grant admin consent if your tenant requires it.
Collect your SharePoint values:
1. Server URL: the hostname only, for example, contoso.sharepoint.com
2. Then, for each folder, collect a Site key and folder value from the folder's browser URL.
  1. For example, for the URL https://contoso.sharepoint.com/sites/marketing/Shared%20Documents
    1. the Key is sites/marketing/
    2. and the Value is Shared%20Documents.
  2. For a subfolder, add its path to the Value with a forward slash: a folder named Signage inside Shared Documents is Shared%20Documents/Signage.

Step 2: Create the Adapter in Korbyt

Navigate to the Data Integration Screen
1. In the new Sidebar Navigation Menu, in the Integrations section, click on Data Adapters.
2. Or, open the Mega Menu, then in the Advanced section, click on Data Integrations
Click the Create Adapter button
Enter an Adapter Name, set Adapter Type to Template, and click Next.
Enter the SharePoint server URL, Azure tenant ID, Azure application ID, and Client Secret from Step 1.
Click SharePoint Authorization and sign in with the service account.
Click SharePoint Sites & Folders and add one Key/Value pair per folder.
Set other options described in the table below, then click Save & Create.
Click the eye icon to confirm files are syncing.

Adapter Setting Explinations

Setting	What it does
SharePoint View	Syncs only files in this library view. Optional.
Tags	Tags applied to every synced file.
Refresh Interval	How often Korbyt checks for changes. Default 1 hour, minimum 10 minutes. The next check starts after the previous one finishes.
Remove Missing Keys	How often Korbyt checks for changes. Default 1 hour, minimum 10 minutes. The next check starts after the previous one finishes.
Column Tags	Columns whose values become tags. Separate multiple columns with commas.
Create Playlists	True lets Korbyt create playlists named from the Playlist Names columns.
Playlist Names	Columns used to name playlists. Requires Create Playlists = True.
Sort Order	Column that sets play order in adapter-created playlists.
Media Duration	Number column that sets how long each item plays, in seconds.
Media Begin Date	Column that sets when an item starts playing.
Media End Date	Column that sets when an item stops playing.
Ignore Title	True uses the file name instead of the SharePoint Title.
Encrypted Columns	Columns stored encrypted in the Korbyt database.

Tips:
Column Tags plus Clever Playlists route content to the right screens without adapter-created playlists.
Media Duration, Media Begin Date, and Media End Date apply with or without Create Playlists.
Column fields take the column's internal name, not its display name. To find it, open Library settings, select the column, and copy the value after Field= in the browser address bar.

How Syncing Behaves

Each sync downloads only what changed. Korbyt detects a change from the file's version, size, or modified date

In SharePoint	In Korbyt After the Next Sync
File added	Added to the Media Library with its tags and dates. Matching Clever Playlists pick it up.
File edited or replaced	Updated in place. Playlists and screens keep using the same item.
Columns changed	Tags, dates, duration, and playlist assignments updated.
File renamed	Renamed in the Media Library and playlists.
File deleted	Removed from the Media Library, playlists, and screens (Remove Missing Keys = True).
PDF or PPTX added or edited	Each page converted to an image in a Media Library subfolder named for the document. Added or removed pages follow.

Screens show changes at their next player check-in, every rolling 15 minutes.
Tags are converted to lowercase and de-duplicated.
- Comma-separated values in one column become separate tags.
Save & Create after editing the adapter runs a full re-sync.
- Every file downloads again; Media Library items are not duplicated.
If the client secret expires or the authorizing account loses access, syncing stops, and errors appear in the adapter logs on the adapter info page. Enter a new secret and click SharePoint Authorization again.

Was this helpful?

Still need help? Share an idea