Dokumentation der API

SharePoint

Stonewake läuft in Ihren Seiten in SharePoint und in Microsoft Teams und legt seine Berichte in Ihren Dokumentbibliotheken ab. Jeden Teil richten Ihre eigenen Administratoren ein. Eine Seite zeigt Stonewake über das Standardwebpart Einbetten oder über die Stonewake App für SharePoint und Teams, und Berichte und Ausschusspakete als PDF gelangen in eine Bibliothek, entweder über die Lieferung durch Stonewake oder über einen Flow in Power Automate. Diese Seite ist die Anleitung für die Administratoren, die das einrichten.

Stonewake auf einer Seite in SharePoint

So funktioniert es

  • Ein Administrator des Arbeitsbereichs führt die Websites in SharePoint auf, die Stonewake anzeigen dürfen, jede mit ihrer genauen Adresse, zum Beispiel https://yourbank.sharepoint.com. Nur diese Websites können die Einbettungsadresse des Arbeitsbereichs in einem Frame zeigen. Jede andere Seite von Stonewake lehnt die Einbettung durch jede Website ab, mit frame-ancestors 'none' und X-Frame-Options: DENY.
  • Die Liste ist für jeden Arbeitsbereich leer, bis ein Administrator eine Website hinzufügt. Eine Adresse mit Platzhalter wie *.sharepoint.com wird abgelehnt, weil sie die Seiten jedes Kunden bei Microsoft zulassen würde. Ebenso eine Adresse mit Pfad, mit Port oder mit einfachem http.
  • Jede Änderung der Liste wird mit der Liste davor und danach im Prüfpfad Ihres Arbeitsbereichs erfasst.
  • Mitglieder melden sich mit ihrem eigenen Konto bei Stonewake an. Die Anmeldung öffnet sich in einem eigenen Fenster auf der Adresse von Stonewake, weil Microsoft und die meisten Identitätsanbieter keine Anmeldeseite in einem Frame zeigen. Das Fenster übergibt die Sitzung an die Seite von Stonewake im Frame und schließt sich. Die Nachricht geht nur an die Adresse von Stonewake, die Seite in SharePoint mit dem Frame erhält nichts.
  • Im Frame liegt die Sitzung nur im Arbeitsspeicher. Kein Cookie und kein Browserspeicher hält sie, und nach dem Neuladen der Seite in SharePoint ist eine neue Anmeldung nötig.
  • Eine Anmeldung in einem anderen Arbeitsbereich wird abgelehnt und sofort beendet, sodass eine Seite, die ein Arbeitsbereich zugelassen hat, nie Daten eines anderen Arbeitsbereichs zeigt.
  • Die Verwaltung des Arbeitsbereichs öffnet sich nicht im Frame. Schlüssel für die API, Mitglieder, die Anmeldeeinstellungen und diese Liste der Websites öffnen sich in einem eigenen Tab von Stonewake, und die API lehnt solche Änderungen ab, wenn sie aus einer eingebetteten Seite kommen.

Einrichtung

  • Schritt 1. Öffnen Sie in Stonewake die Einstellungen des Arbeitsbereichs, dann Seiten in SharePoint, dann Websites in SharePoint verwalten. Fügen Sie die Adresse Ihrer Website in SharePoint hinzu, https://<tenant>.sharepoint.com. Eine Adresse in OneDrive, https://<tenant>-my.sharepoint.com, ist eine eigene Website und braucht einen eigenen Eintrag.
  • Schritt 2. Kopieren Sie die Adresse für das Webpart Einbetten, https://app.stonewake.ai/embed/<embed id>. Die ID der Einbettung ist ein Zufallsschlüssel Ihres Arbeitsbereichs und nennt weder eine Bank noch eine Person.
  • Schritt 3. Ein Websitesammlungsadministrator erlaubt Stonewake auf der Website unter Websiteeinstellungen, HTML-Feldsicherheit, indem er app.stonewake.ai zu den Domänen hinzufügt, deren Inhalte eingebettet werden dürfen. Microsoft beschreibt die Einstellung unter Allow or restrict the ability to embed content on SharePoint pages.
  • Schritt 4. Fügen Sie auf einer Seite das Webpart Einbetten hinzu und setzen Sie diesen Einbettungscode mit der Adresse aus Schritt 2 ein, <iframe src="https://app.stonewake.ai/embed/<embed id>" width="100%" height="900"></iframe>. Eine reine Adresse nimmt das Webpart nur von Websites mit eigenem Einbettungsdienst an, deshalb kommt Stonewake als Einbettungscode auf die Seite. Microsoft beschreibt das Webpart unter Use the Embed web part. Veröffentlichen Sie die Seite.
  • Schritt 5. Mitglieder öffnen die Seite und wählen Anmelden. Ihr Browser muss der Website in SharePoint erlauben, ein Fenster zu öffnen.

Voraussetzungen

  • Die Seite liegt in SharePoint Online, ihre Adresse beginnt also mit https:// und endet mit .sharepoint.com.
  • Der Frame darf ein Fenster öffnen. Ein Frame in einer Sandbox, die Popups sperrt, kann das Anmeldefenster nicht zeigen.
  • Mit SSO für Ihren Arbeitsbereich bietet das Anmeldefenster neben der Anmeldung mit Passwort Mit Ihrer Organisation fortfahren an.
  • Die Stonewake App für SharePoint und Teams ist eine eigene Integration mit eigener Einrichtung, beschrieben im nächsten Teil dieser Seite.

Die Stonewake App für SharePoint und Teams

So funktioniert es

  • Die Stonewake App ist ein einziges SharePoint Framework Paket, stonewake.sppkg. Es fügt Seiten in SharePoint ein Stonewake Webpart hinzu und Microsoft Teams eine Stonewake App, die sich als persönliche App oder als Registerkarte eines Kanals öffnet. Beide zeigen das Team der Person, die Übersicht des Portfolios, die fünf neuesten Statusänderungen und einen Link zu Stonewake.
  • Die Person ist über SharePoint mit ihrem Konto bei Microsoft angemeldet. Das Webpart bittet Microsoft über den eigenen Client von SharePoint um ein Token für die Anwendung Stonewake API mit der Berechtigung Workspace.Read und liest damit https://api.stonewake.ai/v1. Weder ein Passwort für Stonewake noch ein Anmeldefenster ist dabei nötig.
  • Stonewake nimmt ein solches Token nur aus dem Mandanten bei Microsoft an, den Ihr Arbeitsbereich für SSO nachgewiesen hat, nur für Stonewake API mit Workspace.Read und nur auf /v1. Das Token gilt nur für die eigene Anmeldung bei Stonewake der Person, deren Anmeldung bei Microsoft dieselbe Objektkennung bei Microsoft angegeben hat, und wird nie über den Abgleich einer Mailadresse zugeordnet. Eine Person ohne solche Anmeldung sieht einen kurzen Hinweis und keine Daten.
  • Die App liest nur. Jede Abfrage zeigt, was ein Betrachter des eigenen Teams der Person sieht, unabhängig von ihrer Rolle im Dashboard, weil SharePoint eine Berechtigung für die API jeder SharePoint Framework Lösung in Ihrem Mandanten gewährt.
  • Nur Ihre eigene Adresse in SharePoint darf Stonewake aus dem Browser aufrufen. Stonewake fügt sie für Ihren Arbeitsbereich hinzu, sobald der öffentliche Eintrag von Microsoft zeigt, dass sie zu Ihrem Mandanten gehört, und jede andere Website erhält keine Antwort, die sie lesen kann.
  • Stonewake erhält das Token und sonst nichts aus SharePoint, keine Seite, keine Datei und keine Liste.

Einrichtung

  • Schritt 1. Richten Sie SSO mit Microsoft Entra ID für Ihren Arbeitsbereich ein. Jede Person meldet sich einmal mit Microsoft bei Stonewake an, damit ihre Anmeldung ihre Objektkennung bei Microsoft enthält.
  • Schritt 2. Senden Sie Ihrer Ansprechperson bei Stonewake die Adresse Ihres SharePoint, https://<tenant>.sharepoint.com. Stonewake prüft sie gegen den öffentlichen Eintrag von Microsoft, fügt sie für Ihren Arbeitsbereich hinzu und sendet Ihnen das Paket stonewake.sppkg.
  • Schritt 3. Ein Administrator in SharePoint öffnet die Website für Apps, wählt Hochladen und dann stonewake.sppkg. Wählen Sie im Bereich App aktivieren die Option, die App zu aktivieren und allen Websites hinzuzufügen, und für die Teams App die Option Zu Teams hinzufügen. Microsoft beschreibt die Website für Apps unter Manage apps using the Apps site.
  • Schritt 4. Ein Administrator mit der Rolle Anwendungsadministrator oder höher öffnet API-Zugriff im SharePoint Admin Center und genehmigt die ausstehende Anfrage für Stonewake API mit Workspace.Read. Die Genehmigung fügt Stonewake API Ihrer Microsoft Entra ID als eigene Unternehmensanwendung hinzu, neben der Anwendung Stonewake, die Ihr Team für SSO angelegt hat. Microsoft beschreibt die Seite unter Manage access to Microsoft Entra ID-secured APIs.
  • Schritt 5. Ein Administrator für Teams erlaubt die Stonewake App im Teams Admin Center, in Ihren Einstellungen für benutzerdefinierte Apps und Ihren App-Berechtigungsrichtlinien. Microsoft beschreibt die Einstellungen unter Manage custom app policies and settings.
  • Schritt 6. Seitenbearbeiter fügen das Stonewake Webpart einer Seite hinzu. Personen fügen Stonewake in Teams als persönliche App hinzu, und ein Kanalbesitzer kann es als Registerkarte hinzufügen.

Voraussetzungen und Entfernen

  • Ihr Arbeitsbereich meldet sich mit Microsoft SSO an, und die Adresse in SharePoint ist die Stammadresse Ihres Mandanten, https://<tenant>.sharepoint.com. Eine Adresse in OneDrive wird abgelehnt.
  • Ihre Richtlinien für bedingten Zugriff können Stonewake API wie jede andere Anwendung einbeziehen.
  • Zum Entfernen löschen Sie die App aus der Website für Apps, widerrufen Workspace.Read für Stonewake API unter API-Zugriff und bitten Ihre Ansprechperson bei Stonewake, Ihre Adresse in SharePoint zu entfernen. Ein Token, das vor dem Widerruf ausgestellt wurde, endet mit seiner eigenen Laufzeit, höchstens zwei Stunden.

Berichte und Pakete in einer Bibliothek in SharePoint

Die Dokumente

Fünf Endpunkte unter /v1 liefern dieselben Dokumente als PDF, die das Dashboard herunterlädt (siehe Referenz der API).

  • Den Dealbericht und das Ausschusspaket eines Deals, über die ID des Deals, die GET /v1/deals liefert.
  • Den Gegenparteibericht und das Gegenparteipaket, über die ID im Register, die GET /v1/entities liefert.
  • Das Unternehmensprofil, über die ID des Knotens des Graphen, die Treffer von GET /v1/search tragen.

Ein Paket und ein Unternehmensprofil nehmen locale=de oder locale=en an; ohne Angabe gilt die Paketsprache Ihres Arbeitsbereichs.

Lieferung durch Stonewake

Stonewake legt die Dokumente selbst in der Bibliothek ab, über Microsoft Graph und eine App, die Ihre Administratoren in Ihrem eigenen Verzeichnis von Microsoft Entra registrieren. Dieser Weg braucht keine Lizenz für Power Automate und keinen Schlüssel für die API. Ihr Ansprechpartner bei Stonewake schaltet die Lieferung in Bibliotheken für Ihren Arbeitsbereich auf Anfrage frei.

So funktioniert die Lieferung durch Stonewake

  • Ihr Administrator in Entra registriert in Ihrem Verzeichnis eine App für Stonewake und gibt ihr die Anwendungsberechtigung Sites.Selected von Microsoft Graph mit Administratorzustimmung. Mit Sites.Selected allein erreicht die App keine einzige Website.
  • Ihr Administrator in SharePoint gibt dieser App danach Schreibrechte auf genau einer Website. Microsoft beschreibt die Schritte in Overview of Selected permissions in OneDrive and SharePoint. Stonewake schreibt in diese Website und nirgendwo sonst, und Ihre Administratoren können die Freigabe jederzeit zurücknehmen.
  • Ein Administrator des Arbeitsbereichs in Stonewake gibt die ID des Verzeichnisses, die ID der Anwendung, den geheimen Clientschlüssel, die Website, die Bibliothek und den Ordner ein. Der Schlüssel wird im Tresor für Zugangsdaten von Stonewake versiegelt, unter einem Schlüssel, der nie in die Datenbank gelangt, und wird nie wieder angezeigt.
  • Jede Bibliothek gehört zu einem Team Ihres Arbeitsbereichs. Stonewake erstellt ihre Dokumente mit den Leserechten dieses Teams, denselben Rechten wie ein Schlüssel dieses Teams, ein Deal eines anderen Teams wird also nie abgelegt.
  • Die Dokumente sind die fünf Dokumente oben, Byte für Byte, unter dem Dateinamen, den ein Download ihnen gibt und der das Datum trägt. Ein Dokument, das an einem Tag zweimal abgelegt wird, wird zu einer neuen Version derselben Datei.

Lieferung durch Stonewake einrichten

  • Schritt 1. Öffnen Sie im Microsoft Entra Admin Center die App-Registrierungen und wählen Sie Neue Registrierung. Nennen Sie sie Stonewake library delivery und behalten Sie Nur Konten in diesem Organisationsverzeichnis bei. Notieren Sie auf der Übersichtsseite die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant). Microsoft beschreibt die Seite in Registrieren einer Anwendung.
  • Schritt 2. Fügen Sie unter API-Berechtigungen Microsoft Graph, Anwendungsberechtigungen, Sites.Selected hinzu und wählen Sie dann Administratorzustimmung für Ihre Organisation erteilen.
  • Schritt 3. Fügen Sie unter Zertifikate und Geheimnisse einen geheimen Clientschlüssel hinzu und kopieren Sie seinen Wert, den Entra nur einmal zeigt. Wählen Sie die Laufzeit, die Ihre Richtlinie erlaubt, und notieren Sie das Datum, denn die Lieferungen enden, wenn der Schlüssel abläuft.
  • Schritt 4. Ein Administrator in SharePoint gibt der App Schreibrechte auf der einen Website, zum Beispiel im Graph Explorer. Lesen Sie die ID der Website mit GET https://graph.microsoft.com/v1.0/sites/<tenant>.sharepoint.com:/sites/<site> und senden Sie dann POST https://graph.microsoft.com/v1.0/sites/<site id>/permissions mit dem Inhalt {"roles": ["write"], "grantedToIdentities": [{"application": {"id": "<application id>", "displayName": "Stonewake library delivery"}}]}. Microsoft beschreibt die Anfrage in Create permission. Zum Senden braucht es Sites.FullControl.All und eine Rolle wie Administrator in SharePoint.
  • Schritt 5. Öffnen Sie in Stonewake die Einstellungen des Arbeitsbereichs, dann Bibliotheken in SharePoint, Bibliotheken in SharePoint verwalten und Bibliothek verbinden. Geben Sie einen Namen ein, das Team, dessen Dokumente die Bibliothek erhält, die ID des Verzeichnisses, die ID der Anwendung, den Wert des geheimen Clientschlüssels, die Adresse der Website https://<tenant>.sharepoint.com/sites/<site>, die Bibliothek so, wie SharePoint sie nennt (Dokumente für die Standardbibliothek), und einen Ordner darin. Legen Sie den Ordner zuerst in der Bibliothek an, oder lassen Sie das Feld für die oberste Ebene der Bibliothek leer.
  • Schritt 6. Wählen Sie Verbindung prüfen. Stonewake meldet sich als die App an, findet die Website, die Bibliothek und den Ordner und speichert eine kleine Textdatei, Stonewake connection check.txt, in dem Ordner. Die Prüfung gilt nur als bestanden, wenn diese Datei geschrieben ist.
  • Schritt 7. Fügen Sie unter Bearbeiten jedes Dokument mit der ID aus der Adresse seiner Seite des Deals oder Unternehmens hinzu, wählen Sie den Zeitplan, jeden Tag oder jeden Montag um 06:00 UTC, und speichern Sie. Jetzt liefern legt sie sofort ab.

Was die Lieferung durch Stonewake schreibt und festhält

  • Stonewake ruft nur login.microsoftonline.com für das Token der App und graph.microsoft.com für die Website, die Bibliothek, den Ordner und den Upload auf. Einer Adresse, die eine Antwort mitbringt, folgt es nie.
  • Jedes abgelegte Dokument schreibt eine Zeile library_document_delivered mit seiner Größe und seiner Prüfsumme nach SHA-256 in den Prüfpfad Ihres Arbeitsbereichs. Ein Dokument, das Stonewake versucht und nicht ablegt, schreibt eine Zeile library_document_failed mit seinem Grund. Eine Lieferung, die Microsoft aufhält oder ablehnt oder die ihr Zeitlimit erreicht, schreibt eine Zeile library_delivery_failed. Jede Änderung einer Bibliothek, jede Prüfung und jedes Jetzt liefern wird dort ebenfalls erfasst.
  • Ein Dokument, das das Team nicht lesen kann, wird nicht abgelegt und erscheint als für dieses Team nicht lesbar.
  • Eine Bibliothek nimmt höchstens 25 Dokumente und 100 Uploads am Tag auf. Die Bibliotheken eines Arbeitsbereichs werden nacheinander beliefert, und eine Lieferung endet spätestens nach 10 Minuten. Eine Lieferung, die scheitert, etwa weil Microsoft ausgelastet ist oder zu langsam antwortet, wird 30 Minuten später und dann 4 Stunden später erneut versucht, später nur, wenn Microsoft um eine längere Wartezeit bittet, und nie nach dem nächsten geplanten Zeitpunkt der Bibliothek. Eine Bibliothek ohne Zeitplan wird mit dem nächsten Jetzt liefern erneut versucht. Nach drei Fehlschlägen in Folge wartet die Bibliothek, bis ein Administrator die Verbindung erneut prüft.
  • In einer Bibliothek, die neue Dateien mit einer Vertraulichkeitsbezeichnung versieht, lässt Microsoft eine App keine bezeichnete Datei ersetzen. Ein Dokument, das früher am selben Tag abgelegt wurde, bleibt dann unverändert, und die spätere Lieferung hält die Ablehnung fest.
  • Eine Lieferung entwirft nie eine neue Zusammenfassung und löst keinen Modellaufruf aus, wie jeder Download weiter unten.
  • Eine neue Website, Bibliothek oder ein neuer Ordner braucht vor der nächsten Lieferung eine neue Prüfung, und eine laufende Lieferung endet vor ihrem nächsten Upload, wenn sich Website, Bibliothek, Ordner oder Team ändern. Eine abgelehnte Anmeldung, zum Beispiel wegen eines abgelaufenen Schlüssels, stoppt die Lieferungen dieser Bibliothek, bis eine Prüfung wieder besteht.
  • Trennen fragt erst nach einer Bestätigung, beendet die Bibliothek dann endgültig, widerruft ihren Schlüssel im Tresor und stoppt eine laufende Lieferung vor ihrem nächsten Upload. Entfernen Sie die Freigabe der App auf der Website oder löschen Sie die App-Registrierung, um sie auch auf Ihrer Seite zu beenden.

Der Schlüssel

Ein Administrator des Arbeitsbereichs erstellt unter Einstellungen des Arbeitsbereichs, Schlüssel für die API einen Schlüssel mit Darf auch Berichte und Pakete als PDF herunterladen (oder report_downloads auf true, siehe Schlüssel und Zugangsverwaltung). Ohne diesen Berichtsumfang antwortet ein Download mit 403. Der Schlüssel liest genau sein eines Team, ein Deal eines anderen Teams antwortet also mit 404. Bewahren Sie den Schlüssel in einer gesicherten Eingabe Ihres Flows oder im Schlüsselspeicher Ihres Hauses auf, nie in einem Dokument oder auf einer Seite.

Ein Paket mit Power Automate ablegen

Der andere Weg, ohne App-Registrierung in Ihrem Verzeichnis. Der Flow holt jedes Dokument mit einem Berichtsschlüssel ab und speichert es mit dem Connector in SharePoint.

  • Schritt 1. Erstellen Sie in Power Automate einen geplanten Cloudflow, zum Beispiel jeden Montag um 07:00, oder einen Sofortflow.
  • Schritt 2. Fügen Sie die Aktion HTTP hinzu. Methode GET. URI https://api.stonewake.ai/v1/deals/<deal id>/pack.pdf?locale=de. Ein Header, Authorization mit dem Wert Bearer gefolgt vom Schlüssel. Die Aktion HTTP ist in Power Automate ein Premiumconnector.
  • Schritt 3. Schalten Sie in den Einstellungen der Aktion HTTP Sichere Eingaben und Sichere Ausgaben ein, damit Schlüssel und Dokument nicht im Ausführungsverlauf des Flows stehen.
  • Schritt 4. Fügen Sie die Aktion in SharePoint Datei erstellen hinzu. Websiteadresse ist Ihre Website. Ordnerpfad ist der Ordner der Bibliothek, zum Beispiel /Shared Documents/Credit committee. Dateiname ist zum Beispiel Committee pack <deal id> @{utcNow('yyyy-MM-dd')}.pdf. Dateiinhalt ist der Text (Body) der Aktion HTTP.
  • Schritt 5. Speichern Sie den Flow, führen Sie ihn einmal aus und öffnen Sie die Datei in der Bibliothek.

Für mehrere Deals halten Sie deren IDs in einer Liste in SharePoint und legen die Schritte 2 und 4 in Auf alle anwenden über die Elemente der Liste. Ein Bericht oder ein Profil funktioniert genauso, mit der eigenen Adresse aus der Liste oben.

Antworten und Protokoll

  • 200 mit Content-Type: application/pdf und dem Dateinamen in Content-Disposition.
  • 401 für einen fehlenden, widerrufenen oder abgelaufenen Schlüssel. 403 für einen Schlüssel ohne den Berichtsumfang. 404 für eine ID, die der Schlüssel nicht lesen kann.
  • 429 über dem Ratenlimit und 503 mit Retry-After, solange das Rendern ausgelastet ist. Die Standardwiederholungsrichtlinie der Aktion HTTP wiederholt beide.
  • Ein Download entwirft nie eine neue Zusammenfassung. Eine früher entworfene und geprüfte Zusammenfassung wird verwendet, sonst sagt das Dokument, dass es keine enthält, und ein Download löst keinen Modellaufruf aus.
  • Jeder Download wird als report_generated oder pack_generated mit dem Schlüssel, der ihn angefordert hat, im Prüfpfad Ihres Arbeitsbereichs erfasst.
  • Ein Unternehmensprofil oder ein Gegenparteipaket, das Organmitglieder oder Eigentümer nennt, schreibt zusätzlich eine Zeile v1_person_read mit den IDs der Personen, wie jeder Abruf personenbezogener Daten unter /v1.