Microsoft Tech Blog

Blogbeitrag: Office 365 – Erweiterung der Flow Funktionalitäten mittels Office Graph API

Was wollen wir in diesem Beitrag behandeln?

Flow und Azure Logic App bieten mittlerweile schon einen sehr großen Funktionsumfang und werden stetig seitens Microsoft erweitert. Allerdings gibt es immer noch Aktionen, die mit einem Flow oder einer Logic App nicht abgedeckt werden können. Beispielsweise das Erstellen von Kalendereinträgen für verschiedene Benutzer oder das automatisierte Erstellen von einem Microsoft Team für eine Office 365 Gruppe.

In diesem Artikel möchten wir Ihnen zeigen wie Sie mit einem Flow die Graph API aufrufen und somit den Funktionsumfang von Flow noch einmal drastisch erhöhen können, um auch komplexere Business Anforderungen umzusetzen.

 

Die Grundlagen,  aber gleich geht’s los. Versprochen!

Bevor wir jedoch an die Umsetzung gehen, sollten wir uns die Graph API bzw. wie wir uns dort authentifizieren können noch einmal genauer anschauen.

Die Graph API kann in einem App Kontext oder in einem User Kontext aufgerufen werden. Kurz gesagt erfolgt die Anmeldung im App Kontext mit einer APP ID und einem App Secret während im Benutzer Kontext zusätzlich noch ein Benutzer angemeldet sein muss. In unserem Beispiel konzentrieren wir uns auf den App Kontext. Der genaue Unterschied wird in unserem nächsten Blog Artikel erläutert.

Allerdings sei noch erwähnt, dass mit dem App Kontext nicht alle Aktionen der Graph API genutzt werden können wie beispielsweise das Erstellen von Checklisten für ein Planner Task. Hier wird zusätzlich noch ein Benutzer benötigt: eine sogenannte Delegated Permission (App + User Kontext).

Welche Berechtigungen benötigt werden, finden Sie in der Dokumentation der Graph API https://developer.microsoft.com/en-us/graph unter der entsprechenden Aktion.

Nachfolgend ein Beispiel für das Erstellen von Office 365 Groups.

Erstellen einer Office 365 Group

 

 

Build – Wir machen uns endlich an die Arbeit

Jetzt wollen wir aber an das Erstellen des Flows bzw. der App gehen. In unserem Szenario haben wir eine Custom Task Liste in SharePoint und möchten zusätzlich noch einen Kalendereintrag für den Benutzer erstellen, der als Ansprechpartner definiert wurde. Die Flow Action „Create Event“ stößt hier schnell an ihre Grenzen, die Graph API jedoch nicht.

In SharePoint sieht das Ganze dann so aus:

 

SharePoint

 

Schritt 1: Erstellen der Azure AD App

Wie vorhin schon erwähnt, melden wir uns an der Graph API mittels eines App Kontext an. Diese App erstellen wir jetzt. Dazu rufen wir die URL https://apps.dev.microsoft auf und melden uns mit dem Globalen Admin Konto an. Oben rechts können wir nun eine neue App hinzufügen.

Azure App erstellen

Azure App erstellen

 

Anschließend geben wir der App einen Namen und erstellen diese.

 

Azure App registrieren

 

Wir kommen nun zur Übersichtsseite der App, in der wir nun ein neues Passwort erstellen sowie die Berechtigungen der App zuweisen müssen. Für das Passwort gehen wir auf “Generate New Password” und sichern uns dieses, da wir es im Nachhinein nicht mehr ansehen können.

 

Ein Kennwort generieren

Ein Kennwort generieren

 

Als nächstes müssen wir die App Berechtigungen festlegen. Hierzu gibt die Graph Dokumentation Auskunft darüber, welche Berechtigungen wir brauchen, um Kalendereinträge zu lesen und zu erstellen.

Berechtigungen festlegen

Berechtigungen festlegen

 

Diese stellen wir jetzt ein in dem wir unter dem Reiter “Application Permissions Add” wählen und “Calendars.Read.Write” auswählen.

 

Berechtigungen auswählen

Berechtigungen auswählen

 

Nun speichern wir das Ganze und sind mit der Erstellung der App fertig und können an die Erstellung des Flows gehen.

 

Schritt 2: Erstellen des Flows

Dazu erstellen wir uns zuerst einen blanken Flow. Als Trigger nutzen wir SharePoint „wenn ein Item erstellt wird“ und geben unsere Task Liste an. Jetzt müssen wir uns mit unserer vorhin erstellten App am Azure AD anmelden, um ein Bearer Token zu bekommen, welches wir der Graph API für die Authentifizierung mitgeben.

Dazu nutzen wir eine HTTP Action und setzen als Methode POST. In den erweiterten Einstellungen stellen wir die Authentifizierung auf “Active Directory Oauth”. Jetzt müssen wir folgende Werte eintragen:

Authority -> https://login.microsoft.com

Tenant -> ID des Tenant (Diese steht im Azure Portal unter Azure Active Directory -> Eigenschaften).

Audience -> https://graph.microsoft.com

ClientID: die App ID unsere vorher erstellten App

Credential Type -> Secret

Client Seceret: Das App Secret unsere vorher erstellten App

Das Ganze sieht wie folgt aus:

 

Flow erstellen

Flow erstellen

 

Wenn wir uns noch einmal die Dokumentation der Graph API ansehen, sehen wir, dass der Post Request folgendermaßen aufgebaut ist:

 

POST /users/{id | userPrincipalName}/calendar/events

 

“Events” ist dabei der Standard Kalender des Benutzers. Genau diese URL werden wir uns jetzt zusammenbauen. Wir möchten das Event ja für den Benutzer erstellen, der in dem SharePoint Item angegeben ist. Da unser Flow startet, wenn ein Element erstellt wird, können wir den Benutzer einfach als Variable nutzen. Wir nutzen den V1 Endpunkt der Graph API, da wir keine delegated Permissions verwenden und erhalten dadurch folgende URL:

 

https://graph.microsoft.com/v1.0/users/FlowVariableBenutzer/calendar/events

HTTP Post Methode

HTTP Post Methode

 

Als Header nutzen wir:

Content-type -> application/json

Wenn wir nun noch einmal einen Blick in die Dokumentation werfen, sehen wir welche Eigenschaften im Body angegeben werden müssen/können. In unserem Fall z.B. Zeitzone, Titel des Events, Datum etc.

CONTENT

 

Wenn wir uns im Body das Datum für das Event ansehen, dann können wir dort sehen, dass eine Uhrzeit benötigt wird.

Start event

Start event

 

Im SharePoint haben wir nur ein Datumsfeld genutzt. Nun haben wir mehrere Möglichkeiten dieses zu formatieren, da wir in SharePoint Datum und Uhrzeit einstellen oder das Event als Ganztages Event definieren können.

In diesem Fall machen wir es uns einfach und setzen immer eine feste Start- und Endzeit. Dazu fügen wir vor der HTTP Action in Flow zwei Compose Actions ein. Einmal mit dem Input “SharePoint Item Fälligkeitsdatum”T12:00:00 für Termin Anfang und einmal für Termin Ende mit “SharePoint Item Fälligkeitsdatum”T14:00:00”

 

Office Flow

Office Flow

 

Jetzt können wir unseren Body zusammenbauen. Eigenschaften können natürlich variiert, hinzugefügt oder weggelassen werden. In unserem Beispiel sieht der Body wie folgt aus:

Flow Body

Flow Body

 

Test – Wir überprüfen unsere Lösung

Anschließend speichern wir das Ganze noch und können unseren Flow testen. Zuerst erstellen wir uns ein neues Item im SharePoint.

 

Item in SharePoint Liste erzeugen

Item in SharePoint Liste erzeugen

 

Anschießend gehen wir in die History des Flows und sehen uns den Status an.

 

Flow History

Flow History

 

Wir sehen, dass dieser erfolgreich gelaufen ist. Wenn wir jetzt in unseren Kalender gehen, sehen wir den Eintrag für die SharePoint Aufgabe.

 

Kalender

Kalender

 

Kalenderdetails

Kalenderdetails

 

Somit haben wir in wenigen Schritten unsere Flow Actions mit dem Funktionsumfang der Graph API drastisch erhöht.