#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

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

 

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

#HowTo: Mit K2 und PubNub in der Echtzeit


Nicht selten bin ich damit beschäftigt, K2 Interessenten zu erklären worum es sich bei einer LowCode App Plattform wie K2 eigentlich handelt. Gerade bei “echten” Entwicklern entsteht schnell der Eindruck dass man beim Arbeiten mit derartigen Plattformen irgendwann nicht mehr gebraucht wird oder alle Flexibilität eingebüsst werden muss, was wohl zu der Befürchtung führt, dass man als Entwickler nicht mehr mit den allerneuesten Frameworks und Services “spielen” darf.
Auf den ersten Blick ist diese Reaktion nachvollziehbar und natürlich, und ja, natürlich muss man sich an diverse Gegebenheiten anpassen – aber bedeutet das wirklich, dass man als Entwickler in der K2 Welt gefangen wäre? Setzt man diese (frühe) Wahrnehmung vor den Spiegel der Realität, lässt sich deutlich erkennen, dass K2 Kunden oftmals Anforderungen umsetzen, die ziemlich weit entfernt vom Standardverhalten einzuordnen sind. D.h. Kunden profitieren permanent von Standardfunktionen die mit der Plattform kommen (HTML5 UI Technologie, Mobile-Readiness, Workflowengine, Datenintegration, invididuelle Dashboards etc.), können aber aufgrund von APIs oder durch Komponenten wie den REST Broker auch Funktionen bzw. externe Services nutzen, ohne überhaupt die K2 Infrastruktur dafür anfassen zu müssen (Stichwort: Cloudkompatibilität).
Ein nettes Beispiel hierfür ist ein Cloudservice wie PubNub!

Was ist PubNub?

APIs for developers building secure realtime Mobile, Web, and IoT Apps.The PubNub Data Stream Network powers low-latency secure messaging at massive

Wie kann man mit K2 Nachrichten an einen PubNub Channel senden?
Ganz einfach und ohne Service-Side Code. PubNub bietet wie fast alle modernen Plattformen eine REST API, welche mit dem K2 REST Broker genutzt werden kann.
Für eine genaue Beschreibung bitte diese Doku lesen
https://www.pubnub.com/docs/pubnub-rest-api-documentation#publish-subscribe-publish-v1-via-post-post

Die URI sieht generisch wie folgt aus:
“https://pubsub.pubnub.com/publish/{pub}/{sub}/0/{channel}/0”

Was fehlt ist die einmalige Erstellung einer sog. SWAGGER Beschreibung für die Verbindung zu K2. Praktischerweise übersetzt der K2 REST Broker alle erwarteten Werte als Inputparameter für SmartObject-Methoden. Das Ergebnis ist ein wiederverwendbares, typisiertes Objekt im Repository, das man nun direkt von der UI aus oder in Workflows via Drag&Drop nutzen kann.

Eine mögliche Ausprägung der Swagger (JSON) Datei könnte so aussehen:

https://1drv.ms/u/s!Alwsd9IjhMleiqYt8I5fyRE_UV-xHw

(Hinweis: Natürlich wäre es auch möglich den Aufruf ohne den REST Broker via JS direkt auf einem K2 Formular zu machen. Dann würde die Nachricht sogar komplett am K2 Server vorbei an PubNub publiziert – allerdings hätte man dann nicht den Vorteil eines generischen und wiederverwendbaren Objekts und die Funktion wäre auch nicht in WFs nutzbar!)

Das SmartObject kann dann wie gehabt, in den K2 Designern typisiert genutzt werden.

K2 Smartforms Regeldefinition, nach einem Mausklick auf einen Button soll eine PubNub

Regelkonfiguration

Das funktioniert natürlich genau so in den K2 Workflow Designern, wo man nun on-demand an jeder passenden Stelle eine Nachricht an PubNub übermitteln kann:

SmartObject Event Methodenauswahl

In einer echten App kann das ganze dann so aussehen. Im rechten Fenster hinterlässt der Benutzer Bob eine Nachricht, die dann im Dashboard eines anderen Benutzers dargestellt wird:

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

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

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

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 🙂

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