#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

 

Buffer this pageShare on LinkedInShare on FacebookTweet about this on TwitterEmail this to someone