In Microsoft Flow stehen bereits von Hause aus etliche Workflow Aktionen bereit, um auf SharePoint Online zuzugreifen. Trotzdem gibt es viele Situationen, bei denen die vorhandenen Aktionen nicht ausreichen. oder keine fertige Aktion zur Verfügung steht. Ein Beispiel wäre das Setzen von SharePoint Berechtigungen aus Microsoft Flow heraus.
Andererseits liesse sich über die SharePoint REST API viele Anforderungen umsetzen, wenn man sie denn aus Flow heraus ansprechen könnte. Und genau hier kommt die Microsoft Flow Aktion Send an Http Request to SharePoint ins Spiel, die es seit Anfang Mai 2018 gibt. War es vorher auch schon möglich, die SharePoint REST API aus Flow heraus anzusprechen, so war dies doch sehr aufwendig, da man grosse Hürden bzgl. der Authentifizierung erst mal überwinden musste. Dies versteckt die obige Aktion und man kann sich auf das Benutzen der SharePoint REST API konzentrieren.
Um dies an einem Beispiel zu zeigen, wird das folgende Szenario umgesetzt: In einer Liste werden alle GDPR relevanten Systeme verwaltet. Die Einträge müssen von verschiedenen Stellen genehmigt werden. Erst wenn alle Stellen genehmigt haben, ändert sich der Status auf „all approved“. Ist dies erfolgt, soll der Eintrag nur noch gelesen und nicht mehr geändert werden können. Hierzu muss die Berechtigung auf den Eintrag so angepasst werden, dass dieser nur noch Leserechte besitzt. Eine Aktion zum Setzen der Berechtigung auf einen Eintrag (oder auch ein Dokument) existiert wie gesagt in Flow nicht. Es gibt zwar Erweiterungen von Drittherstellen (siehe beispielsweise https://docs.microsoft.com/en-us/connectors/plumsailsp/), diese sind jedoch kostenpflichtig. Über die SharePoint REST API kann man dies aber bewerkstelligen.
Im ersten Teil von diesem zweiteiligen Beitrag geht es darum, die notwendigen REST Aufrufe zu definieren und ein Tool zu benutzen, mit welchem man die REST API Aufrufe testen kann.
Die Grundlagen verstehen
Zunächst einmal sollte man sich mit den Grundlagen der SharePoint REST/OData APIs beschäftigen und auch die möglichen REST API Funktionen kennenlernen. Zwei gute Ressourcen findet man unter den folgenden URLs:
Aus den Informationen der obigen online Resourcen wird man jedoch kaum direkt die Aktion Send an Http Request to SharePoint von Microsoft Flow konfigurieren können. Vielmehr ist es notwendig, dass man die gewünschten Aktionen erst einmal ausprobiert.
Für unser Beispiel (Setzen der Berechtigungen) wären dabei die folgenden Schritte notwendig:
Unterbrechen der Berechtigungsvererbung ohne Übernahme geerbten Berechtigungen REST API (POST): _api/web/lists/getByTitle(‚Name der Liste‚)/items(ID)/breakroleinheritance(copyRoleAssignments=false, clearSubscopes=true)
Setzen der Berechtigungen für die gewünschten SharePoint Gruppen REST API (POST): _api/web//getByTitle(‚Name der Liste‚)/items(ID)/roleassignments/addroleassignment(principalid=<Group-ID>,roleDefId=<Role-ID>)
Unterstützende SharePoint REST API Aufrufe sind zudem:
Erben der Berechtigungen REST API (POST): _api/web/lists/getByTitle(‚Name der Liste‘)/items(ID)/ResetRoleInheritance()
Ermitteln der ID einer bestimmten Berechtigungsstufe (z.B. für Leserechte) REST API (GET): _api/web/roledefinitions/GetByName(‚Name der Berechtigungsstufe‘)/Id
Ermitteln der ID einer bestimmten SharePoint Gruppe REST API (GET): _api/web/sitegroups/GetByName(‚Namer der Gruppe‘)/Id
SharePoint REST Calls, welche die GET Methode nutzen, könnte man direkt anhand der URL im Browser ausführen lassen. Das Ergebnis ist aber nicht gerade anschaulich. Z.B. liefert der folgende Aufruf (alle Listen innerhalb einer Site):
Mit dem Tool „Postman“ die REST API Aufrufe testen
Bei unseren REST API Aufrufen zum Setzen der Berechtigungen handelt es sich jedoch zumeist um POST Aufrufe der REST API, und dies kann in der Browser URL nicht umgesetzt werden. Deshalb bietet sich für das Testen der notwendigen REST API Aufrufe das Tool Postman an. Nach Installation und Konfiguration von Postman kann man beliebige REST Aufrufe absetzen, und kann die Ergebnisse auf verschiedene Weise begutachten. Postman stellt sich allerdings zunächst etwas störrisch an, wenn es darum geht, REST API Aufrufe an SharePoint Online abzusetzen. Dies liegt daran, dass eine Anwendung, die auf die SharePoint REST API zugreifen will, zuerst im Azure Active Directory registriert werden muss. Danach kann man Postman zusammen mit SharePoint verwenden.
Um die Postman App für den Zugriff auf SharePoint Online zu registrieren, sind die folgenden Schritte notwendig:
Login in die Azure Subscription unter https://portal.azure.com, welche im entsprechenden Office 365 Tenant benutzt wird. Navigieren zu Azure Active Directory, App registrations im Menü aufrufen und New application registration auswählen.
In den Feldern dann die folgenden Parameter eingeben. Für die Sign-on URL den Wert https://www.getpostman.com/oauth2/callback angeben. Danach auf Create klicken, um die App Registration anzulegen.
Nach dem Anlegen der App Registration die Application ID kopieren und ggf. in Notepad zwischenspeichern.
Dann auf Settings klicken, um die Berechtigungen für die App einzustellen. In den Settings auf Required permissions klicken.
Dann auf Add klicken und im Punkt 1 (Select an API) Office 365 SharePoint Online auswählen. Im Punkt 2 jeweils die Option Have full control of all site collections auf Yes setzen.
Zurück in die Settings der App Registration und dort auf Keys klicken und eine Beschreibung und Ablaufdatum eintragen.
Auf Save klicken und den erzeugten Key kopieren z.B. in Notepad, da er nur einmal angezeigt wird.
Postman App aufrufen, einen neuen Request öffnen durch Klick auf das Pluszeichen.
Eintragen der jeweiligen API URL: z.B. https://Url-der-website/_api/web/lists
Im Reiter Headers den Wert Accept: application/json; odata=verbose eintragen.
Im Reiter Authorization als Type OAuth 2.0 auswählen, und auf die Schaltfläche Get New Access Token klicken.
Die folgenden Parameter eintragen.
Für Client ID wird die Application ID von Azure in der App Registration eingetragen. Für das Client Secret, wird der erzeugte Key eingetragen. Danach auf Request Token klicken. Im angezeigten Dialog nach unten scrollen und auf Use Token klicken.
Postman ist nun bereit den Request auszuführen, indem man auf Sendklickt. Das Ergebnis kann als JSON Resultat angesehen werden.
In Postman ist es nun sehr einfach einen POST Aufruf abzusetzen, um z.B. die Berechtigungsvererbung für einen Listeneintrag zu unterbrechen.
Beispiel:
https://{onlineURL}/sites/{sitename}/_api/web/lists/getByTitle(‚GDPRSystems‘)/items(1)/breakroleinheritance(copyRoleAssignments=false, clearSubscopes=true)
Das Ergebnis in Postman sieht dann wir folgt aus:
Im zweiten Teil gehts um die Ertellung des Flows
Damit endet der erste Teil dieses zweiteiligen Beitrages. Im zweiten Teil werden wir uns die Erstellung eines Flows ansehen, welcher sich diese Vorbereitungen zunutze macht, und die Berechtigungen für einen Listeneintrag auf „nur lesend“ setzt, sobald ein bestimmter Status erreicht wird. Den zweiten Teil gibts wiederum hier zu lesen im Januar 2019 – bis bald.