Bot de fluxo de trabalho no Teams

Um bot de fluxo de trabalho permite que os usuários interajam com um Cartão Adaptável. O manipulador de ação Cartão Adaptável permite que o cartão Adaptável converse no aplicativo teams. Você pode criar um bot de fluxo de trabalho em vários cenários para que seus usuários aprimorem a experiência do usuário, como gerenciamento de incidentes, tíquetes, fluxo de trabalho de aprovação e cartões de gerenciamento de projeto. Você pode criar e atribuir um item de trabalho com o bot de fluxo de trabalho e sincronizar o conteúdo com o Azure DevOps ou o sistema Jira.

Um bot de fluxo de trabalho pode ser instalado em uma equipe, chat em grupo ou como aplicativo pessoal, dependendo de escopos diferentes. A lógica de comando padrão retorna um Cartão Adaptável. Você pode personalizar essa lógica com seus requisitos de negócios. Para a personalização, você precisa chamar suas APIs existentes.

Vantagens:

• Automatiza processos de negócios e fluxos de trabalho repetitivos sem sair do contexto de conversas.

• Dá suporte a usuários com fluxo de trabalho sequencial por meio de vários cartões progressivamente, sem enviar cartões adicionais.

• Fornece exibições atualizadas específicas do usuário.

• Simplifica o modelo de programação com o SDK do TeamsFx.

  Observação

  Você pode selecionar o recurso que deseja instalar ao adicionar o aplicativo. Para obter mais informações, confira configurar opções de instalação padrão.

Você pode criar um bot de fluxo de trabalho para responder ao Cartão Adaptável disparado pelos usuários. O manipulador de ação cartão adaptável alimentado pelo SDK do TeamsFx pode executar a ação Action.Execute universal cartão adaptável disparada pelos usuários. Em resposta a essa respectiva ação cartão na conversa, o manipulador de ação Cartão Adaptável envia outro Cartão Adaptável.

Manipulador de ação de cartão

Para simplificar a criação de um bot de fluxo de trabalho, o SDK do TeamsFx fornece um manipulador TeamsFxAdaptiveCardActionHandlerde ação cartão adaptável . Você só pode se concentrar no desenvolvimento do bot de fluxo de trabalho para responder à ação cartão sem aprender o Bot Framework.

O diagrama a seguir ilustra como responder a uma ação de Cartão Adaptável com o SDK do TeamsFx:

1. Ação cartão: o cartão em que você define sua ação que os usuários podem invocar, por exemplo, o DoStuff.
2. Manipulador de ação de cartão: disparado quando os usuários invocam a ação cartão correspondente, ela triggerVerb é igual à propriedade na ação verb Cartão Adaptável. Ele pode enviar uma cartão de resposta para responder à ação.
3. Cartão de resposta: o cartão que responde à ação quando o usuário a invoca do cartão de ação.

Para lidar com cartão ações com o SDK do TeamsFx, cada manipulador de ações cartão deve implementar a TeamsFxAdaptiveCardActionHandler interface:

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

Personalizar a inicialização

Você pode inicializar o bot de fluxo de trabalho com seu próprio adaptador ou personalizar após a inicialização. A inicialização padrão está localizada em bot/src/internal/initialize.js(ts).

Você pode atualizar a lógica de inicialização para:

1. Defina options.adapter para usar seu próprio BotFrameworkAdapter.
2. Defina options.command.commands para incluir vários manipuladores de comando.
3. Defina options.cardAction.actions como incluir vários manipuladores de ação.
4. Defina options.{feature}.enabled para habilitar várias ConversationBot funcionalidades.

Para obter mais informações sobre a personalização de inicialização, confira personalização de inicialização adicional

Adicionar ações de cartão

Para adicionar ações de cartão com JavaScript e TypeScript, siga estas etapas:

1. Adicionar uma ação ao cartão adaptável

Você pode adicionar uma nova ação (botão) a um Cartão Adaptável definindo-o no arquivo JSON, como adicionar uma nova DoSomething ação ao src/adaptiveCards/helloworldCommandResponse.json arquivo.

O código a seguir é um exemplo do tipo Action.Executede ação :

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

Quando a ação é invocada no Teams, a propriedade verbo é necessária para que o SDK de conversa do TeamsFx possa invocar o manipulador de ações correspondente.

Observação

Certifique-se de fornecer uma cadeia de caracteres exclusiva global para a propriedade verbo, quando você estiver usando uma cadeia de caracteres geral que pode causar uma colisão com outro bot. Isso pode evitar um comportamento inesperado.

2. Responder com o novo Cartão Adaptável

Você pode retornar um novo Cartão Adaptável para cada ação invocada para exibir a resposta ao usuário final. Você precisa criar um novo arquivo, bot/src/adaptiveCards/doSomethingResponse.json como uma resposta para a ação doSomething com o seguinte conteúdo:

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

Observação

Você pode projetar seu layout de cartão de acordo com sua necessidade de negócios. Veja, designer de cartão adaptável.

3. Adicionar manipulador de ações

Você pode lidar com uma nova ação invocada pelo Cartão Adaptável com a classe TeamsFxAdaptiveCardActionHandlerdo SDK do TeamsFx . Você precisa personalizar a ação nesta etapa, como chamar uma API, processar dados ou qualquer outra ação de acordo com a necessidade da sua empresa.

JavaScript

Você pode criar um novo arquivo 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,
    }

TypeScript

Você pode criar um novo arquivo bot/src/cardActions/doSomethingActionHandler.ts:

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

    export class DoSomethingActionHandler {
        triggerVerb = "doSomething";

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

Observação

• triggerVerb é a propriedade verbo de sua ação.
• actionData são os dados associados à ação, que podem incluir entrada dinâmica do usuário ou alguns dados contextuais fornecidos na propriedade de dados de sua ação.
• Se um Cartão Adaptável for retornado, o cartão existente será substituído por ele por padrão.

4. Registrar o manipulador de ações

Você precisa configurar cada nova ação cartão no conversationBot que habilita o fluxo de conversa do modelo de bot de fluxo de trabalho. Você pode navegar até o bot/src/internal/initialize.js(ts) arquivo e atualizar a actions matriz da cardAction propriedade.

As seguintes etapas ajudam você a registrar o manipulador de ações:

1. Você pode abrir o arquivo bot/src/internal/initialize.js(ts).

2. Você precisa atualizar sua conversationBot inicialização para habilitar cardAction o recurso. Adicione o manipulador à actions matriz usando o seguinte código:

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

   Observação

   Para saber mais sobre como estender o modelo de bot de fluxo de trabalho, confira responder a ações de cartão no Teams

Personalizar a resposta de ação

Você pode usar a adaptiveCardResponse propriedade no manipulador para personalizar como o bot envia o Cartão Adaptável aos usuários. A seguir estão as três opções para personalizar:

• O cartão de resposta é substituído pelo cartão atual em que o botão é definido para o interacionador que dispara a ação. Os usuários na conversa ainda podem exibir a ação original cartão AdaptiveCardResponse.ReplaceForInteractor por padrão.

  

• O cartão de resposta é substituído pelo cartão de ação para todos os usuários no chat e eles podem exibir a resposta cartão AdaptiveCardResponse.ReplaceForAll.

  

  

• O cartão de resposta é enviado como uma mensagem separada na conversa que não pode substituir a ação cartão. Todos os usuários no chat podem exibir a resposta cartão AdaptiveCardResponse.NewForAll.

  

Responder com mensagem de texto

Você também pode responder com mensagens de texto em vez de usar o Cartão Adaptável para cartão resposta de ação, usando InvokeResponseFactory.textMessage:

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

Você pode ver a seguinte mensagem de resposta no Teams:

Responder com mensagens de erro

Quando você deseja retornar uma mensagem de resposta de erro ao cliente, você pode aplicar InvokeResponseFactory.errorResponse para criar sua resposta de invocação. A imagem a seguir mostra a mensagem de erro no Cartão Adaptável:

Observação

Para obter mais informações sobre o formato de resposta de invocação, consulte formato de resposta.

Personalizar o conteúdo do Cartão Adaptável

Você pode editar o arquivo src/adaptiveCards/helloworldCommand.json para personalizar o Cartão Adaptável à sua preferência. O arquivo src/cardModels.ts define uma estrutura de dados usada para preencher dados para o Cartão Adaptável.

A associação entre o modelo e o Cartão Adaptável é feita pelo nome correspondente, como, CardData.title mapeia para ${title} em Cartão Adaptável. Você pode adicionar, editar ou remover propriedades e suas associações para personalizar o Cartão Adaptável às suas necessidades.

Você também pode adicionar novos cartões, se necessário para seu aplicativo. Para criar diferentes tipos de Cartões Adaptáveis com uma lista ou uma tabela de conteúdo dinâmico usando ColumnSet e FactSet, consulte TeamsFx-Samples.

Atualização automática para exibição específica do usuário

Quando cartões adaptáveis são enviados em um canal do Teams ou chat em grupo, todos os usuários podem ver o mesmo cartão conteúdo. Com o novo modelo de atualização para a ação universal cartões adaptáveis, os usuários podem ter uma exibição específica do usuário. A atualização automática também facilita cenários como aprovações, controles do criador da pesquisa, tíquetes, gerenciamento de incidentes e cartões de gerenciamento de projetos. O diagrama a seguir ilustra como fornecer uma exibição específica do usuário com refresh o modelo:

1. Cartão base: o bot envia uma mensagem com a versão base do cartão. Esse cartão base pode ser enviado como uma notificação de bot, resposta de comando ou qualquer outra resposta de ação cartão. Todos os membros da conversa podem exibir a mesma resposta. O cartão base é atualizado automaticamente para o usuário definido userId na refresh propriedade do cartão base.

2. Comportamento de atualização: depois que o usuário visualiza a mensagem, o cliente do Teams dispara automaticamente uma atualização um minuto após a última resposta de atualização. O manipulador de exibição específico do usuário é invocado para retornar uma exibição Response Card de cartão para um usuário UserAespecífico . Outros usuários na conversa ainda podem exibir o cartão base.

A imagem a seguir ilustra como a exibição específica do usuário é exibida no Teams:

Adicionar exibição específica do usuário

As etapas a seguir ajudam você a adicionar uma exibição específica do usuário ao SDK do TeamsFx:

1. Habilitar a atualização no cartão adaptável base

As exibições específicas do usuário são atualizadas de uma cartão base, quando o cartão de resposta é atualizado do cartão base, conforme ilustrado na exibição específica do usuário de atualização automática. Você pode habilitar a atualização automática no cartão base da seguinte maneira:

• A primeira opção permite a atualização de exibição específica do usuário com o SDK. O cartão base pode ser enviado como uma resposta de comando ou uma resposta de ação cartão. Você pode habilitar a atualização de exibição específica do usuário em handleCommandReceived um manipulador de comandos ou no manipulador de ações cartão em handleActionInvoked que o cartão base é retornado. Você pode usar refresh(refreshVerb, userIds, data) o método da @microsoft/adaptivecards-tools biblioteca para injetar uma seção de atualização no cartão base. Para definir a seção de atualização, verifique se você fornece as seguintes propriedades:

  1. userIds: um conjunto de MRIs de usuário para aqueles que podem disparar a atualização automática. Para obter mais informações sobre como adicionar na lista na userIds seção atualização do Cartão Adaptável, consulte buscar a lista ou o perfil do usuário.
  2. verb: uma cadeia de caracteres para identificar a ação de atualização.
  3. data: dados opcionais a serem associados à ação de atualização.

  No exemplo a seguir, um cartão base retorna como resposta de comando que pode atualizar automaticamente para um usuário específico, como o remetente de comando:

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

• A segunda opção permite que a exibição específica do usuário atualize seu Cartão Adaptável. Esta é uma ação de atualização de exemplo definida em baseCard.json:

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

  Você precisa substituir ${userID} pela mri do usuário no código, enquanto renderiza seu conteúdo cartão.

2. Adicionar cartão adaptável específico do usuário

Você precisa projetar o Cartão Adaptável específico do usuário para atualizar um cartão de resposta específico, como responseCard.json para userA mostrado no diagrama para comportamento de atualização. Para começar, você pode criar um responseCard.json com o seguinte conteúdo e salvá-lo na bot/src/adaptiveCards pasta:

-
{
  "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. Adicione cartão manipulador de ações para atualizar exibições

Você pode adicionar o manipulador que implementa TeamsFxAdaptiveCardActionHandler para processar a atividade de invocação de atualização que é disparada automaticamente no 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. Registrar o manipulador de ações

Você pode registrar o manipulador de ações de bot/src/internal/initialize.js(ts) atualização com o seguinte código:

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

Acesso Microsoft Graph

Se você estiver respondendo a um comando que precisa acessar dados do Microsoft Graph de um usuário do Teams já conectado, poderá fazê-lo por SSO (logon único) com o token de usuário do Teams. Leia mais sobre como o Teams Toolkit pode ajudá-lo a adicionar logon único ao aplicativo teams.

Conectar-se às APIs existentes

Muitas vezes você precisa se conectar a APIs existentes para recuperar dados para enviar ao Teams. O Teams Toolkit facilita a configuração e o gerenciamento da autenticação para APIs existentes. Para obter mais informações, confira como integrar APIs de terceiros existentes.

Perguntas frequentes

Como estender o bot de fluxo de trabalho com notificações?

As notificações adicionam a capacidade em seu aplicativo de enviar Cartões Adaptáveis em resposta a eventos externos. Por exemplo, quando uma mensagem é postada em um Hub de Eventos, seu aplicativo pode responder com um Cartão Adaptável conforme necessário. Como estender o bot de fluxo de trabalho com notificações, confira personalizar notificações.

Como estender o bot de fluxo de trabalho com comando e resposta?

O bot de fluxo de trabalho padrão vem com comando e resposta. Para obter mais informações para estender o bot de fluxo de trabalho com comando e resposta, consulte adicionar comando e resposta.

Guias passo a passo

Siga o guia passo a passo para criar o bot de fluxo de trabalho do Teams.

Confira também

• Criar bots para o Teams
• Crie seu primeiro aplicativo de bot usando JavaScript
• Compilar um bot de notificação com JavaScript
• Cartões Adaptáveis
• Noções básicas sobre conversas