SharePoint

The primedocs app for SharePoint adds the primedocs button to the command bar of document libraries in SharePoint Online. Clicking it opens primedocs Web in a new browser tab. primedocs saves the document created there in the library and folder from which creation was started.

This page describes how the app works technically, what it does on SharePoint pages and which connections it involves. Setup is described in Microsoft SharePoint App Installation.

Prerequisites

• SharePoint Online (Microsoft 365). SharePoint Server (on-premises) is not supported, because documents are saved through Microsoft Graph.
• Sign-in to primedocs through Entra ID (Office 365). Documents are stored in SharePoint on behalf of the signed-in user.
• The Entra ID App Registration requires the delegated permissions Sites.ReadWrite.All and Files.ReadWrite.All (see Entra ID Apps). The same scopes and offline_access must be listed in the microsoftAppDelegateScopes attribute of the office365Auth node in primedocs.config.
• Only web-compatible primedocs templates are supported.
• Currently, only document libraries in the top-level site of a site collection are supported. primedocs cannot save documents from libraries in subsites.

Components

Component	Description
App package primedocs-sharepoint-extension.sppkg	SharePoint Framework (SPFx) solution with a ListView Command Set extension. The package contains the extension's JavaScript itself. SharePoint serves it from the app catalog, no external CDN is used.
List primedocsSettings	SharePoint list with the TemplatePickerUrl item. It contains the address of the primedocs instance the app opens.
primedocs Web	Web application of the primedocs instance (/app/web/sharepoint). Users select the template and fill in the fields here.
primedocs server	Generates the document and saves it to the library through Microsoft Graph.

Properties of the app package:

• Tenant-wide deployment: The app is deployed once in the app catalog and is then available in all sites, without activation per site.
• No custom script: The extension does not require custom scripts to be allowed on the sites.
• No API permissions in SharePoint: The package does not request any web API permissions. Nothing needs to be approved under "API access" in the SharePoint admin center.

Behaviour on SharePoint pages

Loading the extension

SharePoint loads the extension only in the modern list view of document libraries. It is not active in other lists, on pages or in the classic view.

On load, the extension performs two read requests through the SharePoint REST API in the browser, with the permissions of the signed-in user:

1. Read the configuration: Items of the primedocsSettings list in the current site. If there is no TemplatePickerUrl item, the extension reads the same list in the tenant root site (for example https://contoso.sharepoint.com).
2. Check the list type: Properties of the list currently shown, to make sure it is a document library.

If the extension finds no TemplatePickerUrl or the list is not a document library, it deactivates itself for this view and the button does not appear.

Beyond that, the extension does not change the page. It writes nothing to SharePoint, reads no document content and does not connect to the primedocs instance on load.

Clicking the button

On click, the extension reads the context of the current view and opens the TemplatePickerUrl with the following query parameters in a new browser tab:

Parameter	Value	Meaning
saveLocationSharePointSiteId	GUID	ID of the SharePoint site (site collection) containing the library.
saveLocationSharePointSiteName	Display name	Title of the site (display only).
saveLocationSharePointFolderPath	Server-relative partial path	Current folder relative to the library (library root stripped). Empty in the root folder.
saveLocationSharePointListId	GUID	ID of the document library (SharePoint list).
saveLocationSharePointListName	Display name	Title of the document library (display only).
saveLocationSharePointUrl	Absolute URL (URL-encoded)	Address of the SharePoint library page the button was opened from (for the "Back to SharePoint" link).
manifestVersion	Version number	Version of the deployed app package. primedocs records it in the client usage.

To save the document, primedocs uses the three parameters saveLocationSharePointSiteId, saveLocationSharePointListId and saveLocationSharePointFolderPath. The site and library names and the URL are for display only.

Example URL (values shortened):

https://{INSTANCE-NAME}/app/web/sharepoint?saveLocationSharePointSiteId=a1b2c3d4-…&saveLocationSharePointFolderPath=%2FContracts%2F2026&saveLocationSharePointListId=f9e8d7c6-…&saveLocationSharePointSiteName=Legal&saveLocationSharePointListName=Documents&saveLocationSharePointUrl=https%3A%2F%2Fcontoso.sharepoint.com%2F…&manifestVersion=1.0.0.5

The new tab is opened without a reference to the SharePoint page (noopener, noreferrer). primedocs Web can therefore neither control nor read the SharePoint page.

Document creation and storage

1. Start: primedocs Web takes over the parameters and shows a notice that documents are saved in the named site and library. From the notice, the user can return to SharePoint or leave SharePoint mode.
2. Sign-in: If the user is not signed in yet, primedocs Web redirects to sign-in through Entra ID. During sign-in, the primedocs server is authorised to access Microsoft Graph on behalf of the user with the scopes from microsoftAppDelegateScopes.
3. Creation: The user selects a web-compatible template, fills in the fields and enters the file name. The document is generated by the primedocs server, not by the browser.
4. Storage: The primedocs server uploads the document to the library and folder through Microsoft Graph. If a file with that name already exists, the new document receives a unique name. Existing files are not overwritten.
5. Result: primedocs Web shows the name of the saved document and offers to open it.

All Graph calls are delegated, so they run with the SharePoint permissions of the signed-in user. If the user has no write access to the library, saving fails.

Permissions

primedocs is not granted any permissions of its own in SharePoint. All access happens on behalf of the signed-in user and is limited to that user's SharePoint permissions.

During operation

Who	Permission	Purpose
SharePoint app in the browser	No permission of its own. It uses the user's SharePoint session.	Read the primedocsSettings list and the properties of the library
User	Read access to the primedocsSettings list	Without read access to the list in the site and in the root site, the app finds no configuration and does not show the button.
User	Add files in the target library (for example permission level "Contribute")	primedocs saves the document with these permissions.
primedocs server (Microsoft Graph, delegated)	Sites.ReadWrite.All, Files.ReadWrite.All	Read the libraries of the site to determine the drive, and upload the document. primedocs uses the same permissions for saving to Teams channels and OneDrive.
primedocs server (Microsoft Graph, delegated)	offline_access	Save documents even when the user signed in some time ago, without a new sign-in.

For delegated permissions, the suffix "All" does not mean that primedocs can access all sites. Microsoft Graph applies delegated permissions only within the permissions of the signed-in user. primedocs therefore reads and writes only where the user is allowed to read and write.

The SharePoint app and saving to SharePoint do not use application permissions (access without a user). The primedocs server accesses Microsoft Graph on behalf of a user exclusively to save a document created by that user to SharePoint, Teams or OneDrive.

Restricting access to individual sites through the Graph permissions is not provided for. Where primedocs is available is controlled by the deployment of the app (see below) and by the users' SharePoint permissions.

For setup

Task	Required role
Upload and deploy the app package in the app catalog	SharePoint administrator
Create the primedocsSettings list and grant read access	Owner of the respective site
Consent to the delegated permissions of the Entra ID App Registration (admin consent)	Administrator allowed to grant consent on behalf of the organisation in Entra ID

Deployment to selected sites

primedocs does not have to appear in every site. There are two ways to restrict the app to specific sites:

• Through the configuration: The app remains deployed to all sites, but the primedocsSettings list is not in the tenant root site, only in the desired sites. In all other sites the app does not show the button.
• Through the installation: The app is not deployed to all sites but added to each desired site individually. In all other sites the extension is not loaded at all.

The steps are described in Deploy to selected sites only.

Operation with an on-premises instance

The app also works when the primedocs instance runs in your own data centre. SharePoint Online and the primedocs instance are never connected directly:

• Only the user's browser mediates between SharePoint and the primedocs instance. It loads the extension from SharePoint and then opens primedocs Web. Microsoft 365 does not connect to the primedocs instance. The instance therefore does not need to be reachable from the internet.
• The primedocs instance talks outbound to Entra ID and Microsoft Graph. No inbound connections from the Microsoft cloud are required.

From	To	Protocol	Purpose
Browser	SharePoint Online (*.sharepoint.com)	HTTPS	Show the library, load extension and configuration
Browser	primedocs instance (TemplatePickerUrl)	HTTPS	Use primedocs Web. The instance must be reachable from the workstations, internal access or VPN is sufficient.
Browser	login.microsoftonline.com (according to authority in primedocs.config)	HTTPS	Sign-in to primedocs through Entra ID
primedocs server	login.microsoftonline.com	HTTPS	Authorise access to Microsoft Graph on behalf of the user
primedocs server	graph.microsoft.com	HTTPS	Save the document to the SharePoint library

If the server's outbound access to graph.microsoft.com is blocked, saving to SharePoint fails.

Installation

Detailed installation instructions can be found under Microsoft SharePoint App Installation.