#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

 

#HowTo: Generische Swagger Datei für K2 REST Broker

In einem anderen Beitrag habe ich ausführlich erklärt, wie einfach man mit dem K2 REST Broker via IFTTT und den Maker Service praktisch jeden Dienst mit K2 ansteuern kann: LinkedIn, Facebook, Twitter, Philips Hue etc.

Grundvoraussetzung hierfür ist eine Swagger Datei, die den Service beschreibt und von dem K2 Broker genutzt wird um korrespondierende SmartObjects zu erstellen. In diesem Artikel geht es darum, wie diese Datei auszusehen hat und wie man sie letztlich den K2 Broker damit konfigurieren muss!

Zu erwähnen sei hier noch, dass ich diese Datei nun bewusst generisch aufgebaut habe, damit ich jedes Maker Ereignis auslösen kann. Natürlich könnte man auch eine Datei mit konkreten Werten aufbauen oder mit mehreren Dateien arbeiten! Der Inhalt meiner generischen Ausprägung ist am Ende des Artikels zu sehen.

Hat man die Datei erstellt muss man den REST Broker konfigurieren. Dies geht am einfachsten über die Management Site.

Wichtig ist hierbei der Speicherort der Datei. Der kann auf dem Server oder auf einer Onlineresource sein, siehe Descriptor Location.

Aber diesem Punkt ist man quasi wieder “back in business” und kann wie gehabt mit den SmartObjects arbeiten und sie direkt in der Oberfläche oder in Worklows nutzen.  Ein kurzer Test in der Management Site schadet allerdings nicht, denn vielleicht hat man ja die Swagger Datei nicht ordentlich aufgebaut.

Diese Parametrisierung entspricht allerdings exakt der Beschreibung und somit können wir wieder zurück zum eigentlichen Beitrag 🙂

Der Inhalt der generischen Swagger (.JSON) Datei ist wie folgt zu gestalten:

{
 "swagger": "2.0",
 "info": {
 "version": "1.0.0",
 "title": "IFTTTMaker",
 "description": "IFTTT Maker Test with K2 REST BROKER"
 },
 "schemes": [
 "https"
 ],
 "host": "maker.ifttt.com",
 "basePath": "/trigger",
 "paths": {
 "/{event}/with/key/{key}": {
 "post": {
 "responses": {
 "200": {
 "description": "IFTTT Response"
 }
 },
 "parameters": [
 {
 "name": "event",
 "in": "path",
 "description": "event name",
 "type": "string",
 "required": true
 },
 {
 "name": "key",
 "in": "path",
 "description": "maker key url part, keep this SECRET",
 "type": "string",
 "required": true
 },
 {
 "name": "value1",
 "in": "query",
 "description": "value1 parameter",
 "type": "string",
 "required": false
 },
 {
 "name": "value2",
 "in": "query",
 "description": "value2 parameter",
 "type": "string",
 "required": false
 },
 {
 "name": "value3",
 "in": "query",
 "description": "value3 parameter",
 "type": "string",
 "required": false
 }
 ]
 }
 } 
 }
}

K2 Everything! REST Broker mit IFTTT & Maker Service nutzen

Heutzutage kommt man in meinem Umfeld um bestimmte Themen ja nicht mehr herum – Mobile, LowCode, Cloud, IoT etc. Mit diesem Beitrag will ich kurz erklären, wie man heute bereits verschiedenste Schnittstellen als K2 SmartObject integrieren kann.

Dabei verwende ich bewusst keine alten “Klassiker” wie SharePoint, SQL oder CRM sondern habe mich für ein Beispiel entschieden, das momentan einem relativ starken Hype ausgesetzt ist und zudem representativ für IoT steht: IFTTT (If This Then That – www.ifttt.com).

Abstrahiert kann man IFTTT an dieser Stelle eigentlich gegen jeden beliebigen Dienst austauschen, der standardiesierte Schnittstellen im Internet bereitstellt – in diesem Fall via REST. Warum? REST ist der de facto Standard im Web und ermöglicht mir außerdem ohne Verwendung von Server-side Code zu integrieren. K2 setzt hierbei auf den Swagger Standard für die Dienstbeschreibung. Dementsprechend benötigt man für die Anbindung via REST Broker ein sog. Swagger-File. Diese Datei beschreibt die Servicestruktur, Objekte und Parameter für den Aufruf, diese Eigenschaften werden von dem Broker dann in K2 SmartObjects übersetzt. Aber was genau von IFTTT will ich eigentlich nutzen?

Auf IFTTT gibt es den Maker Service. Diesen Service kann man als generisches Event Hub betrachten, das von jedem Gerät oder von jeder App genutzt werden kann – vorausgesetzt es ist möglich Web Requests zu tätigen. Per Web Request kann man dann ein IFTTT Event auslösen (IF THIS) und danach praktisch jede beliebige Funktion ausführen (THEN THAT), z.B. Device Notifications senden, Dateien erstellen, Twittern, Facebook aktualisieren oder auch andere “smarte” Geräte steuern, wie z.B. Hue Lampen.

Ein Trigger für den Maker Service ist denkbar einfach aufgebaut:

  • Eventname (z.B. “Licht an”, “Twittern” etc.)
  • 3 Optionale Parameter die man in den IFTTT Rezepten dann nutzen kann

Wie man die Swagger Datei aufbauen und integrieren kann, beschreibe ich hier #HowTo: Generische Swagger Datei für K2 REST Broker

Da man mit K2 Smartforms jedes SmartObject direkt ansprechen kann, habe ich mir kurz ein kleines Dashboard erstellt:

Wie man sieht, habe ich für LinkedIn, Facebook, Twitter, Hue und den Device Notification Service ein paar Views erstellt. Diese sind alle mit einem Button zum Auslösen des IFTTT Events ausgestattet und identisch konfiguriert:

Der Parameter “event” muss entsprechend der IFTTT / Maker Konfiguration gesetzt werden. Den Key habe ich in eine Servervariable ausgelagert – falls er sich ändert, muss ich somit nur die Variable anpassen. Der Rest funktioniert automatisch!

Beispiel LinkedIn:

 

 

 

Beispiel Facebook:

Beispiel Twitter:

Das besonders praktische an der generischen Swagger Datei ist, dass ich nun IFTTT Dienste hinzufügen und integrieren kann, ohne auch nur irgendetwas an der K2 Seite konfigurieren oder ergänzen zu müssen! Ich muss nur auf IFTTT ein Maker Applet erstellen und den Namen des “event” plus 3 optionale Variablen übergeben!