Use cases
Systemnachrichten in Channels senden (Webhooks/Groovy-Prozessaktion)
Beispiel
Aus einer Intrexx-Applikation soll bei Neuanlage eines Datensatzes in einer Datengruppe (hier die Datengruppe "Support-Tickets") automatisch eine Nachricht in einem Microsoft Teams Channel erstellt werden. Die Informationen aus dem Datensatz sollen in der Nachricht mit einer Schaltfläche, die den Datensatz direkt in Intrexx öffnet, als Card gerendert werden.
Voraussetzungen
Das Intrexx-Portal muss für eingehende Webhooks aus dem Internet erreichbar sein.
Verwendete Technologien
-
Intrexx-Applikation und -Prozess mit Groovy-Aktion
-
Inbound-Webhook für Microsoft Teams
Vorgehensweise
Schritt 1
In Microsoft Teams wird ein Channel für Intrexx-Support-Tickets erstellt und in diesem gemäß der Anleitung unter "Teams Inbound Webhook erstellen" ein neuer Inbound-Webhook registriert. Die dabei erzeugte Webhook-URL wird notiert.
Schritt 2
Importieren Sie die Beispielapplikation und -prozesse. Die ZIP-Datei für den Import können Sie hier herunterladen.
Schritt 3
Im Beispielprozess "MS365 Teams" finden Sie eine Groovy-Aktion mit dem folgenden Skript:
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.*;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.*;
def id = g_record["96BA727080433D309562AE579A8AD507B8CDB8A2"].value
def title = g_record["1C07C0BA592B734D2BB2050F9A60C2D2132FDDE5"].value
def descr = g_record["364EB5C7725271398BA44FCBD74C1EF115F81A20"].value
def payload = """
{
"@type": "MessageCard",
"@context": "http://schema.org/extensions",
"themeColor": "0076D7",
"summary": "Larry Bryant created a new support ticket",
"sections": [{
"activityTitle": "${title}",
"activitySubtitle": "${descr}",
"activityImage": "https://teamsnodesample.azurewebsites.net/static/img/image5.png",
"facts": [{
"name": "Assigned to",
"value": "Unassigned"
}, {
"name": "Status",
"value": "Not started"
}],
"markdown": true
}],
"potentialAction": [{
"@type": "ActionCard",
"name": "Add a comment",
"inputs": [{
"@type": "TextInput",
"id": "comment",
"isMultiline": false,
"title": "Add a comment here for this task"
}],
"actions": [{
"@type": "HttpPOST",
"name": "Add comment",
"target": "https://docs.microsoft.com/outlook/actionable-messages"
}]
}, {
"@type": "OpenUri",
"name": "Open in Intrexx",
"targets": [{
"os": "default",
"uri": "https://localhost:1337/path/app/?rq_AppGuid=5F0E4968468F8C4C36515228523D26B6CA16202F&rq_TargetPageGuid=6C02ABACBED2AFA937C1A6D97C2FA12937017C01&qs_link=946E2A263B44AB6052F8556F08B2EF64F49F7464&qs_STRID=${id}"
}]
}, {
"@type": "ActionCard",
"name": "Change status",
"inputs": [{
"@type": "MultichoiceInput",
"id": "list",
"title": "Select a status",
"isMultiSelect": "false",
"choices": [{
"display": "In Progress",
"value": "1"
}, {
"display": "Active",
"value": "2"
}, {
"display": "Closed",
"value": "3"
}]
}],
"actions": [{
"@type": "HttpPOST",
"name": "Assign to me",
"target": "https://a75dafc0b855.ngrok.io/?qs_path=groovy/de/uplanet/lucy/sample/teams-change-ticket-status.groovy&id=${id}",
"body": "{\\"status\\":\\"{{list.value}}\\", \\"ticketID\\":\\"${id}\\", \\"ticketTitle\\":\\"${title}\\", \\"ticketDescr\\":\\"${descr}\\"}",
"bodyContentType": "application/json"
}]
}]
}
"""
g_syslog.info(payload)
HttpClient client = HttpClient.newBuilder().build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("<Webhook-URL>"))
.POST(BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
g_syslog.info(response.statusCode());
g_syslog.info(response.body());
Ersetzen Sie hier "<Webhook-URL>" mit der Webhook-URL, die Sie in Schritt 1 dieser Anleitung kopiert haben. Speichern und aktivieren Sie den Prozess.
Schritt 4
Um auf eine Benutzeraktion auf eine Karte in Teams in Intrexx zu reagieren, wird ein HTTP-Endpunkt als Groovy-Skript benötigt. Dazu muss das folgende Skript im Portalverzeichnis "groovy/de/uplanet/lucy/sample/teams-change-ticket-status.groovy" gespeichert werden. Das Skript kann dann den Datensatz in Intrexx entsprechend aktualisieren.
import java.io.*
import de.uplanet.io.IOHelper
ByteArrayOutputStream bos = new ByteArrayOutputStream();
IOHelper.copyStream(bos, g_request.getInputStream())
def id = g_request["id"]
def body = new String(bos.toByteArray())
def json = g_json.parse(body)
//def reply = "Hello from Intrexx, ${json.from.name}"
def title = json["ticketTitle"]
def descr = json["ticketDescr"]
def user = ""
if (g_session != null)
user = g_session.user.name
else
user = "Supporter"
g_syslog.info("Ticket: " + id)
g_syslog.info(json)
def payload = """
{
"@type": "MessageCard",
"@context": "http://schema.org/extensions",
"themeColor": "0076D7",
"summary": "Larry Bryant created a new support ticket",
"sections": [{
"activityTitle": "${title}",
"activitySubtitle": "${descr}",
"activityImage": "https://teamsnodesample.azurewebsites.net/static/img/image5.png",
"facts": [{
"name": "Assigned to",
"value": "${user}"
}, {
"name": "Status",
"value": "Active"
}],
"markdown": true
}],
"potentialAction": [{
"@type": "OpenUri",
"name": "Open in Intrexx",
"targets": [{
"os": "default",
"uri": "https://localhost:1337/path/app/?rq_AppGuid=5F0E4968468F8C4C36515228523D26B6CA16202F&rq_TargetPageGuid=6C02ABACBED2AFA937C1A6D97C2FA12937017C01&qs_link=946E2A263B44AB6052F8556F08B2EF64F49F7464&qs_STRID=${id}"
}]
}]
}
"""
response.json()
response.setHeader("CARD-UPDATE-IN-BODY", "true")
write(payload)Schritt 5
Der Groovy-Endpunkt muss für Microsoft Teams öffentlich erreichbar sein, entweder direkt im Portal im Internet oder per Reverse Proxy.
Öffnen Sie dazu im Portal die Beispielapplikation und erstellen Sie einen neuen Datensatz. Dieser neue Datensatz löst die Prozessaktion aus, die die Nachricht im Channel per Webhook-Aufruf erzeugt.
Mit Klick auf "Change Status" kann über "Assign to me" ein neuer Status gewählt werden.
Bei Klick auf "Assign to me" wird die Karte an den Intrexx-Webhook gesendet, der wiederum mit einer neuen Card antwortet, so dass nun nur noch die Open-Aktion verfügbar ist.
Über die Schaltfläche "Open in Intrexx" in der Nachricht kann direkt der Intrexx-Datensatz im Browser aufgerufen werden.
Hier finden Sie weiterführende Informationen zum Thema:
In Intrexx auf Teams-Nachrichten reagieren
Channel Nachrichten (Webhooks)
Beispiel
Aus einem Teams-Channel soll mit "@mention" eine Anfrage an das Intrexx-Portal gesendet werden, z.B. um Daten aus einer Datengruppe ("meine Supporttickets") angezeigt zu bekommen. Die Informationen sollen in der Nachricht als Card gerendert werden. Zusätzlich soll eine Schaltfläche in der Nachricht das direkte Öffnen des Datensatzes in Intrexx ermöglichen.
Vorbedingungen
Das Intrexx-Portal muss für eingehende Webhooks aus dem Internet erreichbar sein.
Verwendete Technologien
-
Intrexx-Beispielapplikation und Groovy-HTTP-Endpunkt
-
Outbound-Webhook für Microsoft Teams
Vorgehensweise
Schritt 1
Erstellen Sie das folgende Groovy-Skript für den Intrexx-HTTP-Endpunkt unter org/portal/groovy/de/uplanet/lucy/sample/teams-get-tickets.groovy:
import java.io.*
import de.uplanet.io.IOHelper
import de.uplanet.tools.HMACVerifier
ByteArrayOutputStream bos = new ByteArrayOutputStream()
IOHelper.copyStream(bos, g_request.getInputStream())
def bytes = bos.toByteArray()
def req = g_request.getHttpServletRequest()
def authHeader = req.getHeader("Authorization")
g_syslog.info(authHeader)
if (authHeader == null || !authHeader.startsWith("HMAC")) {
g_syslog.error("Unauthorized request")
response.setStatus(401)
return
}
def key = "beuBhNzxssEKxljQ90tftG6Xc4Rf0gx/fjZR28V31aw="
def hmac = authHeader.substring(5)
g_syslog.info(hmac)
if (!HMACVerifier.verify(hmac, key, bytes)) {
g_syslog.error("Unauthorized request")
response.setStatus(401)
return
}
def body = new String(bytes)
def json = g_json.parse(body)
def reply = """
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "**Open tickets for ${json.from.name}**"
},
{
"type": "TextBlock",
"text": "[Ticket 1](https://localhost:1337/)"
},
{
"type": "TextBlock",
"text": "[Ticket 2](https://localhost:1337/)"
}
]
}
}
]
}
"""
g_syslog.info(reply)
response.json()
write(reply)Schritt 2
In Teams einen Channel für Intrexx-Support-Tickets erstellen und in diesem gemäß der Anleitung unter "Teams Outbound Webhook erstellen" einen neuen Outbound-Webhook registrieren. Dabei unter "Callback-URL" die URL zum Groovy-Skript-Endpunkt hinterlegen (z.B. https://my.intrexx.org/?qs_path=groovy/de/uplanet/lucy/sample/teams-get-ticktes.groovy). Notieren Sie außerdem die Passphrase für die Signierung der Requests.
Schritt 3
In Microsoft Teams können Sie den Bot nun wie folgt ansprechen: @Intrexx Show my tickets
Hier finden Sie weiterführende Informationen zum Thema:
In Chats/Groupchats/Channels mit Bots interagieren
Teams Messaging Extensions-Aktion für Intrexx Share Tasks
Beispiel
In Teams-Chats, -Groupchats oder -Channels soll über eine neue oder bestehende Nachricht eine Aufgabe in Intrexx Share erstellt werden. Dazu kommt eine Teams Messaging Extension-Aktion mit Bot zum Einsatz. Auf der Intrexx-Seite wird ein OData-Service für die Task-Datengruppe angeboten, der vom Bot aufgerufen wird, um Aufgaben anzulegen.
Teams Bot Deployment
Voraussetzungen
-
Microsoft Teams ist installiert und Sie besitzen ein Konto
-
.NET Core SDK version 3.1
-
ngrok oder gleichwertige Tunneling-Lösung
-
Visual Studio oder Visal Studio Code with C#/.Net extension
-
Intrexx 21.09 Portal mit Intrexx Share und dem Modul "Projekte" (dieses Beispiel basiert auf dem Intrexx-DemoPortal, es kann jedoch jedes andere Portal mit Intrexx Share und dem Modul "Projekte" verwendet werden)
Bot Web App vorbereiten und ausführen
Schritt 1
Clonen Sie das Repository mit
git clone https://github.com/UnitedPlanet/ms365-integration-samples.gitoder laden Sie es hier herunter: teams-messaging-extensions-action-for-ix-tasks.zip
Schritt 2
Wenn Sie Visual Studio verwenden:
-
Starten Sie Visual Studio
-
Wählen Sie das Menü "File / Open / Project/Solution"
-
Navigieren Sie zum Ordner "teams-messaging-extensions-action"
-
Wählen Sie hier die Datei "TeamsMessagingExtensionsAction.csproj" aus
Schritt 3
Führen Sie ngrok - point to port 3978 oder verwenden Sie einen Reverse Proxy to Tunnel External https-Requests zum Intrexx Portal Server
ngrok http -host-header=rewrite 3978Schritt 4
Erstellen Sie eine Bot Framework Registration Resource in Azure.
-
Verwenden Sie die aktuelle HTTPS-URL, die Sie bei der Ausführung von ngrok erhalten haben. Hängen Sie dabei den Pfad "/api/messages" an, der bei diesem Beispiel verwendet wird: https://xxxxx.ngrok.io/api/messages
-
Stellen Sie sicher, dass der Microsoft Teams-Channel aktiviert ist
-
Wenn Sie kein Azure-Konto besitzen können Sie diese Bot Framework-Registrierung verwenden.
Schritt 5
Führen Sie ein Update der appsettings.json-Konfiguration für den Bot für die Verwendung von Microsoft App-ID und App-Passwort aus der Bot Framework-Registration. Bitte beachten Sie dabei, dass das App-Password dem "Client Secret" im Azure-Portal entspricht und Sie jederzeit ein neues Client Secret erzeugen können. Stellen Sie außerdem den Intrexx-Benutzernamen und das -Password für die Authentifizierung mit dem Intrexx-OData-Service zur Verfügung.
Schritt 6
Dieser Schritt ist spezifisch für Microsoft Teams.
-
Setzen Sie in der Datei "manifest.json", die Sie im Ordner "teamsAppManifest" finden, die Microsoft-App-ID, die zuvor bei der Registrierung des Bots erzeugt wurde, überall da ein, wo Sie den Platzhalter-String "<<YOUR-MICROSOFT-APP-ID>>" finden. Abhängig vom Szenario kann die Microsoft-App-ID mehrfach in der Datei "manifest.json" vorkommen.
-
Packen Sie die Inhalte des teamsAppManifest-Ordners, um ein "manifest.zip" zu erzeugen.
-
Laden Sie das manifest.zip in Teams hoch. Klicken Sie dazu auf "Upload a custom app" in der App-Ansicht.
Schritt 7
Führen Sie Ihren Bot aus - entweder mit F5 von Visual Studio aus oder unter Verwendung von Dotnet run in einem geeigneten Ordner.
Projekte bearbeiten und Empfängerliste für die Task-Card
Die Aufgaben-Karte enthält zwei Wertelisten für Projekte und Empfänger. Die Werte können in der Datei "teams-messaging-extensions-action/Resources/taskCard.json" bearbeitet werden.
{
"type": "TextBlock",
"text": "Project",
"size": "default"
},
{
"type": "Input.ChoiceSet",
"id": "taskProject",
"style": "compact",
"isMultiSelect": false,
"value": "",
"choices": [
{
"title": "My Tasks",
"value": "FEF3C9FB5C9F6F45C25E7EFD6149BB39F44CF04C"
},
{
"title": "Trade fair at the conference center",
"value": "C2838ACA9DBCB25EF5447D0C847FC9BFD53DEE81"
},
{
"title": "The digital kitchen",
"value": "2C44139F68ECC98CBB604CD1866FAF866E2449A6"
}
]
},
{
"type": "TextBlock",
"text": "Assign to",
"size": "default"
},
{
"type": "Input.ChoiceSet",
"id": "taskResponsibleUserId",
"style": "compact",
"isMultiSelect": false,
"value": "",
"choices": [
{
"title": "Administrator",
"value": "1"
},
{
"title": "PeterM",
"value": "6"
},
{
"title": "TinaM",
"value": "16"
},
{
"title": "FrankN",
"value": "17"
}
]
}Die Projekt-Liste enthält den Projektnamen und die -GUID. Diese WErte können in der Datenbank-Tabelle "TSK_CATEGORIES" ermittelt werden. Die Empfängerlistenwerte sind Intrexx-Benutzernamen und ihre Benutzer-ID. Diese Werte können in der Sicht "VBLUSER" ermittelt werden.
Bot in Azure bereitstellen
Unter Bereitstellen Ihres Bots finden Sie eine komplette Liste mit Instruktionen zur Bereitstellung.
Intrexx OData-Service bereitstellen
Um den OData-Service in Ihrem Portal bereitzustellen entpacken Sie die folgende ZIP-Datei in das Portalverzeichnis "internal/cfg/odata/producer" und starten Sie den Portaldienst neu. Anschließend sollte die OData-Service-Konfiguration im Modul "Integration" im Portal Manager zur Verfügung stehen.
Download msteams-msg-extensions-share-task-odata.zip
Aufgabeerzeugung testen
Klicken Sie im Teams Channel auf "Neue Unterhaltung" und dann auf das App-Icon. Wählen Sie dann "Intrexx Aufgabe erzeugen" aus. Die Aufgaben-Karte wird angezeigt, wenn der Bot korrekt registriert und der Bot-Service für Microsoft Teams über den ngrok-Tunnel zur Verfügung steht.
Nachdem die Aufgabe abgegeben ist antwortet der Bot mit einer Zusammenfassung und einem Link zur Aufgabe in Intrexx.
Die Aufgabe kann sofort in Intrexx angesehen werden.
Verantwortliche Benutzer erhalten eine Benachrichtigung in Intrexx Share.
Die Aufgabe wird ebenfalls in Übersichten und der Aufgabentabelle angezeigt.
MS Graph SDK in Groovy-Prozessaktion verwenden
Authentifizierung
Für die Authentifizierung mit der MS Graph API steht in Groovy-Skripts die folgenden Klassen zur Verfügung.
import de.uplanet.lucy.server.odata.v4.consumer.http.MsGraphSdkAuthenticationProviderFactory
def clientId = "msgraphsdk" // Name of the MS Graph OAuth2 configuration
def authFactory = new MsGraphSdkAuthenticationProviderFactory()
def accessTokenProvider = authFactory.createForCurrentUser(clientId) // 1) Anmeldung mit aktuellem Portaluser (Authorization Code)
def accessTokenProvider = authFactory.createForImpersonatedUser(clientId, "<USER_GUID>") // 2) Anmeldung mit statischem Benutzer aus Konfiguration (Password)
def accessTokenProvider = authFactory.createForServiceUser(clientId, "<USER_GUID>") // 3) Anmeldung mit Service Account aus Konfiguration (Client Credentials) -
Anmeldung mit aktuellem Portalbenutzer (Authorization Code Flow)
Dieser Anmeldungstyp leitet den Portaluser im Browser zur Anmeldung an Microsoft 365 weiter und anschließend zurück nach Intrexx. Nur für interaktive Aktionen geeignet.
-
Anmeldung mit statischem Benutzer aus Konfiguration (Password Flow)
Bei diesem Anmeldungstyp wird ein Microsoft 365-Benutzer aus der Konfiguration verwendet.
-
Anmeldung mit Service Account aus Konfiguration (Client Credentials Flow)
Bei diesem Anmeldungstyp wird ein Microsoft 365-Dienstkonto aus der Konfiguration verwendet.
Graph SDK Beispiele
Senden einer E-Mail in Prozessen
Das folgende Beispiel zeigt, wie eine E-Mail aus Prozessen oder Seiten-Handlern versendet werden können.
import de.uplanet.lucy.server.odata.v4.consumer.http.MsGraphSdkAuthenticationProviderFactory
import java.util.ArrayList;
import okhttp3.Request;
import com.microsoft.graph.models.BodyType;
import com.microsoft.graph.models.ChatMessage;
import com.microsoft.graph.models.EmailAddress;
import com.microsoft.graph.models.Importance;
import com.microsoft.graph.models.ItemBody;
import com.microsoft.graph.models.Message;
import com.microsoft.graph.models.Recipient;
import com.microsoft.graph.requests.GraphServiceClient;
def clientId = "msgraphsdk" // Name of the MS Graph OAuth2 configuration
def authFactory = new MsGraphSdkAuthenticationProviderFactory()
def accessTokenProvider = authFactory.createForImpersonatedUser(clientId, "7312F993D0DA4CECCA9AE5A9D865BE142DE413EA") // 2) Anmeldung mit statischem Benutzer aus Konfiguration (Password)
def graphClient =
GraphServiceClient
.builder()
.authenticationProvider(accessTokenProvider)
.buildClient();
def message = new Message();
message.subject = "Hello";
message.importance = Importance.LOW;
def body = new ItemBody();
body.contentType = BodyType.HTML;
body.content = "Hi from <b>Intrexx</b>!";
message.body = body;
def toRecipientsList = new ArrayList<Recipient>();
def toRecipients = new Recipient();
def emailAddress = new EmailAddress();
emailAddress.address = "john.smith@intrexx365.com";
toRecipients.emailAddress = emailAddress;
toRecipientsList.add(toRecipients);
message.toRecipients = toRecipientsList;
def msgResponse = graphClient.me().messages()
.buildRequest()
.post(message);
def msgId = msgResponse.id;
graphClient.me().messages(msgId)
.send()
.buildRequest()
.post();Weitere Informationen zu diesem Thema finden Sie hier:
https://docs.microsoft.com/en-us/graph/api/user-post-messages
Präsenz des aktuellen Users anzeigen und ändern
Das folgende Beispiel zeigt, wie die Präsenzinformationen des aktuellen Portalbenutzers abgefragt und geändert werden können. Die Applikation dazu können Sie hier herunterladen: ms365presence.zip
Groovy Page Rendering Handler (Before) zur Anzeige der Präsenz auf einer Seite (via VTL):
import de.uplanet.lucy.server.odata.v4.consumer.http.MsGraphSdkAuthenticationProviderFactory
import com.microsoft.graph.requests.GraphServiceClient
def clientId = "teams" // Name of the MS Graph OAuth2 configuration
def authFactory = new MsGraphSdkAuthenticationProviderFactory()
def accessTokenProvider = authFactory.createForCurrentUser(clientId)
def graphClient = GraphServiceClient
.builder()
.authenticationProvider(accessTokenProvider)
.buildClient()
def presence = graphClient.me().presence()
.buildRequest()
.get()
g_log.info(presence.activity)
g_log.info(presence.availability)
g_sharedState["my_activity"] = presence.activity
g_sharedState["my_availability"] = presence.availabilityWeitere Informationen dazu finden Sie hier:
https://docs.microsoft.com/en-us/graph/api/presence-get?view=graph-rest-beta&tabs=java
Groovy Page Action Handler (Before) zum Ändern der Präsenz über eine Ansichtsseite:
import de.uplanet.lucy.server.odata.v4.consumer.http.MsGraphSdkAuthenticationProviderFactory
import com.microsoft.graph.requests.GraphServiceClient
import com.microsoft.graph.models.PresenceSetPresenceParameterSet;
import javax.xml.datatype.DatatypeConfigurationException;
import javax.xml.datatype.DatatypeFactory;
import javax.xml.datatype.Duration;
def clientId = "teams" // Name of the MS Graph OAuth2 configuration
def authFactory = new MsGraphSdkAuthenticationProviderFactory()
def accessTokenProvider = authFactory.createForServiceUser(clientId)
def graphClient = GraphServiceClient
.builder()
.authenticationProvider(accessTokenProvider)
.buildClient()
def upn = g_session.user?.emailBiz // the current user's upn
def appId = "89094413-170f-440b-a3e7-6f8e45257531" // the azure app id
def myId = graphClient.users(upn).buildRequest().get().id; // get the current user's Azure id
def availability = g_request["dropdowncontrolAA8B5A6C"] // get the status
if (availability == null)
availability = "Available"
def acitivity = availability == "Busy" ? "InACall" : availability; // get the activity
def expirationDuration = DatatypeFactory.newInstance().newDuration("PT5M"); // define expiration
def params = PresenceSetPresenceParameterSet.newBuilder() // build parameter set
.withActivity(acitivity)
.withSessionId(appId)
.withAvailability(availability)
.withExpirationDuration(expirationDuration)
.build();
graphClient.users(myId).presence().setPresence(params).buildRequest().post();
g_log.info("Set presence for user ${upn}");Weitere Informationen dazu finden Sie hier:
https://docs.microsoft.com/en-us/graph/api/presence-setpresence?view=graph-rest-beta&tabs=java
Weitere Informationen
Senden Sie uns eine E-Mail