SharePoint Workflow 2013 REST API

In diesem Beitrag möchte ich euch exemplarisch die Funktionalität der SharePoint Workflow 2013 REST API vorstellen. Die 2013er Workflow Engine von SharePoint bietet die Möglichkeit Webdienste aufzurufen. Damit ergeben sich unzählig neue Möglichkeiten, die sonst nur über Code Lösungen möglich gewesen wären. Damit man 2013er Workflows nutzen kann benötigt man entweder SharePoint Online oder einen Workflow Manager Server in der On Premise Welt (Eine Installationsanleitung findet Ihr hier: Installation Workflow Manager für SharePoint 2013).

Zur besseren Erklärung der SharePoint Workflow 2013 REST API werden wir uns ein ganz konkretes Szenario ansehen: Wir haben eine SharePoint Site Collection mit mehreren Unterwebsites. In den Unterwebsites läuft ein Workflow, der Daten in die Root Site der Site Collection schreiben möchte. Zusätzlich soll der Benutzer in der Zielliste nur lesend darauf zugreifen können. Somit muss der Workflow unter einem anderen Benutzer ausgeführt werden. Ohne die 2013er Workflow Engine hätte man schlechte Karten, aber durch Nutzung der REST API ist dies nun möglich.

Öffnen wir also den SharePoint Designer und legen einen Workflow an. Wichtig ist dabei nur, dass auch als Plattform der 2013er Workflow ausgewählt wird.

Nachdem der Workflow Daten auf einer anderen Site schreiben soll, benötigt man hierfür einen App Schritt. Hierfür müssen zuerst noch einige Voraussetzungen geschaffen werden. Damit der App Schritt im SharePoint Designer überhaupt zur Verfügung steht, muss das entsprechende Feature auf der jeweiligen Site aktiviert werden.

Sollte der App Schritt im SharePoint Designer nicht auftauchen nachdem man das Feature aktiviert hat, hilft meistens ein Neustart vom SharePoint Designer.

Bisher haben wir aber nur die Grundlage für das Schreiben und Lesen in einer anderen Site geschaffen. Die eigentliche Berechtigung fehlt allerdings noch. Diese legen wir jetzt an. Der 2013er Workflow verhält sich hierbei analog zu den SharePoint Apps. Zuerst brauchen wir also die ID von unserem Workflow. Hierzu veröffentlichen wir den noch leeren Workflow einmal, damit dieser eine ID zugewiesen bekommt. Danach findet man die ID unter den Website-App-Berechtigungen in den Websiteeinstellungen.

Die App-ID ist der Teil, der nach dem „|“ beginnt und vor dem „@“ Zeichen endet. Also ganz einfach. 🙂

Unsere „Workflow App“ benötigt also nun Zugriff auf die andere Site, bei uns also der Root Site Collection. Dazu rufen wir folgende URL auf: https://<RootSiteUrl>/_layouts/15/appinv.aspx. Diese Seite ist nirgends verlinkt und muss deshalb manuell aufgerufen werden.

Die App-ID unseres Workflows muss hier eingetragen werden und danach der Button Nachschlagen gedrückt werden. Alle Felder bis auf das Berechtigungsanforderungs-XML werden dadurch automatisch ausgefüllt. In das verbleibende Feld muss folgendes XML eingetragen werden:

<AppPermissionRequests>
   <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />
</AppPermissionRequests>

Nach der Bestätigung unserer Eingabe erscheint danach die Aufforderung, unserem Workflow zu vertrauen.

Jetzt kann unser Workflow auch auf die Root Site Collection zugreifen und wir können endlich mit dem eigentlichen Workflow starten.

Am Einfachsten zeige ich Euch zuerst den ganzen Workflow im SharePoint Designer und erkläre danach die einzelnen Punkte.

Wie man auf dem ersten Blick erkennen kann, muss man bei der SharePoint Workflow 2013 REST API ziemlich viel mit Wörterbüchern arbeiten. 🙂

In Zeile 1 wird lediglich der Start des Workflows protokolliert. Man sollte allerdings niemals ein Wörterbuch in der Verlaufsliste protokollieren, weil dadurch ein Fehler generiert wird und der Workflow nicht mehr funktioniert.

In Zeile 2 erstellen wir ein Wörterbuch für den Header des REST Aufrufs.

Folgende Einträge müssen hierbei hinterlegt werden:

Name	Type	Value
Accept	Zeichenfolge	application/json; odata=verbose
Content-Type	Zeichenfolge	application/json; odata=verbose

Noch ein kleiner Hinweis, dass der Header je nach gewollter Aktion unterschiedlich sein kann. Dieser Header funktioniert nur, wenn wir einen Eintrag hinzufügen wollen. Möchten wir einen bestehenden Eintrag ändern, muss dieser zwingend angepasst werden.

In Zeile 3 bauen wir uns die notwendigen Metadaten für den Request zusammen. Das funktioniert auch wieder über ein Wörterbuch, dass folgende Daten enthält:

Name	Type	Value
type	Zeichenfolge	SP.Data.ListeListItem

Hierbei ist zu beachten, dass der interne Name der Liste (wo der Eintrag erstellt werden soll) entsprechend berücksichtigt wird. In unserem Beispiel hat die Liste den Namen Liste. Dieser Teil muss bei einem anderen Namen entsprechend geändert werden.

 

In Zeile 4 und 5 bauen wir die Datenstruktur auf, die wir für ein URL-Feld im SharePoint benötigen. Hier kann nicht einfach die URL als String übergeben werden, weil die interne Datenstruktur von diesem Typ doch etwas komplexer ist. Im Wörterbuch in Zeile 4 definieren wir erst einmal nur den Typ, dass es sich hierbei um eine URL handelt:

Name	Type	Value
type	Zeichenfolge	SP.FieldUrlValue

In Zeile 5 definieren wir dann erst die eigentlichen Parameter für die URL, also Typ, Bezeichnung und die eigentliche URL:

Name	Type	Value
__metadata	Wörterbuch	Variable: urlField
Description	Zeichenfolge	Google
Url	Zeichenfolge	https://www.google.de

In Zeile 6 wird dann das Wörterbuch mit allen unseren Daten erstellt:

Name	Type	Value
__metadata	Wörterbuch	Variable: metadata
Title	Zeichenfolge	Eintrag vom Workflow erstellt
VerantwortlichId	Ganze Zahl	Benutzer-ID
URL	Wörterbuch	Variable: urlFieldMeta

Wir erstellen einen Eintrag in einer Liste also mit dem Titel „Eintrag vom Workflow erstellt“, der URL von Google und füllen ein Personenfeld mit dem Namen VerantwortlichId aus. Hier funktioniert die SharePoint Workflow 2013 REST API so, dass die Benutzer-ID übergeben wird. Diese muss man sich entsprechend vor der Verwendung besorgen. Zu beachten ist auch, dass dem (internen) Namen des Personenfelds das Suffix „Id“ angehängt wird. Im SharePoint heißt das Feld also nur Verantwortlich.

Die HTTP-Anforderung führen wir dann im eigentlich App-Schritt aus, damit wir auch auf andere Sites zugreifen können (siehe Beschreibung weiter oben).

Die URL für unsere Anforderung lautet: https://<RootSiteUrl>/_api/web/lists/getbytitle('<NameDerListe>')/items. Diese URL kann natürlich auch per Browser getestet werden.

Hier findet man auch solche Dinge wieder, wie das Feld VerantwortlichId.

Die HTTP-Methode für das Hinzufügen ist HTTP POST. Das Wörterbuch mit den Parametern aus Zeile 6 wird ebenfalls übergeben. Wichtig ist nur noch den Header entsprechend zu setzen. Dies geschieht durch einen Rechtsklick auf die Aktion und die Auswahl der Eigenschaften.

Dort wird beim Parameter RequestHeaders unser erstelltes Wörterbuch aus Zeile 2 hinterlegt.

Die restlichen Aktionen und Ausgaben im Workflow sind eigentlich selbsterklärend. Wir protokollieren den Response Code von unserer HTTP-Anforderung (wenn alles gut läuft, sollte Created zurückgegeben werden) und beenden den Workflow.

Damit sind wir auch mit unserem Beispiel am Ende und wir können nun per Workflow Einträge in einer anderen Site hinzufügen. Natürlich gibt es eine Vielzahl weiterer Möglichkeiten, die SharePoint Workflow 2013 REST API zu nutzen und dieser Artikel soll nur den Einstieg etwas erleichtern.

In diesem Sinne,

Happy SharePointing…