Nintex Xtensions – Azure Function als Workflow Action

In der Blogserie „Nintex Xtensions“ zeigen wir, wie man seine Workflow Cloud schnell und einfach um eigene Funktionen erweitern kann.

„Nintex Workflowcloud“ ist das neue plattformunabhängige Prozessautomatisierungstool von Nintex. Wie der Name schon vermuten lässt, wird dieses Tool durch einen Cloud-Service zur Verfügung gestellt. Nintex hat sich durch das SharePoint- bzw. Microsoft O365-Plugin „Nintex Workflow für Office 365“ einen Namen gemacht. Die neue Workflow Cloud funktioniert ähnlich, nur dass sie eben nicht mehr abhängig von SharePoint oder Microsoft O365 ist und sie ist relativ simpel erweiterbar. So können eigene Workflowaktionen, sogenannte Xtensions erstellt werden.

In diesem Tutorial wird gezeigt, wie man eine selbst erstellte Serverless Azure Function als Workflowaktion in seiner Workflow Cloud zur Verfügung stellt.

 

Voraussetzungen

• Einen Nintex Workflow Cloud Zugang mit Subscription
• Man sollte mit der Anwendung der Workflowcloud vertraut sein
• Eine Azure Function, wie in diesem Beitrag „Serverless – Meine erste Azure Funktion“ beschrieben. (Dazu wird ein Azure Account und eine Subscription benötigt. In dem Tutorial wird außerdem Visual Studio benutzt, was auch zu empfehlen ist. Im Zweifelsfall, kann man aber auch auf den Editor in Azure oder andere IDEs zurückgreifen).
• Visual Studio Code ist empfehlenswert, aber auch hier können beliebige Texteditoren verwendet werden.

Vorbereitung

Wir haben also wie oben erwähnt eine Azure Function erstellt. Allerdings müssen wir noch eine Kleinigkeit anpassen. Also öffnen wir unser Projekt mit Visual Studios.

Aktuell gibt der Code ein Result-Objekt zurück mit reinem Text. Allerdings benötigt Nintex Workflowcloud immer ein JSON-Objekt als Response. Also müssen wir die Return-Zeile anpassen und als Übergabe für das Result-Objekt ein neues Objekt anlegen. Unsere C# -Code sieht also jetzt so aus

(Änderung: return new OkObjectResult(new { message = responseMessage });):

using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
namespace MyFirstAzureFunction

{
public static class HelloWorldFunction
{
[FunctionName("HelloWorldFunction")]
public static async Task Run(
[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");

          string name = req.Query["name"];

          string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
dynamic data = JsonConvert.DeserializeObject(requestBody);
name = name ?? data?.name;

          string responseMessage = string.IsNullOrEmpty(name)
? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
: $"Hello, {name}.";

          return new OkObjectResult(new { message = responseMessage });
}
}
}

 

Die Funktion gibt nun ein JSON-Objekt (application/json), nicht mehr plain/text.

Wir können wie in dem oben erwähnten Artikel beschrieben das Projekt nun erneut veröffentlichen und das vorhandene Deployment einfach überschreiben.

Als nächstes navigieren wir in Azure über die Funktions-App-Bibliothek zu der Verwaltungsoberfläche unserer Funktion.

 

 

Nun können wir über den Reiter Plattformfeatures unter dem Punkt API auf API-Management klicken um im Anschluss über neu erstellen eine sogenannte API-Management Instanz zu erstellen. 

 

 

Bei API Management handelt es sich um einen Verwaltungsdienst mit dem wir Gateways für verknüpfte Funktionsapps erstellen und verwalten können.

Das Erstellen der API-Management Instanz kann einige Minuten dauern.

 

Ist die Ressource erstellt, klicken wir auf API verknüpfen und wählen die Funktion aus.

 

Im nächsten Schritt übernehmen wir die Standard-Einstellungen und klicken auf Create um eine API in unserem API-Management zu erstellen.

 

Um die API zu schützen damit sie nicht für jede Person, die die URL kennt aufrufbar ist stellen wir sicher, dass eine subscription key erforderlich ist. Das können wir in den Settings der API einstellen. Diese Option ist jedoch ohnehin standardmäßig aktiviert.  

Um einen solchen API-Key zu generieren benötigen wir ein sogenanntes Abonnement für die API. Dafür gibt es in der API-Managementoberfläche den entsprechenden Reiter. Wir achten darauf, es der richtigen API zuzuordnen.  

 

Mit Klick auf speichern haben wir dieses Abonnement erstellt. Dort können wir uns nun den API-Key über das Interaktionsmenü anzeigen lassen und kopieren. Wir benötigen diesen, wenn wir die Aktion in der Nintex Workflowcloud benutzen. 

 

Open API-Spezifikation erstellen

Folgenden Datei-Inhalt können wir kopieren, in einen Editor (z.B. VS Code) einfügen und als JSON-Datei abspeichern.

Wichtig: Der Host muss entsprechend de API-Management-Instanz angepasst werden.

Hier werden die Ein- & und Ausgabefelder für die Workflow-Aktion, sowie die Sicherheitseinstellungen definiert.

{
"swagger": "2.0",
"info": {
"title": "MyFirstAzureFunctionDaw",
"version": "1.0",
"description": "Import from "MyFirstAzureFunctionDaw" Function App"
},
"host": "myfirstazurefunctiondaw-apim.azure-api.net",
"basePath": "/MyFirstAzureFunctionDaw",
"schemes": [
"https"
],
"securityDefinitions": {
"apiKeyHeader": {
"type": "apiKey",
"name": "Ocp-Apim-Subscription-Key",
"in": "header"
}
},
"security": [
{
"apiKeyHeader": []
}
],
"paths": {
"/HelloWorldFunction": {
"post": {
"summary": "HelloWorldFunction",
"description": "Hallo",
"operationId": "post-helloworldfunction",
"parameters": [
{
"name": "name",
"description": "Name",
"in": "query",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"message": {
"type":"string"
}
}
}
}
}
}
}
},
"tags": []
}

Erstellen der Nintex Xtension

Da wir jetzt eine für Nintex Workflowcloud brauchbare OpenAPI-Spezifikation (Swagger) haben, wechseln wir zu unserem Nintex-Workflowcloud Dashboard und loggen uns dort ein. Hier gibt es einen Reiter Xtensions. Wenn wir auf diesen klicken sehen wir auf der rechten Seite ein +. Hier können wir unsere OpenAPI-Spezifikation hochladen um die Xtension zu erstellen.

Im nächsten Fenster müssen wir die Sicherheitseinstellungen bestätigen. Nintex Workflowcloud erkennt, die in der Swagger definierten Einstellungen. Wir wählen hier header aus und klicken auf Next. In dem folgenden Fenster können wir Namen und Beschreibung verändern und müssen ein Icon für unsere Xtension hochladen.

Jetzt haben wir unsere eigene Azure Funktion als Workflowaktion in unserer Workflowcloud.

Fazit

Wie wir sehen ist Nintex sehr leicht erweiterbar. Wir benötigen nur eine REST-Schnittstelle und können so beliebige Services nutzen. Seien es vorhandene externe Dienste oder wie in diesem Fall unsere eigenen. Natürlich ist dies ein sehr einfaches Beispiel, was nur zu Demonstrationszwecken und keinem wirklichen Nutzen dient, es gibt aber selbstverständlich auch anspruchsvolle Anwendungsfälle mit mehreren, komplexen Ein- und Ausgabetypen und sehr nützlichen Funktionen zur Prozessautomatisierung. Mit solchen Xtensions werden wir uns im Laufe dieser Serie beschäftigen.