#HowTo: Swagger Datei für Microsoft Teams Webhook erstellen und in K2 Apps verwenden

Pünktlich (ok, fast!) zum Release von Microsoft Teams liefere ich noch das HowTo zum Thema Webhook Integration nach.

In dem letzten Live Beispiel (Vendor Contract Management) bin ich bereits auf eine mögliche MS Teams Integration in einem “echten” Geschäftsprozess eingegangen. Heute erkläre ich kurz wie die MS Teams Anbindung technisch mit K2 funktioneren kann (es gibt durchaus mehrere Optionen) – und zwar anhand von Webhooks.

Was ist ein Webhook?
Ein Webhook ist ein Service Endpoint, der typischerweise JSON Payload interpretiert und nach dem Aufruf die Inhalte des Payloads verarbeitet. Alle möglichen Plattformen im Netz nutzen mittlerweile dieses Prinzip um eine wirklich sehr einfache Anbindung von externen Systemen zu ermöglichen. So lässt sich das im Folgenden beschriebene Prinzip praktisch 1:1 auf andere Systeme oder gar Plattformen übertragen: IFTTT (Maker Applet), Zapier (Webhooks), Microsoft Flow (Request Trigger) . Glücklicherweise kommt auch MS Teams mit dieser Art von Connector! Siehe hier.

MS Teams Webhook konfigurieren
Webhooks sind Connectoren auf Channelebene. D.h. man kann Webhooks über das Channel-Kontextmenü erstellen und konfigurieren.

Im folgenden Screen einfach auf “Add” klicken und man befindet sich auch schon in Konfiguration

Nachdem man dem Webhook einen Namen und ggf. ein Icon verpasst hat, erhält man auch schon die URL für den Aufruf. Diese URL ist ziemlich einfach zu analysieren – was die Erstellung einer Swagger Datei mit dynamischen Pfad (d.h. eine Datei für mehrere Channels) erleichtert.

https://outlook.office.com/webhook/{1}@{2}/IncomingWebhook/{Key}/{3}

Die URL Parts 1, 2 und 3 sind immer identisch, lediglich der Key weicht für jeden Webhook ab. Hierfür erstelle ich mit einer passenden Swagger Definition ein dynamisches SmartObject, welches dann pro Aufruf den Key als Input-Parameter erwartet. Somit erhalte ich ein typisiertes Object, welches ich direkt in Formularen oder Workflows verwenden kann, ohne mich um nervige String.Replace-Angelegenheiten kümmern zu müssen! Anhand des Keys wird dann definiert, in welchen Channel die Anwendung schreiben soll. Natürlich wäre es auch möglich für jeden Channel eine passende (fixe) Swagger Definition zu erstellen, das ist allerdings redundant und nicht erforderlich. Daraus ergibt sich der erste Teil der Swagger Definition:

{
“swagger”: “2.0”,
“info”: {
“version”: “1.0.0”,
“title”: “MS Teams”,
“description”: “MS Teams with K2 REST BROKER”
},
“schemes”: [
“https”
],
“host”: “outlook.office.com”,
“basePath”: “/webhook”,
“paths”: {
/<1>@<2>/IncomingWebhook/{key}/<3>“: {

Wie formatiert man MS Teams Nachrichten?
Nachrichten in MS Teams können sehr unterschiedlich gestaltet werden. Alle Optionen für die Formatierung sind hier beschrieben:
https://dev.outlook.com/Connectors/GetStarted

Microsoft nennt diese Nachrichten “Connector Cards”, diese können von sehr einfach (nur eine Nachricht) bis sehr komplex (Titel, Untertitel, Nachricht, Bild, Hyperlinks, wiederholte Bereiche etc.) gestaltet werden. Das Layout wird durch über den JSON Payload bestimmt.

Das Schema ist in der Doku beschrieben, ein paar Beispiele außerhalb der K2 Welt:

Einfach (nur Text):

curl -H "Content-Type: application/json" -d "{\"text\": \"Hello World!\"}" <YOUR WEBHOOK URL>

Komplex (mit Formattierungen und Abschnitten):

curl -H "Content-Type: application/json" -d "{\"title\": \"Learn about Office 365 Connectors\", \"text\": \"Visit the [Outlook Dev Portal](https://dev.outlook.com) to learn more about Office 365 Connectors!\", \"themeColor\": \"EA4300\"}" <YOUR WEBHOOK URL>

Woher weiß K2 wie das Schema auszusehen hat?

Als K2 Designer muss man sich nicht um diese Problematik kümmern. Übersetzt man das Schema einmalig in die passende Swagger Datei, sieht das so aus:

"paths": {
 "/<1>@<2>/IncomingWebhook/{key}/<3>": {
 "post": {
 "responses": {
 "200": {
 "description": "Response"
 }
 },
 "parameters": [
 {
 "name": "key",
 "in": "path",
 "description": "MS Teams url part for channel, keep this SECRET",
 "type": "string",
 "required": true
 },
 {
 "name": "Message",
 "in": "body",
 "description": "The message you want to post",
 "schema": {
 "$ref": "#/definitions/TeamMessage"
 },
 "required": true
...
...
 },
 "definitions": { 
 "TeamMessage": {
 "type": "object",
 "properties": {
 "title": {
 "type": "string",
 "required" : true
 },
 "text": {
 "type": "string",
 "required" : true
 },
 "sections": {
 "type": "array",
 "items": {
 "$ref": "#/definitions/Section",
 "required" : false
...
 },
 "Section": {
 "type": "object",
 "properties": {
 "activityTitle": {
 "type": "string"
 },
 "activitySubtitle": {
 "type": "string"
 },
 "activityText": {
 "type": "string"
 },
 "activityImage": {
 "type": "string"
...

Die komplette Swagger Definition findet man hier.

Durch die Konfiguration mit dem REST Broker arbeitet man letztlich mit typisierten SmartObjects – gleichermaßen direkt mit Formularen oder in K2 Workflows!

Test in der K2 Management Site

K2 Smartform

 

Ergebnis

 

Live Beispiel: K2 Contract Management mit Microsoft Teams Integration

Beim SharePoint Saturday in München haben wir eine umfassende K2 Demo zum Thema Vendor Contract Management gezeigt und dazu sehr gutes Feedback erhalten. Daher habe ich mich entschieden die Demo hier noch in einem Beitrag vorzustellen. Die Session hatte den Titel “Real-Life SharePoint: Vendor Contract Management” – der Hintergrund für die Erwähnung “real-life” war die Tatsache, dass in der Demo zahlreiche Anforderungen adressiert werden, die wir im Alltag von unseren Kunden hören:

  • die Vendor Daten liegen bereits in SAP und sollen in der Anwendung verwendet werden, ohne dass eine zusätzliche DB aufgebaut werden muss
  • Vertragsdokumente sollen im SharePoint abgelegt und dynamisch mit Inhalt gefüllt und letztlich als PDF konvertiert werden
  • neue Vertragsdokumente müssen einen mehrstufigen Freigabeworkflow durchlaufen, welcher mit mehreren Geschäftsregeln bestückt ist
    • die Rechtsabteilung soll nur bei Bedarf involviert werden
    • der CFO muss in den Prüfprozess involviert werden, wenn das Vertragsvolumen 500K übersteigt
  • geprüfte und genehmigte Veträge sollen mit DocuSign digital signiert und im SharePoint aktualisiert werden (Signatur erforderlich von internem Verantwortlichem und externem Vertreter des Lieferanten)
  • der Kunde hat sich strategisch für Microsoft Teams als Group-Chat Lösung entschieden – das Vertragsmanagement soll die Fortschritte der Vertragserstellung regelmäßig im Kanal “VendorNews” automatisch dokumentieren
  • die Lösung muss KPIs und Reports für maximale Sichtbarkeit und Transparenz bieten

Zunächst erfassen wir die Vertragsdaten und wählen u.a. auch den Lieferanten via Lookup gegen SAP aus. In diesem Beispiel wähle ich den Lieferanten “Vision Service Plan”.

Alle Daten auf einen Blick. Die Anwendung erfasst verschiedene Eigenschaften  – manche haben einen Einfluss auf den Prüfprozess (siehe oben) und involvieren dynamisch Verantwortliche oder führen zu Erinnerungsfunktionen wenn ein Vertrag ausläuft.

Nach dem Absenden werden die Daten gespeichert und ein Workflow übernimmt im Hintergrund das Routing des Vertrags.

1) Erfolgreich gespeichert und Referenznr. CTR00028 erhalten

2) Microsoft Teams automatisch aktualisiert

3) Anhand des Viewflow Controls kann man den Prozessfortschritt “live” verfolgen

Die Anwendungslogik sieht nun eine Freigabe des Abteilungsleiters vor.

Auf dem oberen Teil des Prüfformulars hat der Prüfer Einblick auf alle Vertragsdaten und zusätzliche visuelle Indikatoren. Es ist auch möglich andere K2 Apps zu referenzieren – in diesem Beispiel hinterlässt der Prüfer einen Kommentar via die App “Log Conversation”

Danach gibt er den Vertrag frei. Da der Vertrag keine Relevanz für die Rechtsabteilung hat und auch unter 500K liegt, wird sofort der Teilprozess für die Digitale Signatur gestartet.

Als erstes muss der interne Verantwortliche den Vertrag digital signieren. Über das K2 Aufgabenformular hat er Zugriff auf den Vertrag, der zwischenzeitlich als PDF Datei vorliegt und mit den korrespondieren Vertragsdaten gefüllt wurde!

Mit einen Klick kann die persönliche Sigantur gespeichert und die Aufgabe abgeschlossen werden.

Da die Anwendung automatisch den Microsoft Teams Channel befüllt, kann man dort direkt den Fortschritt nachverfolgen. Wie man sieht, wurde auch der Kommentar vom vorherigen Schritt in den Channel übertragen.

Nachdem dann der Verantwortliche des Lieferanten ebenfalls die Digitale Signatur gesetzt hat, ist der Prozess generell abgeschlossen und das Dokument wird als PDF doppelt-signiert im SharePoint abgespeichert.

Fertiger Vertrag:

Und ein letzter Blick in die Microsoft Teams App 🙂