Use cases

Systemnachrichten in Channels senden (Webhooks/Groovy-Prozessaktion)

In Intrexx auf Teams-Nachrichten reagieren

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.git

oder 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 3978

Schritt 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) 

1. 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.

2. Anmeldung mit statischem Benutzer aus Konfiguration (Password Flow)

   Bei diesem Anmeldungstyp wird ein Microsoft 365-Benutzer aus der Konfiguration verwendet.

3. 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.availability

Weitere 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

Microsoft 365 Kollaboration

Prozessaktion - Team/Kanal erstellen

Prozessaktion - Teams-Nachrichten-Aktion

Prozessaktion - Teams-Besprechung erstellen

Prozessaktion - MS365 Gruppe erstellen