Bot de flux de travail dans Teams

Un bot de workflow permet aux utilisateurs d’interagir avec une carte adaptative. Le gestionnaire d’actions de carte adaptative permet à la carte adaptative de converser dans l’application Teams. Vous pouvez créer un bot de flux de travail dans plusieurs scénarios pour vos utilisateurs afin d’améliorer l’expérience utilisateur, comme la gestion des incidents, la création de tickets, le flux de travail d’approbation et les cartes de gestion de projet. Vous pouvez créer et affecter un élément de travail avec un bot de flux de travail et synchroniser le contenu avec le système Azure DevOps ou Jira.

Un bot de flux de travail peut être installé dans une équipe, une conversation de groupe ou en tant qu’application personnelle, selon différentes étendues. La logique de commande par défaut retourne une carte adaptative. Vous pouvez personnaliser cette logique en fonction des besoins de votre entreprise. Pour la personnalisation, vous devez appeler vos API existantes.

Avantages :

  • Automatise les processus métier et les workflows répétitifs sans quitter le contexte des conversations.

  • Prend en charge les utilisateurs avec un flux de travail séquentiel via différentes cartes progressivement, sans envoyer de cartes supplémentaires.

  • Fournit des vues spécifiques à l’utilisateur à jour.

  • Simplifie le modèle de programmation avec le Kit de développement logiciel (SDK) TeamsFx.

    Remarque

    Vous pouvez sélectionner la fonctionnalité que vous souhaitez installer lors de l’ajout de l’application. Pour plus d’informations, consultez Configurer les options d’installation par défaut.

Vous pouvez créer un bot de flux de travail pour répondre à la carte adaptative déclenchée par les utilisateurs. Le gestionnaire d’actions de carte adaptative alimenté par le SDK TeamsFx peut exécuter l’action Action.Execute universelle de carte adaptative déclenchée par les utilisateurs. En réponse à cette action de carte respective dans la conversation, une autre carte adaptative est envoyée par le gestionnaire d’actions de carte adaptative.

Sortie finale du bot de flux de travail avec un bouton

Gestionnaire d’actions de carte

Pour simplifier la création d’un bot de flux de travail, le Kit de développement logiciel (SDK) TeamsFx fournit un gestionnaire TeamsFxAdaptiveCardActionHandlerd’actions de carte adaptative . Vous pouvez vous concentrer uniquement sur le développement d’un bot de workflow pour répondre à l’action de carte sans apprendre le Bot Framework.

Le diagramme suivant montre comment répondre à une action de carte adaptative avec le Kit de développement logiciel (SDK) TeamsFx :

Diagramme du gestionnaire d’actions de carte de bot de workflow

  1. Carte d’action : carte dans laquelle vous définissez votre action que les utilisateurs peuvent appeler, par exemple .DoStuff
  2. Gestionnaire d’actions de carte : déclenché lorsque les utilisateurs appellent l’action de carte correspondante, il triggerVerb est identique à la propriété dans action verb de carte adaptative. Il peut envoyer une carte de réponse pour répondre à l’action.
  3. Carte de réponse : carte qui répond à l’action lorsque l’utilisateur l’appelle à partir de la carte d’action.

Pour gérer les actions de carte avec le Kit de développement logiciel (SDK) TeamsFx, chaque gestionnaire d’actions de carte doit implémenter l’interface TeamsFxAdaptiveCardActionHandler . Il s’agit de la définition d’interface pour TeamsFxAdaptiveCardActionHandler:


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>;
}

Personnaliser l’initialisation

Vous pouvez initialiser le bot de workflow avec votre propre adaptateur ou le personnaliser après l’initialisation. L’initialisation par défaut se trouve dans bot/src/internal/initialize.js(ts).

Vous pouvez mettre à jour la logique d’initialisation pour :

  1. Définissez options.adapter pour utiliser votre propre BotFrameworkAdapter.
  2. Définissez options.command.commands pour inclure plusieurs gestionnaires de commandes.
  3. Définissez options.cardAction.actions pour inclure plusieurs gestionnaires d’actions.
  4. Définissez options.{feature}.enabled pour activer plusieurs ConversationBot fonctionnalités.

Pour plus d’informations sur la personnalisation de l’initialisation, consultez Personnalisation d’initialisation supplémentaire

Ajouter des actions de carte

Pour ajouter des actions de carte avec JavaScript et TypeScript, vous pouvez effectuer les opérations suivantes :


1. Ajouter une action à votre carte adaptative

Vous pouvez ajouter une nouvelle action (bouton) à une carte adaptative en la définissant dans le fichier JSON, par exemple en ajoutant une nouvelle DoSomething action au src/adaptiveCards/helloworldCommandResponse.json fichier. Il s’agit d’un exemple de type Action.Executed’action :

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

Lorsque l’action est appelée dans Teams, la propriété verb est requise, afin que le Kit de développement logiciel (SDK) de conversation TeamsFx puisse appeler le gestionnaire d’actions correspondant.

Remarque

Veillez à fournir une chaîne unique globale pour la propriété de verbe, lorsque vous utilisez une chaîne générale susceptible d’entraîner une collision avec un autre bot. Cela peut éviter un comportement inattendu.


2. Répondre avec une nouvelle carte adaptative

Vous pouvez retourner une nouvelle carte adaptative pour chaque action appelée pour afficher la réponse à l’utilisateur final. Vous devez créer un fichier, bot/src/adaptiveCards/doSomethingResponse.json en tant que réponse à l’action doSomething avec le contenu suivant :

{
  "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"
}

Remarque

Vous pouvez concevoir la disposition de votre carte en fonction des besoins de votre entreprise. Voir Concepteur de cartes adaptatives.


3. Ajouter un gestionnaire d’actions

Vous pouvez gérer une nouvelle action appelée par carte adaptative avec la classe TeamsFxAdaptiveCardActionHandlerdu SDK TeamsFx . Vous devez personnaliser l’action dans cette étape, comme appeler une API, traiter des données ou toute autre action en fonction des besoins de votre entreprise.

Vous pouvez créer un fichier bot/src/cardActions/doSomethingActionHandler.js:

    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,
    }

Voici un exemple de gestionnaire d’actions :

  • triggerVerb est la propriété de verbe de votre action.
  • actionData est les données associées à l’action, qui peuvent inclure une entrée utilisateur dynamique ou certaines données contextuelles fournies dans la propriété de données de votre action.
  • Si une carte adaptative est retournée, la carte existante est remplacée par elle par défaut.

4. Inscrire le gestionnaire d’actions

Vous devez configurer chaque nouvelle action de carte dans le conversationBot qui active le flux conversationnel du modèle de bot de workflow. Vous pouvez accéder au bot/src/internal/initialize.js(ts) fichier et mettre à jour le actions tableau de la cardAction propriété .

Les étapes suivantes vous aident à inscrire le gestionnaire d’actions :

  1. Vous pouvez ouvrir le fichier bot/src/internal/initialize.js(ts).

  2. Vous devez mettre à jour votre conversationBot initialisation, pour activer cardAction la fonctionnalité et ajouter le gestionnaire au tableau d’actions :

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

    Remarque

    Pour en savoir plus sur l’extension du modèle de bot de flux de travail, consultez Répondre aux actions de carte dans Teams


Personnaliser la réponse de l’action

Vous pouvez utiliser la adaptiveCardResponse propriété dans handler pour personnaliser la façon dont le bot envoie la carte adaptative aux utilisateurs. Voici les trois options à personnaliser :

  • La carte de réponse est remplacée par la carte active où le bouton est défini pour l’interacteur qui déclenche l’action. Les utilisateurs de la conversation peuvent toujours afficher la carte AdaptiveCardResponse.ReplaceForInteractord’action d’origine . Il s'agit du comportement par défaut.

    Personnaliser la façon dont le bot envoie la carte adaptative

  • La carte de réponse est remplacée par la carte d’action pour tous les utilisateurs de la conversation, et ils peuvent afficher la carte AdaptiveCardResponse.ReplaceForAllde réponse .

    Remplacement de la carte d’action pour tous par le bouton Accusé de réception

    Remplacement de la carte d’action pour tous

  • La carte de réponse est envoyée sous la forme d’un message distinct dans la conversation qui ne peut pas remplacer la carte d’action. Tous les utilisateurs de la conversation peuvent afficher la carte AdaptiveCardResponse.NewForAllde réponse .

    Carte de réponse envoyée pour tous en tant que nouveau

Répondre par SMS

Vous pouvez également répondre avec des sms au lieu d’utiliser la carte adaptative pour la réponse à l’action de carte, à l’aide InvokeResponseFactory.textMessagede :

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

Vous pouvez voir le message de réponse suivant dans Teams :

exemple de réponse de carte affichée

Répondre avec des messages d’erreur

Lorsque vous souhaitez retourner un message de réponse d’erreur au client, vous pouvez appliquer InvokeResponseFactory.errorResponse pour générer votre réponse d’appel. L’image suivante montre un message d’erreur dans la carte adaptative :

message de réponse d’erreur affiché

Remarque

Pour plus d’informations sur le format de réponse d’appel, consultez Format de réponse.

Personnaliser le contenu de la carte adaptative

Vous pouvez modifier le fichier src/adaptiveCards/helloworldCommand.json pour personnaliser la carte adaptative selon vos préférences. Le fichier src/cardModels.ts définit une structure de données utilisée pour remplir les données de la carte adaptative.

La liaison entre le modèle et la carte adaptative s’effectue en faisant correspondre le nom, par exemple, CardData.title mappe à ${title} dans la carte adaptative. Vous pouvez ajouter, modifier ou supprimer des propriétés et leurs liaisons pour personnaliser la carte adaptative en fonction de vos besoins.

Vous pouvez également ajouter de nouvelles cartes, si nécessaire pour votre application. Pour créer différents types de cartes adaptatives avec une liste ou une table de contenu dynamique à l’aide ColumnSet de et FactSet, consultez TeamsFx-Samples.

Actualisation automatique vers une vue spécifique à l’utilisateur

Lorsque des cartes adaptatives sont envoyées dans un canal Teams ou une conversation de groupe, tous les utilisateurs peuvent voir le même contenu de carte. Avec le nouveau modèle d’actualisation de l’action universelle cartes adaptatives, les utilisateurs peuvent avoir une vue spécifique à l’utilisateur. L’actualisation automatique facilite également les scénarios tels que les approbations, les contrôles du créateur de sondage, la création de tickets, la gestion des incidents et les cartes de gestion de projet. Le diagramme suivant montre comment fournir une vue spécifique à l’utilisateur avec refresh le modèle :

Vue schématique du modèle d’actualisation automatique spécifique à l’utilisateur

  1. Carte de base : le bot envoie un message avec la version de base de la carte. Cette carte de base peut être envoyée sous la forme d’une notification de bot, d’une réponse de commande ou de toute autre réponse d’action de carte. Tous les membres de la conversation peuvent afficher la même réponse. La carte de base est automatiquement actualisée pour l’utilisateur défini userId dans la refresh propriété de la carte de base.

  2. Comportement d’actualisation : une fois que l’utilisateur a affiché le message, le client Teams déclenche automatiquement une actualisation une minute après la dernière réponse d’actualisation. Le gestionnaire d’affichage spécifique à l’utilisateur est appelé pour retourner une vue Response Card par carte pour un utilisateur UserAspécifique. Les autres utilisateurs de la conversation peuvent toujours afficher la carte de base.

L’image suivante illustre l’affichage spécifique de l’utilisateur dans Teams :

Affichage spécifique à l’utilisateur dans teams

Ajouter une vue spécifique à l’utilisateur

Les étapes suivantes vous aident à ajouter une vue spécifique à l’utilisateur avec le Kit de développement logiciel (SDK) TeamsFx :


1. Activer l’actualisation dans la carte adaptative de base

Les vues spécifiques à l’utilisateur sont actualisées à partir d’une carte de base, lorsque la carte de réponse est actualisée à partir de la carte de base, comme illustré dans la vue d’actualisation automatique spécifique à l’utilisateur. Vous devez activer l’actualisation automatique sur la carte de base. Il existe deux options pour y parvenir :

  • La première option active l’actualisation de la vue spécifique à l’utilisateur avec le Kit de développement logiciel (SDK). La carte de base peut être envoyée sous la forme d’une réponse de commande ou d’une réponse d’action de carte. Vous pouvez activer l’actualisation de l’affichage spécifique à l’utilisateur dans handleCommandReceived un gestionnaire de commandes ou dans handleActionInvoked le gestionnaire d’actions de carte où la carte de base est retournée. Vous pouvez utiliser refresh(refreshVerb, userIds, data) la méthode de la @microsoft/adaptivecards-tools bibliothèque pour injecter une section d’actualisation dans votre carte de base. Pour définir la section d’actualisation, veillez à fournir les éléments suivants :

    1. userIds: ensemble d’IRM utilisateur pour ceux qui peuvent déclencher l’actualisation automatique. Pour plus d’informations sur la façon d’ajouter une liste dans userIds la section Actualisation de la carte adaptative, consultez Extraire la liste de noms ou le profil utilisateur.
    2. verb: chaîne pour identifier l’action d’actualisation.
    3. data: données facultatives à associer à l’action d’actualisation.

    Dans l’exemple suivant, une carte de base retourne en tant que réponse de commande qui peut s’actualiser automatiquement à un utilisateur spécifique, tel que l’expéditeur de la commande :

             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));
             }
           }
    
  • La deuxième option permet à l’affichage spécifique de l’utilisateur d’actualiser votre carte adaptative. Il s’agit d’un exemple d’action d’actualisation défini dans baseCard.json:

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

    Vous devez remplacer par ${userID} l’irm utilisateur dans le code, lors du rendu du contenu de votre carte.


2. Ajouter une carte adaptative spécifique à l’utilisateur

Vous devez concevoir la carte adaptative spécifique à l’utilisateur pour actualiser une carte de réponse spécifique, par responseCard.json exemple pour userA le comportement d’actualisation dans le diagramme. Pour commencer, vous pouvez créer un responseCard.json avec le contenu suivant et l’enregistrer dans le bot/src/adaptiveCards dossier :


{
  "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. Ajouter un gestionnaire d’actions de carte pour actualiser les vues

Vous pouvez ajouter un gestionnaire qui implémente TeamsFxAdaptiveCardActionHandler pour traiter l’activité d’appel d’actualisation qui est automatiquement déclenchée dans Teams :

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. Inscrire le gestionnaire d’actions

Vous pouvez inscrire le gestionnaire d’actions d’actualisation dans bot/src/internal/initialize.js(ts) avec le code suivant :

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


Accéder à Microsoft Graph

Si vous répondez à une commande qui doit accéder aux données Microsoft Graph d’un utilisateur Teams déjà connecté, vous pouvez le faire par authentification unique (SSO) avec son jeton d’utilisateur Teams. En savoir plus sur la façon dont Teams Toolkit peut vous aider à ajouter l’authentification unique à l’application Teams.

Se connecter à des API existantes

Vous devez souvent vous connecter à des API existantes pour récupérer des données à envoyer à Teams. Teams Toolkit vous permet de configurer et de gérer facilement l’authentification pour les API existantes. Pour plus d’informations, consultez Comment intégrer des API tierces existantes.

Questions fréquentes (FAQ)


Comment étendre le bot de workflow avec des notifications ?

Les notifications ajoutent la possibilité dans votre application d’envoyer des cartes adaptatives en réponse à des événements externes. Par exemple, lorsqu’un message est publié sur un hub d’événements, votre application peut répondre avec une carte adaptative en fonction des besoins. Comment étendre le bot de flux de travail avec des notifications, consultez Personnaliser les notifications.


Comment étendre le bot de workflow avec la commande et la réponse ?

Le bot de workflow par défaut est fourni avec la commande et la réponse. Pour plus d’informations sur l’extension du bot de flux de travail avec la commande et la réponse, consultez ajouter une commande et une réponse.


Guide pas à pas

Suivez le guide pas à pas pour créer un bot de flux de travail Teams.

Voir aussi