#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

 

Forrester Wave: K2 erneut Strong Performer unter den Mobile Low-Code Development Platforms, Q1 2017

Forrester hat einen neuen Report veröffentlicht und K2 erneut als Strong Performer in der Kategorie Mobile Low-Code Development Platforms anerkannt. Besonderes Gewicht hatten bei der Analyse die Punkte Integration und Handling von Datenquellen (K2 SmartObject Technologie) und die ausgereifte Workflowengine.

Folgende Lösungen sind Bestandteil dieser Forrester Wave:
Alpha Software, Appian, Capriza, i-exceed, K2, Kony, Magic Software, Mendix, Oracle, OutSystems und Salesforce

Den kompletten Report kann man mit einer Forrester Subscription hier downloaden
https://www.forrester.com/report/The+Forrester+Wave+Mobile+LowCode+Development+Platforms+Q1+2017/-/E-RES136055

Weiterführende Resources gibt es auch auf dem offiziellen K2 Blog
https://www.k2.com/resources/blog

 

K2 @ CeBIT 2017 – Halle 3, Stand H36

Auch in diesem Jahr ist unser Team wieder auf der CeBIT vertreten. Alle Kunden, Partner und Interessenten sind herzlich eingeladen, uns am Stand zu besuchen.

Es gibt neben der Möglichkeit jederzeit live am Stand eine K2 Demo mitzunehmen, auch den täglichen Vortrag in der BPM Area.

Jeden Tag um 12 Uhr:

LowCode Plattformen und BPM – Agile Umsetzung von Prozessen

K2 findet man in Halle 3 am Stand H36 in der sog. BPM Area.

Hallenplan 

Direktlink
http://ssp.deepmap.de/respmap/#/map/cebit17/de/exhibitor/T541709

Review: K2 Europe Customer Day 2016, Frankfurt

customerday2016

Wie schon im Jahr 2015 hatte das K2 Northern Europe Team wieder zum Kundentag nach Frankfurt geladen. Rund 50 Kundenvertreter aus Deutschland, der Schweiz, Österreich, der Ukraine und Skandinavien kamen am 5.Oktober im Hilton Hotel in Frankfurt zusammen, um sich im persönlichen Gespräch auszutauschen und natürlich auf den neuesten Stand rund um K2 zu bringen!

Neben zahlreichen Updates zu 4.7, Mobile und der neuen K2 Cloud Platform, gab es Referenzvorträge von Partnern und Kunden und eine Best Practice Session. Abgerundet wurde der Tag dann mit einer Ask The Experts Diskussionsrunde, bei der das K2NE Team von Andrew Murphy (Director Technical Sales EMEA) des K2 UK Teams unterstützt wurde.

Zum Abschluss gab es dann noch ein besonderes Gimmick. Die Gruppe von Drum Café Deutschland hat den Teilnehmern noch rhythmisch eingeheizt 😉 Wer die Gruppe nicht kennt, sollte sich dieses Video ansehen.

small_k2ne_customer_day_2016

 

LIVE-WEBINAR: WARUM GESCHÄFTSANWENDUNGEN FÜR EIN BESSERES BPM SORGEN

Wie machen wir eigentlich die Umsetzung nachdem die Prozesse modelliert sind? Wem diese Frage bekannt vorkommt, kann ich das anstehende K2 Webinar am 5.November empfehlen.

Die Anmeldung ist wie immer kostenlos und unter diesem Link möglich:

Nehmen Sie an diesem Webinar teil

Business Process Management (BPM)-Suiten können Mehrwert für Ihr Unternehmen bieten, stellen aber oft monolithische Systeme dar, für deren Implementierung und Nutzung ein hohes Maß an Know-how und Schulung erforderlich ist, was sich bereits im Vorfeld störend auf den Geschäftsbetrieb auswirken kann. In der heutigen Geschäftswelt benötigen Unternehmen agile Plattformen, die schneller am Markt sind und einen größeren Mehrwert bieten.

Besuchen Sie dieses Webinar, in dem wir zeigen, wie wichtig schnelle Anwendungsentwicklungsplattformen sind und wie diese Plattformen sowohl von IT-Benutzern als auch von Geschäftskunden genutzt werden können.

Folgende Themen werden behandelt:
•    Aktuelle Änderungen im BPM-Umfeld
•    Umstellung von automatisierten Workflows auf dynamische Geschäftsprozess Anwendungen und
•    Wie Sie Ihren ROI und Ihre Geschäftsergebnisse verbessern können

Ihre BPM-Anforderungen können stark variieren und Verschiedenes umfassen – von Top-down-Initiativen zur Geschäftstransformation bis hin zu intelligenten Prozessanwendungen, die Informationen aus verteilten Systemen wie Line-of-Business-Systemen, ERP-Systemen (für die unternehmensweite Ressourcenplanung) und sozialen Medien integrieren. Nehmen Sie an diesem Webinar teil und sehen Sie selbst, wie Suiten mit Geschäftsprozess-Anwendungen flexible Lösungen bereitstellen können, die Ihre gesamte Palette von BPM-Anforderungen unterstützen.
Melden Sie sich hier an und erfahren Sie, wie Sie „Best Practice”-Ansätze für ein besseres BPM bei jedem Schritt des BPM-Lebenszyklus einführen können.