Gerenciar tarefas habilitadas por aplicativos no Planner para obter experiências de tarefas personalizadas

Visão geral

O recurso de tarefas do aplicativo oferece à sua organização mais controle sobre o que os usuários veem quando abrem suas tarefas no aplicativo Planner do Microsoft Teams. Em vez de mostrar apenas o conjunto padrão de campos de tarefa, você pode fornecer aos usuários uma experiência personalizada para a tarefa em questão. Essa experiência pode ser um conjunto de campos específico do fluxo de trabalho ou uma orientação passo a passo para orientar o usuário em um fluxo de trabalho do início ao fim. Para conseguir isso, integre um aplicativo do Teams à tarefa e crie essas tarefas programaticamente.

Digamos, por exemplo, que os usuários em sua organização usem um aplicativo do Teams para rastrear e concluir inspeções. Você pode integrar este aplicativo de inspeções com tarefas para que uma tarefa do Planner seja criada para cada inspeção rastreada no sistema.

• Quando um usuário abre uma dessas tarefas do aplicativo Planner no Teams, ele vê uma tela simplificada com um botão para ir diretamente para a experiência de inspeção da plataforma do seu aplicativo de inspeções.
• Quando concluem a tarefa e fecham a experiência de inspeções, eles estão de volta ao Planner de onde começaram.

Os usuários obtêm a experiência personalizada que um aplicativo do Teams fornece diretamente de suas tarefas atribuídas. Eles não precisam navegar para um aplicativo diferente para realizar o trabalho ou perder o contexto de onde estavam ao trabalhar com suas tarefas.

Além desses benefícios quando os usuários concluem tarefas, o recurso de tarefas baseadas em aplicativos permite que as organizações reflitam os processos e fluxos de trabalho obrigatórios da linha de negócios como tarefas, para que os funcionários possam ver todo o trabalho pelo qual são responsáveis em um único lugar.

Essa experiência é compatível com o aplicativo Planner no Teams na Web, na área de trabalho e em dispositivos móveis. Você pode fornecer experiências de tarefas personalizadas para seus usuários com qualquer aplicativo do Teams que atenda aos seguintes requisitos.

Requisitos

Tarefas habilitadas para aplicativos são um recurso de extensibilidade que depende da criação programática e do gerenciamento de tarefas. Os requisitos para usar esse recurso são os seguintes.

• Cada tarefa baseada em aplicativo aponta para uma experiência em um aplicativo do Teams de destino, o que exige que você forneça uma URL de referência para essa experiência. Recomendamos que você aponte essa URL de referência para o item ou tela específico em que o usuário deve estar trabalhando. Essa URL de referência deve ser adicionada à tarefa de uma maneira específica. Para saber mais, consulte a seção Etapa 1: configurar a URL de referência deste artigo.

• As tarefas devem ser criadas e atualizadas usando a API de cenários de negócios no Microsoft Graph.

• Os usuários que precisam trabalhar com a tarefa devem ter acesso ao aplicativo de destino no Teams, conforme regido pelas políticas de aplicativo definidas no Centro de administração do Teams. Para saber mais, confira Visão geral do gerenciamento e governança de aplicativos no Centro de administração do Teams.

• O aplicativo Teams de destino é responsável por gerenciar o ciclo de vida da tarefa, que inclui as seguintes ações:

  • Crie a tarefa. Consulte Criar businessScenarioTask.
  • Atribua a tarefa. Consulte Atualizar businessScenarioTask.
  • Atualize a tarefa, caso as propriedades sejam alteradas. Consulte Atualizar businessScenarioTask.
  • Marque a tarefa como Concluída quando todas as etapas forem concluídas. Consulte Atualizar businessScenarioTask.
  • Exclua a tarefa. Consulte Excluir businessScenarioTask.

Esse recurso permite que seu aplicativo Teams de destino controle o ciclo de vida da tarefa porque alguns fluxos de trabalho podem não ter fluxos determinísticos. Como resultado, o aplicativo Planner não sabe se todas as etapas necessárias foram concluídas. Por exemplo, uma constatação durante uma inspeção pode resultar na inclusão de várias outras etapas na inspeção. Da mesma forma, os usuários são impedidos de atualizar os campos da tarefa ou marcar a tarefa como Concluída. Essas ações podem fazer com que os usuários façam alterações em conflito com o que é refletido no aplicativo Teams de destino.

Criar uma tarefa habilitada pelo aplicativo

Esta seção aborda como usar a API Create businessScenarioTask para criar uma tarefa habilitada pelo aplicativo.

Use a seguinte solicitação HTTP POST. Veja a aparência da solicitação, com espaços reservados para as propriedades que você especificar.

Solicitação

POST https://graph.microsoft.com/beta/solutions/businessScenarios/{your-business-scenario-ID}/planner/tasks 

{ 
"title": "{Task title}", 
    "target": { 
        "@odata.type": "#microsoft.graph.businessScenarioGroupTarget", 
        "taskTargetKind": "group", 
        "groupId": "{group ID of the team where you want to create the task}" 
    }, 
    "businessScenarioProperties": { 
        "externalObjectId": "{any unique ID, for example, the ID of the object in your destination app}", 
        "externalBucketId": "{any bucket ID from planConfiguration of your business scenario}" 
    }, 
    "assignments": { 
        "{user ID of user you want to assign the task to}": { 
            "@odata.type": "#microsoft.graph.plannerAssignment", 
            "orderHint": " !" 
        } 
    }, 
    "details": { 
        "references": { 
            "{reference URL}": { 
                "@odata.type": "microsoft.graph.plannerExternalReference", 
                "alias": "{destination app name}", 
                "previewPriority": " !", 
                "type": "TeamsHostedApp" 
            } 
       } 
    } 
} 

As seções a seguir explicam como formar a solicitação com mais detalhes.

Como definir as propriedades na solicitação

Um tipo específico de anexo diferencia uma tarefa baseada em aplicativo de uma tarefa padrão. O anexo deve ser do tipo TeamsHostedApp e deve conter um link especialmente formatado (URL de referência) para a experiência de destino no aplicativo Teams. Isso significa para o Planner que a tarefa é uma tarefa alimentada por aplicativo.

Lembre-se de que a API se refere a esses anexos como referências.

Primeiro, configure a URL de referência para apontar para a experiência de destino. Em seguida, especifique a URL de referência juntamente com outras propriedades necessárias para o anexo no corpo da solicitação.

Etapa 1: Configurar a URL de referência

A URL de referência usa um formato específico. Siga estas etapas para construir e codificar a URL.

Etapa 1a: construir a URL

A URL de referência para a experiência de destino deve usar a sintaxe de link modal do Stageview no seguinte formato:

https://teams.microsoft.com/l/stage/{Teams-app-Id}/0?context={"contentUrl":"URL-to-destination-experience"},"name":"{page-title}","openMode":"modal"}

Para construir a URL de referência, especifique os seguintes parâmetros.

Veja um exemplo de uma URL de referência antes da codificação:

https://teams.microsoft.com/l/stage/com.microsoft.teamspace.tab.youtube/0?context={"contentUrl":"https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY","name":"Security%20talk","openMode":"modal"}

Neste exemplo:

• Teams-app-Id é a ID do aplicativo do YouTube no Teams (com.microsoft.teamspace.tab.youtube). Lembre-se de que a maioria das IDs de aplicativo do Teams são alfanuméricas e podem parecer diferentes.
• URL-to-destination-experience aponta para a experiência no aplicativo do Teams de destino (https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY).
• page-title é o nome do título da tela (Security talk) ao carregar a URL.

Se o aplicativo do YouTube no Teams estiver disponível para você, envie essa URL para si mesmo e confirme se ele é aberto.

Etapa 1b: Codificar a URL

Você precisa codificar a URL de referência antes de poder usá-la no anexo. A codificação percentual garante que o link esteja em um formato compatível para uso programático.

Siga estas etapas para codificar a URL de referência. Usamos o exemplo de URL de referência descrito anteriormente para demonstrar como codificar o URL.

1. Codificar por porcentagem a parte da URL que vem depois 0?context=de . Não codifique https:// ou = (o símbolo de igual) ou qualquer um dos caracteres intermediários.

   https://teams.microsoft.com/l/stage/com.microsoft.teamspace.tab.youtube/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Ftabs.teams.microsoft.com%2FyoutubeContentStage%3FvideoId%3DHBGmSy1iVmY%22%2C%22name%22%3A%22Security%2520talk%22%2C%22openMode%22%3A%22modal%22%7D

   Dica

   Esta é a última etapa em que o link pode ser facilmente validado no chat do Teams. Depois de concluir esta etapa, você poderá testar a URL enviando-a para si mesmo em um chat do Teams. O link deve ser aberto na área de trabalho, na Web ou no dispositivo móvel do Teams para qualquer usuário que tenha acesso ao aplicativo de destino no Teams.

2. Substituir todos os. caracteres na URL de referência por %2E. Você deve fazer isso em todos os caracteres na URL de referência, do início ao fim. Se você ignorar esta etapa, a URL de referência pode não funcionar.

   A URL a seguir está pronta para uso programático.

   https://teams%2Emicrosoft%2Ecom/l/stage/com%2Emicrosoft%2Eteamspace%2Etab%2Eyoutube/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Ftabs%2Eteams%2Emicrosoft%2Ecom%2FyoutubeContentStage%3FvideoId%3DHBGmSy1iVmY%22%2C%22name%22%3A%22Security%2520talk%22%2C%22openMode%22%3A%22modal%22%7D

   Nota

   Se a URL apontar para um Power App, verifique se ela inclui o parâmetro para fazer o &source=teamstab logon único (SSO) funcionar para o Power Apps e o &skipMobileRedirect=1 parâmetro para ignorar a tela que solicita que os usuários abram o player autônomo do Power App.

Etapa 2: Definir o anexo

Para definir o anexo, especifique as seguintes propriedades no "references" corpo da solicitação.

        "references": { 
            "{reference-URL}": { 
            "@odata.type": "microsoft.graph.plannerExternalReference", 
            "alias": "{destination app name}", 
            "previewPriority": " !", 
            "type": "TeamsHostedApp" 
         } 
       } 

Exemplo

Este exemplo mostra como criar uma tarefa baseada em aplicativo chamada "Revisar apresentação de práticas de segurança" e atribuí-la a um usuário chamado Adele Vance (ID de usuário 44ee44ee-ff55-aa66-bb77-88cc88cc88cc). Essa solicitação usa o exemplo de URL de referência da seção Etapa 1: Configure a URL de referência deste artigo.

Solicitação

POST https://graph.microsoft.com/beta/solutions/businessScenarios/ccd5aa8aebd048bd839a4fa5b7420631/planner/tasks

{
"title": "Review security practices presentation",
    "target": {
        "@odata.type": "#microsoft.graph.businessScenarioGroupTarget",
        "taskTargetKind": "group",
        "groupId": "769bbf41-70b7-4ea6-a044-a7037358883e"
    },
    "businessScenarioProperties": {
        "externalObjectId": "SP-202418",
        "externalBucketId": "Security practices"
    },
    "assignments": {
        "44ee44ee-ff55-aa66-bb77-88cc88cc88cc": {
            "@odata.type": "#microsoft.graph.plannerAssignment",
            "orderHint": " !"
        }
    },
    "details": {
        "references": {
            "https://teams%2Emicrosoft%2Ecom/l/stage/com%2Emicrosoft%2Eteamspace%2Etab%2Eyoutube/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Ftabs%2Eteams%2Emicrosoft%2Ecom%2FyoutubeContentStage%3FvideoId%3DHBGmSy1iVmY%22%2C%22name%22%3A%22Security%2520talk%22%2C%22openMode%22%3A%22modal%22%7D": {
                "@odata.type": "microsoft.graph.plannerExternalReference",
                "alias": "Security practices presentation",
                "previewPriority": " !",
                "type": "TeamsHostedApp"
             }
        }
    }
}

Como isso se parece no aplicativo Planner

Aqui está o que o usuário vê quando abre a tarefa no aplicativo Planner no Teams. Selecionar o botão Iniciar tarefa leva o usuário para a experiência de destino no aplicativo Teams. Neste exemplo, a experiência de destino é um vídeo de práticas de segurança no aplicativo YouTube no Teams.

Para saber mais sobre a experiência do usuário, confira Trabalhar com tarefas executadas no aplicativo Planner no Teams.

Artigos relacionados

• Usar a API de cenários de negócios no Microsoft Graph para integração com o Planner
• Gerenciar o aplicativo Planner para sua organização no Microsoft Teams