Freigeben über

Workflowbot in Teams

  • Artikel

Ein Workflowbot ermöglicht Benutzern die Interaktion mit einer adaptiven Karte. Der Aktionshandler für adaptive Karten ermöglicht es der adaptiven Karte, sich in der Teams-App zu unterhalten. Sie können einen Workflowbot in mehreren Szenarien für Ihre Benutzer erstellen, um die Benutzererfahrung zu verbessern, z. B. Incident management, Ticketing, Genehmigungsworkflow und Projektverwaltungskarten. Sie können ein Arbeitselement mit einem Workflowbot erstellen und zuweisen und den Inhalt mit dem Azure DevOps- oder Jira-System synchronisieren.

Ein Workflowbot kann abhängig von verschiedenen Bereichen in einem Team, gruppenchat oder als persönliche App installiert werden. Die Standardbefehlslogik gibt eine adaptive Karte zurück. Sie können diese Logik an Ihre geschäftsspezifischen Anforderungen anpassen. Für die Anpassung müssen Sie Ihre vorhandenen APIs aufrufen.

Vorteile:

  • Automatisiert Geschäftsprozesse und sich wiederholende Workflows, ohne den Kontext von Unterhaltungen zu verlassen.

  • Unterstützt Benutzer mit sequenziellem Workflow über verschiedene Karten nach und nach, ohne zusätzliche Karten zu senden.

  • Stellt aktuelle benutzerspezifische Ansichten bereit.

  • Vereinfacht das Programmiermodell mit dem TeamsFx SDK.

    Hinweis

    Sie können die Funktion auswählen, die Sie installieren möchten, wenn Sie die App hinzufügen. Weitere Informationen finden Sie unter Konfigurieren von Standardinstallationsoptionen.

Sie können einen Workflowbot erstellen, um auf die adaptive Karte zu reagieren, die von Benutzern ausgelöst wird. Der Aktionshandler für adaptive Karten, der vom TeamsFx SDK unterstützt wird, kann die universelle Aktion Action.Execute adaptive Karte ausführen, die von Benutzern ausgelöst wird. Als Reaktion auf diese jeweilige Kartenaktion in der Unterhaltung sendet der Aktionshandler für adaptive Karten eine weitere adaptive Karte.

Screenshot: endgültige Ausgabe eines Workflowbots in Teams

Kartenaktionshandler

Um die Erstellung eines Workflowbots zu vereinfachen, stellt das TeamsFx SDK einen Adaptive Card-Aktionshandler bereit TeamsFxAdaptiveCardActionHandler. Sie können sich nur auf die Entwicklung eines Workflowbots konzentrieren, um auf die Kartenaktion zu reagieren, ohne das Bot Framework zu erlernen.

Das folgende Diagramm veranschaulicht, wie Sie mit dem TeamsFx SDK auf eine Aktion für adaptive Karten reagieren:

Diagramm: Workflow-Bot-Kartenaktionshandler

  1. Aktionskarte: Die Karte, auf der DoStuffSie Ihre Aktion definieren, die Benutzer aufrufen können, z. B. .
  2. Kartenaktionshandler: Wird ausgelöst, wenn Benutzer die entsprechende Kartenaktion aufrufen, ist es triggerVerb identisch mit der -Eigenschaft in der verb Aktion "Adaptive Karte". Es kann eine Antwortkarte senden, um auf die Aktion zu reagieren.
  3. Antwortkarte: Die Karte, die auf die Aktion reagiert, wenn der Benutzer sie von der Aktionskarte aus aufruft.

Zum Verarbeiten von Kartenaktionen mit dem TeamsFx SDK muss jeder Kartenaktionshandler die TeamsFxAdaptiveCardActionHandler Schnittstelle implementieren:


TeamsFxAdaptiveCardActionHandler 
{
    /**
     * The verb defined in adaptive card action that can trigger this handler.
     */
    triggerVerb: string;

    /**
     * Specify the behavior for how the card response will be sent in Teams conversation.
     * The default value is `AdaptiveCardResponse.ReplaceForInteractor`, which means the card
     * response will replace the current one only for the interactor.
     */
    adaptiveCardResponse?: AdaptiveCardResponse;
    
    /**
     * The handler function that will be invoked when the action is fired.
     * @param context The turn context.
     * @param actionData The contextual data that associated with the action.
     */
    handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse>;
}

Anpassen der Initialisierung

Sie können den Workflowbot mit Ihrem eigenen Adapter initialisieren oder nach der Initialisierung anpassen. Die Standardinitialisierung befindet sich in bot/src/internal/initialize.js(ts).

Sie können die Initialisierungslogik auf Folgendes aktualisieren:

  1. Legen Sie so fest options.adapter , dass Ihr eigenes BotFrameworkAdapterverwendet wird.
  2. Legen Sie fest options.command.commands , dass mehrere Befehlshandler eingeschlossen werden.
  3. Legen Sie diese Einstellung fest options.cardAction.actions , um mehrere Aktionshandler einzuschließen.
  4. Legen Sie fest options.{feature}.enabled , um mehrere ConversationBot Funktionen zu aktivieren.

Weitere Informationen zur Initialisierungsanpassung finden Sie unter Zusätzliche Initialisierungsanpassung.

Hinzufügen von Kartenaktionen

Führen Sie die folgenden Schritte aus, um Kartenaktionen mit JavaScript und TypeScript hinzuzufügen:


1. Hinzufügen einer Aktion zu Ihrer adaptiven Karte

Sie können einer adaptiven Karte eine neue Aktion (Schaltfläche) hinzufügen, indem Sie sie in der JSON-Datei definieren, z. B. eine neue DoSomething Aktion zur src/adaptiveCards/helloworldCommandResponse.json Datei hinzufügen.

Der folgende Code ist ein Beispiel für den Aktionstyp Action.Execute:

{ 
  "type": "AdaptiveCard", 
  "body": [
    ...
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "DoSomething",
          "verb": "doSomething" 
        }
      ]
    },
    ...
  ]
}

Wenn die Aktion in Teams aufgerufen wird, ist die Verb-Eigenschaft erforderlich, damit das TeamsFx Conversation SDK den entsprechenden Aktionshandler aufrufen kann.

Hinweis

Stellen Sie sicher, dass Sie eine globale eindeutige Zeichenfolge für die Verbeigenschaft bereitstellen, wenn Sie eine allgemeine Zeichenfolge verwenden, die zu einem Konflikt mit einem anderen Bot führen kann. Dadurch kann unerwartetes Verhalten vermieden werden.


2. Antworten Mit der neuen adaptiven Karte

Sie können eine neue adaptive Karte für jede Aktion zurückgeben, die aufgerufen wird, um die Antwort für den Endbenutzer anzuzeigen. Sie müssen eine neue Datei bot/src/adaptiveCards/doSomethingResponse.json als Antwort für die doSomething Aktion mit folgendem Inhalt erstellen:

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "A sample response to DoSomething."
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4"
}

Hinweis

Sie können Ihr Kartenlayout entsprechend Ihren geschäftlichen Bedarf gestalten. Weitere Informationen finden Sie unter Adaptiver Karten-Designer.


3. Hinzufügen des Aktionshandlers

Sie können eine neue Aktion verarbeiten, die von adaptiver Karte mit der Klasse TeamsFxAdaptiveCardActionHandlerdes TeamsFx SDK aufgerufen wird. Sie müssen die Aktion in diesem Schritt anpassen, z. B. das Aufrufen einer API, die Verarbeitung von Daten oder eine andere Aktion gemäß Ihren geschäftlichen Notwendigkeiten.

Sie können eine neue Datei bot/src/cardActions/doSomethingActionHandler.jserstellen:

    const { AdaptiveCards } = require("@microsoft/adaptivecards-tools");
    const { AdaptiveCardResponse, InvokeResponseFactory } = require("@microsoft/teamsfx");
    const responseCard = require("../adaptiveCards/doSomethingResponse.json");

    class DoSomethingActionHandler { 
    triggerVerb = "doStuff";

        async handleActionInvoked(context, message) { 
            const responseCardJson = AdaptiveCards.declare(responseCard).render(actionData);
            return InvokeResponseFactory.adaptiveCard(responseCardJson);
        }
    }

     module.exports = {

       DoSomethingActionHandler,
    }

Hinweis

  • triggerVerb ist die Verbeigenschaft Ihrer Aktion.
  • actionData sind die Daten, die der Aktion zugeordnet sind, einschließlich dynamischer Benutzereingaben oder einiger kontextbezogener Daten, die in der data-Eigenschaft Ihrer Aktion bereitgestellt werden.
  • Wenn eine adaptive Karte zurückgegeben wird, wird die vorhandene Karte standardmäßig durch diese ersetzt.

4. Registrieren des Aktionshandlers

Sie müssen jede neue Kartenaktion im konfigurieren, die conversationBot den Konversationsfluss der Workflowbotvorlage ermöglicht. Sie können zur bot/src/internal/initialize.js(ts) Datei navigieren und das actions Array der cardAction Eigenschaft aktualisieren.

Die folgenden Schritte helfen Ihnen beim Registrieren des Aktionshandlers:

  1. Sie können die Datei bot/src/internal/initialize.js(ts)öffnen.

  2. Sie müssen Ihre conversationBot Initialisierung aktualisieren, um das Feature zu aktivieren cardAction . Fügen Sie den Handler mithilfe des folgenden Codes dem Array hinzu actions :

          const conversationBot = new ConversationBot({ 
     ... 
     cardAction: { 
       enabled: true, 
       actions: [ 
         new DoStuffActionHandler(),
         new DoSomethingActionHandler() 
       ], 
     } 
   });

    Hinweis

    Weitere Informationen zum Erweitern der Workflowbotvorlage finden Sie unter Reagieren auf Kartenaktionen in Teams.


Anpassen der Aktionsantwort

Sie können die adaptiveCardResponse -Eigenschaft im Handler verwenden, um anzupassen, wie der Bot die adaptive Karte an Benutzer sendet. Im Folgenden sind die drei Optionen zum Anpassen aufgeführt:

  • Die Antwortkarte wird durch die aktuelle Karte ersetzt, auf der die Schaltfläche für den Interaktor definiert ist, der die Aktion auslöst. Die Benutzer in der Unterhaltung können weiterhin standardmäßig die ursprüngliche Aktionskarte AdaptiveCardResponse.ReplaceForInteractor anzeigen.

    Screenshot: Anpassen der Vorgehensweise beim Senden einer adaptiven Karte durch den Bot

  • Die Antwortkarte wird durch die Aktionskarte für alle Benutzer im Chat ersetzt, und sie können die Antwortkarte AdaptiveCardResponse.ReplaceForAllanzeigen.

    Screenshot: Die Aktionskarte für alle Benutzer im Chat wurde durch die Schaltfläche

    Screenshot: Ersetzte Aktionskarte für alle Benutzer im Chat ohne Bestätigungsschaltfläche.

  • Die Antwortkarte wird als separate Nachricht in der Unterhaltung gesendet, die die Aktionskarte nicht ersetzen kann. Alle Benutzer im Chat können die Antwortkarte AdaptiveCardResponse.NewForAllanzeigen.

    Screenshot: Antwortkarte, die für alle benutzer im Chat als separate Nachricht gesendet wird

Antworten mit SMS

Sie können auch mit SMS antworten, anstatt adaptive Karte für die Kartenaktionsantwort zu verwenden, indem Sie verwenden InvokeResponseFactory.textMessage:

async handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse> {
    return InvokeResponseFactory.textMessage("This is a sample card action response!");
}

Die folgende Antwortnachricht wird in Teams angezeigt:

Screenshot: Beispielantwort einer Karte

Antworten mit Fehlermeldungen

Wenn Sie eine Fehlermeldung an den Client zurückgeben möchten, können Sie anwenden InvokeResponseFactory.errorResponse , um Ihre Aufrufantwort zu erstellen. Die folgende Abbildung zeigt die Fehlermeldung in adaptiver Karte:

Screenshot: Fehlermeldung

Hinweis

Weitere Informationen zum Aufrufantwortformat finden Sie unter Antwortformat.

Anpassen von Inhalten für adaptive Karten

Sie können die Datei src/adaptiveCards/helloworldCommand.json bearbeiten, um adaptive Karten an Ihre Bevorzugten Anzupassen. Die Datei src/cardModels.ts definiert eine Datenstruktur, die zum Auffüllen von Daten für die adaptive Karte verwendet wird.

Die Bindung zwischen dem Modell und der adaptiven Karte erfolgt durch den übereinstimmenden Namen, CardData.title z. B. wird in adaptiver Karte zugeordnet ${title} . Sie können Eigenschaften und deren Bindungen hinzufügen, bearbeiten oder entfernen, um die adaptive Karte an Ihre Anforderungen anzupassen.

Sie können auch neue Karten hinzufügen, wenn dies für Ihre Anwendung erforderlich ist. Informationen zum Erstellen verschiedener Typen von adaptiven Karten mit einer Liste oder einer Tabelle mit dynamischen Inhalten mithilfe ColumnSet von und FactSetfinden Sie unter TeamsFx-Samples.

Automatische Aktualisierung zur benutzerspezifischen Ansicht

Wenn adaptive Karten in einem Teams-Kanal oder Gruppenchat gesendet werden, können alle Benutzer denselben Karteninhalt sehen. Mit der universellen Aktion "Aktualisierungsmodell für adaptive Karten" können Benutzer über eine benutzerspezifische Ansicht verfügen. Die automatische Aktualisierung erleichtert auch Szenarien wie Genehmigungen, Steuerelemente für Umfrageersteller, Ticketerstellung, Incidentmanagement und Projektmanagementkarten. Das folgende Diagramm veranschaulicht, wie Sie eine benutzerspezifische Ansicht mit refresh Modell bereitstellen:

Das Diagramm zeigt ein benutzerspezifisches Modell für die automatische Aktualisierung.

  1. Basiskarte: Der Bot sendet eine Nachricht mit der Basisversion der Karte. Diese Basiskarte kann als Botbenachrichtigung, Befehlsantwort oder jede andere Kartenaktionsantwort gesendet werden. Alle Mitglieder der Unterhaltung können dieselbe Antwort anzeigen. Die Basiskarte wird automatisch auf den Benutzer aktualisiert, der in der refresh -Eigenschaft der Basiskarte definiert userId ist.

  2. Aktualisierungsverhalten: Nachdem der Benutzer die Nachricht angezeigt hat, löst der Teams-Client eine Minute nach der letzten Aktualisierungsantwort automatisch eine Aktualisierung aus. Der benutzerspezifische Ansichtshandler wird aufgerufen, um eine Kartenansicht Response Card für einen bestimmten Benutzer UserAzurückzugeben. Andere Benutzer in der Unterhaltung können die Basiskarte weiterhin anzeigen.

Die folgende Abbildung veranschaulicht, wie die benutzerspezifische Ansicht in Teams angezeigt wird:

Screenshot: Benutzerspezifische Ansicht in Teams

Hinzufügen einer benutzerspezifischen Ansicht

Die folgenden Schritte helfen Ihnen beim Hinzufügen einer benutzerspezifischen Ansicht mit dem TeamsFx SDK:


1. Aktivieren der Aktualisierung in adaptiver Basiskarte

Die benutzerspezifischen Ansichten werden von einer Basiskarte aktualisiert, wenn die Antwortkarte von der Basiskarte aktualisiert wird, wie in der benutzerspezifischen Ansicht zur automatischen Aktualisierung dargestellt. Sie können die automatische Aktualisierung auf der Basiskarte wie folgt aktivieren:

  • Die erste Option ermöglicht die benutzerspezifische Ansichtsaktualisierung mit dem SDK. Die Basiskarte kann als Befehlsantwort oder Kartenaktionsantwort gesendet werden. Sie können die benutzerspezifische Ansichtsaktualisierung in handleCommandReceived einem Befehlshandler oder in handleActionInvoked einem Kartenaktionshandler aktivieren, in dem die Basiskarte zurückgegeben wird. Sie können die -Methode aus der @microsoft/adaptivecards-tools Bibliothek verwendenrefresh(refreshVerb, userIds, data), um einen Aktualisierungsabschnitt in Ihre Basiskarte einzufügen. Stellen Sie zum Definieren des Aktualisierungsabschnitts sicher, dass Sie die folgenden Eigenschaften angeben:

    1. userIds: Eine Gruppe von Benutzer-MRIs für Benutzer, die die automatische Aktualisierung auslösen können. Weitere Informationen zum Hinzufügen userIds einer Liste im Aktualisierungsabschnitt der adaptiven Karte finden Sie unter Abrufen der Liste oder des Benutzerprofils.
    2. verb: Eine Zeichenfolge zum Identifizieren der Aktualisierungsaktion.
    3. data: Optionale Daten, die der Aktualisierungsaktion zugeordnet werden sollen.

    Im folgenden Beispiel gibt eine Basiskarte als Befehlsantwort zurück, die automatisch für einen bestimmten Benutzer aktualisiert werden kann, z. B. für den Befehlssender:

             import baseCard from "../adaptiveCards/baseCard.json";
         import { AdaptiveCards } from "@microsoft/adaptivecards-tools";

         export class MyCommandHandler1 implements TeamsFxBotCommandHandler {
         triggerPatterns: TriggerPatterns = "helloWorld";

         async handleCommandReceived(context: TurnContext, message: CommandMessage): 
         Promise<string | Partial<Activity> | void> {
         const refreshVerb = "userViewRefresh";        // verb to identify the refresh action
         const userIds = [ context.activity.from.id ]; // users who will be refreshed
         const data = { key: "value"};                 // optional data associated with the action

         const responseCard = AdaptiveCards
           .declare(baseCard)
           .refresh(refreshVerb, userIds, data)
           .render(cardData);

             return MessageFactory.attachment(CardFactory.adaptiveCard(responseCard));
         }
       }

  • Die zweite Option ermöglicht die benutzerspezifische Ansicht zum Aktualisieren Ihrer adaptiven Karte. Dies ist eine Beispielaktualisierungsaktion, die in baseCard.jsondefiniert ist:

    {
  "type": "AdaptiveCard",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Refresh",
      "verb": "userViewRefresh" ,
      "data": {
        "key": "value"
      }
    },
    "userIds": [
      "${userID}"
    ]
  },
  "body": [
    ...
  ],
  ...
}

    Sie müssen beim Rendern des Karteninhalts im Code durch mrT des Benutzers ersetzen.You need to replace ${userID} with user MRI in code, while rendering your card content.


2. Hinzufügen einer benutzerspezifischen adaptiven Karte

Sie müssen die benutzerspezifische adaptive Karte entwerfen, um eine bestimmte Antwortkarte zu aktualisieren, z responseCard.json . B. für userA , die im Diagramm für das Aktualisierungsverhalten angezeigt wird. Um zu beginnen, können Sie einen responseCard.json mit dem folgenden Inhalt erstellen und im bot/src/adaptiveCards Ordner speichern:

-
{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "This is a user-specific view"
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4"
}

3. Hinzufügen eines Kartenaktionshandlers zum Aktualisieren von Ansichten

Sie können einen Handler hinzufügen, der implementiert, um die Aktualisierungsaufrufaktivität TeamsFxAdaptiveCardActionHandler zu verarbeiten, die automatisch in Teams ausgelöst wird:

import responseCard from "../adaptiveCards/responseCard.json";

export class Handler1 implements TeamsFxBotCardActionHandler {
    triggerVerb: string = "userViewRefresh";

    async handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse> {
      /**
       * If you have multiple userIds defined in your refresh action, for example: userIds: [ "<UserA>", "<userB>" ] ,
       * and you can return different card response for those users respectively with the following code sample.
        
        const currentUserId = context.activity.from.id;
        switch (currentUserId) {
          case "<userA's id>":
            const card1 = AdaptiveCards.declare(card1).render(actionData);
            return InvokeResponseFactory.adaptiveCard(card1);
          case "<userB's id>":
            const card1 = AdaptiveCards.declare(card2).render(actionData);
            return InvokeResponseFactory.adaptiveCard(card2);
        }
     */
      const responseCardJson = AdaptiveCards.declare(responseCard).render(actionData);
      return InvokeResponseFactory.adaptiveCard(responseCardJson);
    } 
}

4. Registrieren des Aktionshandlers

Sie können den Aktualisierungsaktionshandler in bot/src/internal/initialize.js(ts) mit dem folgenden Code registrieren:

export const commandBot = new ConversationBot({
  ...
  cardAction: {
    enabled: true,
    actions: [
      new Handler1()
    ],
  }
})

Zugreifen auf Microsoft Graph

Wenn Sie auf einen Befehl reagieren, der auf Microsoft Graph-Daten eines bereits angemeldeten Teams-Benutzers zugreifen muss, können Sie dies durch einmaliges Anmelden (Single Sign-On, SSO) mit dessen Teams-Benutzertoken tun. Erfahren Sie mehr darüber, wie Teams Toolkit Ihnen beim Hinzufügen des einmaligen Anmeldens in der Teams-App helfen kann.

Herstellen einer Verbindung mit vorhandenen APIs

Sie müssen häufig eine Verbindung mit vorhandenen APIs herstellen, um Daten abzurufen, die an Teams gesendet werden sollen. Teams Toolkit erleichtert Ihnen das Konfigurieren und Verwalten der Authentifizierung für vorhandene APIs. Weitere Informationen finden Sie unter Integrieren vorhandener APIs von Drittanbietern.

Häufig gestellte Fragen


Wie kann ein Workflowbot mit Benachrichtigungen erweitert werden?

Benachrichtigungen fügen in Ihrer App die Möglichkeit hinzu, adaptive Karten als Reaktion auf externe Ereignisse zu senden. Wenn beispielsweise eine Nachricht an einen Event Hub gesendet wird, kann Ihre App bei Bedarf mit einer adaptiven Karte antworten. Informationen zum Erweitern eines Workflowbots mit Benachrichtigungen finden Sie unter Anpassen von Benachrichtigungen.


Wie kann ein Workflowbot mit Befehl und Antwort erweitert werden?

Der Standardworkflowbot enthält Befehl und Antwort. Weitere Informationen zum Erweitern eines Workflowbots mit Befehl und Antwort finden Sie unter Hinzufügen von Befehl und Antwort.


Schrittweise Anleitung

Befolgen Sie die Schritt-für-Schritt-Anleitung zum Erstellen eines Teams-Workflowbots .

Siehe auch