SharePoint

Die primedocs-App für SharePoint fügt in Dokumentbibliotheken von SharePoint Online die Schaltfläche primedocs in die Befehlsleiste ein. Ein Klick öffnet primedocs Web in einem neuen Browser-Tab. Das dort erstellte Dokument legt primedocs in der Bibliothek und im Ordner ab, aus denen die Erstellung gestartet wurde.

Diese Seite beschreibt, wie die App technisch arbeitet, was sie auf SharePoint-Seiten tut und welche Verbindungen dabei entstehen. Die Einrichtung steht unter Microsoft SharePoint App-Installation.

Voraussetzungen

• SharePoint Online (Microsoft 365). SharePoint Server (on-premises) wird nicht unterstützt, weil die Ablage über Microsoft Graph erfolgt.
• Anmeldung an primedocs über Entra ID (Office 365). Dokumente werden im Namen des angemeldeten Benutzers in SharePoint gespeichert.
• Die Entra ID App Registration benötigt die Delegated Permissions Sites.ReadWrite.All und Files.ReadWrite.All (siehe Entra ID Apps). Dieselben Scopes und offline_access müssen im Attribut microsoftAppDelegateScopes des Knotens office365Auth in der primedocs.config stehen.
• Es werden ausschliesslich webfähige primedocs Vorlagen unterstützt.
• Unterstützt werden derzeit nur Dokumentbibliotheken in der obersten Website einer Websitesammlung. Aus Bibliotheken in Unterwebsites kann primedocs keine Dokumente speichern.

Bestandteile

Bestandteil	Beschreibung
App-Paket primedocs-sharepoint-extension.sppkg	SharePoint-Framework-Lösung (SPFx) mit einer ListView Command Set Extension. Das Paket enthält das JavaScript der Erweiterung selbst. SharePoint stellt es aus dem App-Katalog bereit, ein externes CDN wird nicht verwendet.
Liste primedocsSettings	SharePoint-Liste mit dem Eintrag TemplatePickerUrl. Er enthält die Adresse der primedocs-Instanz, die die App öffnen soll.
primedocs Web	Webanwendung der primedocs-Instanz (/app/web/sharepoint). Hier wählen Benutzer die Vorlage und füllen die Felder aus.
primedocs-Server	Erstellt das Dokument und speichert es über Microsoft Graph in der Bibliothek.

Eigenschaften des App-Pakets:

• Mandantenweite Bereitstellung: Die App wird einmal im App-Katalog bereitgestellt und ist danach in allen Sites verfügbar, ohne Aktivierung pro Site.
• Kein Custom Script: Die Erweiterung benötigt keine Freigabe von benutzerdefinierten Skripts auf den Sites.
• Keine API-Berechtigungen in SharePoint: Das Paket fordert keine Berechtigungen für Web-APIs an. Im SharePoint Admin Center ist unter «API-Zugriff» nichts zu genehmigen.

Verhalten auf SharePoint-Seiten

Laden der Erweiterung

SharePoint lädt die Erweiterung nur in der modernen Listenansicht von Dokumentbibliotheken. In anderen Listen, auf Seiten und in der klassischen Ansicht ist sie nicht aktiv.

Beim Laden führt die Erweiterung im Browser zwei Lesezugriffe über die SharePoint-REST-API aus, mit den Rechten des angemeldeten Benutzers:

1. Konfiguration lesen: Einträge der Liste primedocsSettings in der aktuellen Site. Ist dort kein Eintrag TemplatePickerUrl vorhanden, liest die Erweiterung dieselbe Liste in der Root-Site des Mandanten (z. B. https://contoso.sharepoint.com).
2. Listentyp prüfen: Eigenschaften der aktuell angezeigten Liste, um sicherzustellen, dass es sich um eine Dokumentbibliothek handelt.

Findet die Erweiterung keine TemplatePickerUrl oder ist die Liste keine Dokumentbibliothek, deaktiviert sie sich für diese Ansicht und die Schaltfläche erscheint nicht.

Darüber hinaus verändert die Erweiterung die Seite nicht. Sie schreibt nichts in SharePoint, liest keine Dokumentinhalte und baut beim Laden keine Verbindung zur primedocs-Instanz auf.

Klick auf die Schaltfläche

Beim Klick liest die Erweiterung den Kontext der aktuellen Ansicht aus und öffnet die TemplatePickerUrl mit folgenden Query-Parametern in einem neuen Browser-Tab:

Parameter	Wert	Bedeutung
saveLocationSharePointSiteId	GUID	ID der SharePoint-Site (Site Collection), in der die Bibliothek liegt.
saveLocationSharePointSiteName	Anzeigename	Titel der Site (nur zur Anzeige).
saveLocationSharePointFolderPath	Server-relativer Teilpfad	Aktueller Ordner relativ zur Bibliothek (Bibliotheks-Wurzel abgeschnitten). Im Wurzelordner leer.
saveLocationSharePointListId	GUID	ID der Dokumentbibliothek (SharePoint-Liste).
saveLocationSharePointListName	Anzeigename	Titel der Dokumentbibliothek (nur zur Anzeige).
saveLocationSharePointUrl	Absolute URL (URL-kodiert)	Adresse der SharePoint-Bibliotheksseite, von der aus geöffnet wurde (für den Link «Zurück zu SharePoint»).
manifestVersion	Versionsnummer	Version des bereitgestellten App-Pakets. primedocs erfasst sie in der Client-Nutzung.

Zum Speichern des Dokuments verwendet primedocs die drei Parameter saveLocationSharePointSiteId, saveLocationSharePointListId und saveLocationSharePointFolderPath. Site- und Bibliotheksname sowie die URL dienen nur der Anzeige.

Beispiel-URL (Werte gekürzt):

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

Der neue Tab wird ohne Verweis auf die SharePoint-Seite geöffnet (noopener, noreferrer). primedocs Web kann die SharePoint-Seite deshalb weder steuern noch auslesen.

Dokumenterstellung und Ablage

1. Start: primedocs Web übernimmt die Parameter und zeigt einen Hinweis an, dass Dokumente in der genannten Site und Bibliothek gespeichert werden. Über den Hinweis kann der Benutzer zu SharePoint zurückkehren oder den SharePoint-Modus verlassen.
2. Anmeldung: Ist der Benutzer noch nicht angemeldet, leitet primedocs Web zur Anmeldung über Entra ID weiter. Dabei erhält der primedocs-Server die Berechtigung, mit den Scopes aus microsoftAppDelegateScopes im Namen des Benutzers auf Microsoft Graph zuzugreifen.
3. Erstellung: Der Benutzer wählt eine webfähige Vorlage, füllt die Felder aus und gibt den Dateinamen an. Das Dokument erzeugt der primedocs-Server, nicht der Browser.
4. Ablage: Der primedocs-Server lädt das Dokument über Microsoft Graph in die Bibliothek und den Ordner hoch. Existiert bereits eine Datei mit diesem Namen, erhält das neue Dokument einen eindeutigen Namen. Bestehende Dateien werden nicht überschrieben.
5. Ergebnis: primedocs Web zeigt den Namen des gespeicherten Dokuments an und bietet an, es zu öffnen.

Alle Graph-Aufrufe erfolgen delegiert, also mit den SharePoint-Rechten des angemeldeten Benutzers. Hat der Benutzer in der Bibliothek keine Schreibrechte, schlägt die Ablage fehl.

Berechtigungen

primedocs erhält in SharePoint keine eigenen Rechte. Alle Zugriffe erfolgen im Namen des angemeldeten Benutzers und sind auf dessen SharePoint-Rechte begrenzt.

Im Betrieb

Wer	Berechtigung	Wofür
SharePoint-App im Browser	Keine eigene Berechtigung. Sie nutzt die SharePoint-Sitzung des Benutzers.	Liste primedocsSettings und Eigenschaften der Bibliothek lesen
Benutzer	Lesen auf der Liste primedocsSettings	Ohne Leserecht auf die Liste der Site und der Root-Site findet die App keine Konfiguration und zeigt die Schaltfläche nicht an.
Benutzer	Dateien hinzufügen in der Zielbibliothek (z. B. Berechtigungsstufe «Mitwirken»)	primedocs legt das Dokument mit diesen Rechten ab.
primedocs-Server (Microsoft Graph, delegiert)	Sites.ReadWrite.All, Files.ReadWrite.All	Bibliotheken der Site lesen, um das Laufwerk zu ermitteln, und das Dokument hochladen. Dieselben Berechtigungen nutzt primedocs für die Ablage in Teams-Kanälen und OneDrive.
primedocs-Server (Microsoft Graph, delegiert)	offline_access	Ablage auch dann, wenn die Anmeldung des Benutzers schon länger zurückliegt, ohne erneute Anmeldung.

Der Zusatz «All» bedeutet bei delegierten Berechtigungen nicht, dass primedocs auf alle Sites zugreifen kann. Microsoft Graph wendet delegierte Berechtigungen nur im Rahmen der Rechte des angemeldeten Benutzers an. primedocs liest und schreibt deshalb nur dort, wo der Benutzer selbst lesen und schreiben darf.

Die SharePoint-App und die Ablage in SharePoint verwenden keine Application Permissions (Zugriff ohne Benutzer). Der primedocs-Server greift im Namen eines Benutzers ausschliesslich auf Microsoft Graph zu, um ein von diesem Benutzer erstelltes Dokument in SharePoint, Teams oder OneDrive abzulegen.

Eine Einschränkung auf einzelne Sites über die Graph-Berechtigungen ist nicht vorgesehen. Wo primedocs zur Verfügung steht, steuern die Bereitstellung der App (siehe unten) und die SharePoint-Rechte der Benutzer.

Für die Einrichtung

Aufgabe	Benötigte Rolle
App-Paket in den App-Katalog hochladen und bereitstellen	SharePoint-Administrator
Liste primedocsSettings anlegen und Leserechte vergeben	Besitzer der jeweiligen Site
Delegated Permissions der Entra ID App Registration zustimmen (Admin-Consent)	Administrator mit dem Recht, in Entra ID die Zustimmung für die Organisation zu erteilen

Bereitstellung auf ausgewählten Sites

primedocs muss nicht in allen Sites erscheinen. Es gibt zwei Wege, die App auf bestimmte Sites zu beschränken:

• Über die Konfiguration: Die App bleibt für alle Sites bereitgestellt, die Liste primedocsSettings liegt aber nicht in der Root-Site des Mandanten, sondern nur in den gewünschten Sites. In allen anderen Sites zeigt die App die Schaltfläche nicht an.
• Über die Installation: Die App wird nicht für alle Sites bereitgestellt, sondern in jeder gewünschten Site einzeln hinzugefügt. In allen anderen Sites wird die Erweiterung gar nicht geladen.

Die Schritte stehen unter Nur auf ausgewählten Sites bereitstellen.

Betrieb mit einer On-Premises-Instanz

Die App funktioniert auch, wenn die primedocs-Instanz im eigenen Rechenzentrum betrieben wird. SharePoint Online und die primedocs-Instanz sind dabei nie direkt miteinander verbunden:

• Zwischen SharePoint und der primedocs-Instanz vermittelt ausschliesslich der Browser des Benutzers. Er lädt die Erweiterung aus SharePoint und öffnet anschliessend primedocs Web. Microsoft 365 baut keine Verbindung zur primedocs-Instanz auf. Diese muss deshalb nicht aus dem Internet erreichbar sein.
• Die primedocs-Instanz spricht ausgehend mit Entra ID und Microsoft Graph. Eingehende Verbindungen aus der Microsoft-Cloud sind nicht nötig.

Von	Nach	Protokoll	Zweck
Browser	SharePoint Online (*.sharepoint.com)	HTTPS	Bibliothek anzeigen, Erweiterung und Konfiguration laden
Browser	primedocs-Instanz (TemplatePickerUrl)	HTTPS	primedocs Web nutzen. Die Instanz muss von den Arbeitsplätzen aus erreichbar sein, intern oder über VPN genügt.
Browser	login.microsoftonline.com (gemäss authority in der primedocs.config)	HTTPS	Anmeldung an primedocs über Entra ID
primedocs-Server	login.microsoftonline.com	HTTPS	Zugriff auf Microsoft Graph im Namen des Benutzers autorisieren
primedocs-Server	graph.microsoft.com	HTTPS	Dokument in der SharePoint-Bibliothek speichern

Ist der ausgehende Zugriff des Servers auf graph.microsoft.com gesperrt, schlägt die Ablage in SharePoint fehl.

Installation

Detaillierte Installationsanweisungen finden sich unter Microsoft SharePoint App-Installation.