Gerir tarefas com tecnologia de aplicação no Planner para experiências de tarefas personalizadas

Artigo
12/18/2024
Aplica-se a:

Microsoft Teams

Nota

Esta funcionalidade está atualmente em pré-visualização pública.

Visão geral

A funcionalidade de tarefas com tecnologia de aplicação oferece à sua organização mais controlo sobre o que os utilizadores veem quando abrem as suas tarefas na aplicação Planner no Microsoft Teams. Em vez de mostrar apenas o conjunto padrão de campos de tarefas, pode fornecer aos utilizadores uma experiência adaptada à tarefa em questão. Essa experiência pode ser um conjunto de campos específico do fluxo de trabalho ou orientação passo a passo para orientar o utilizador através de um fluxo de trabalho do início ao fim. Para tal, integre uma aplicação do Teams com a tarefa e crie estas tarefas programaticamente.

Digamos que, por exemplo, os utilizadores na sua organização utilizam uma aplicação do Teams para controlar e concluir as inspeções. Pode integrar esta aplicação de inspeções em tarefas para que seja criada uma tarefa de Planner para cada inspeção controlada no sistema.

Quando um utilizador abre uma destas tarefas a partir da aplicação Planner no Teams, vê um ecrã simplificado com um botão para aceder diretamente à experiência de inspeção com tecnologia da sua aplicação de inspeções.
Quando concluírem a tarefa e fecharem a experiência de inspeções, estão de volta ao Planner onde começaram.

Os utilizadores obtêm a experiência personalizada que uma aplicação do Teams fornece diretamente a partir das tarefas atribuídas. Não precisam de navegar para uma aplicação diferente para trabalhar ou perder o contexto de onde estavam ao trabalhar com as suas tarefas.

Além destes benefícios quando os utilizadores contiverem tarefas, a funcionalidade de tarefas com tecnologia de aplicação permite às organizações refletir os processos de linha de negócio e fluxos de trabalho necessários como tarefas, para que os funcionários possam ver todo o trabalho pelo qual são responsáveis a partir de um único local.

Esta experiência é suportada na aplicação Planner na Web, no ambiente de trabalho e no teams para dispositivos móveis. Pode fornecer experiências de tarefa personalizadas aos seus utilizadores com qualquer aplicação do Teams que cumpra os seguintes requisitos.

Requisitos

As tarefas com tecnologia de aplicação são uma funcionalidade de extensibilidade que se baseia na criação programática e gestão de tarefas. Os requisitos para utilizar esta funcionalidade são os seguintes.

Cada tarefa com tecnologia de aplicação aponta para uma experiência numa aplicação do Teams de destino, que requer que forneça um URL de referência para essa experiência. Recomendamos que aponte este URL de referência para o item ou ecrã específico em que o utilizador deve trabalhar. Este URL de referência tem de ser adicionado à tarefa de uma forma específica. Para saber mais, veja a secção Passo 1: Configurar o URL de referência deste artigo.
As tarefas têm de ser criadas e atualizadas com a API de cenários empresariais no Microsoft Graph.
Os utilizadores que precisam de trabalhar com a tarefa têm de ter acesso à aplicação de destino no Teams, conforme regido pelas políticas de aplicações que definiu no centro de administração do Teams. Para saber mais, veja Descrição geral da gestão e governação de aplicações no centro de administração do Teams.
A aplicação teams de destino é responsável pela gestão do ciclo de vida da tarefa, que inclui as seguintes ações:
- Crie a tarefa. Veja Criar businessScenarioTask.
- Atribua a tarefa. Consulte Atualizar businessScenarioTask.
- Atualize a tarefa, se as propriedades forem alteradas. Consulte Atualizar businessScenarioTask.
- Marque a tarefa como Concluída quando todos os passos estiverem concluídos. Consulte Atualizar businessScenarioTask.
- Elimine a tarefa. Veja Eliminar businessScenarioTask.

Esta funcionalidade permite que a aplicação Teams de destino regule o ciclo de vida da tarefa, uma vez que alguns fluxos de trabalho podem não ter fluxos deterministas. Como resultado, a aplicação Planner não sabe se todos os passos necessários estão concluídos. Por exemplo, uma conclusão durante uma inspeção pode resultar na inclusão de mais vários passos na inspeção. Da mesma forma, os utilizadores são impedidos de atualizar campos de tarefas ou de marcar a tarefa como Concluída. Estas ações podem fazer com que os utilizadores façam alterações que entrem em conflito com o que é refletido na sua aplicação teams de destino.

Criar uma tarefa com tecnologia de aplicação

Esta secção aborda como utilizar a API Create businessScenarioTask para criar uma tarefa com tecnologia de aplicação.

Utilize o seguinte pedido HTTP POST. Eis o aspeto do pedido, com marcadores de posição para as propriedades que 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 secções seguintes explicam como formar o pedido mais detalhadamente.

Como definir as propriedades no pedido

Um tipo específico de anexo diferencia uma tarefa com tecnologia de aplicação de uma tarefa padrão. O anexo tem de ser do tipo TeamsHostedApp e tem de conter uma ligação especialmente formatada (URL de referência) para a experiência de destino na aplicação Teams. Isto significa para Planner que a tarefa é uma tarefa com tecnologia de aplicação.

Tenha em atenção que a API se refere a estes anexos como referências.

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

Passo 1: Configurar o URL de referência

O URL de referência utiliza um formato específico. Siga estes passos para construir e, em seguida, codificar o URL.

Passo 1a: Construir o URL

O URL de referência para a experiência de destino tem de utilizar a sintaxe da ligação 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 o URL de referência, especifique os seguintes parâmetros.

Parâmetro	Descrição
`Teams-app-Id`	O ID da aplicação Teams que está a integrar na tarefa.
`URL-to-destination-experience`	O URL que aponta para a experiência de destino na sua aplicação teams de destino que pretende que os utilizadores vejam quando abrem a tarefa. Por motivos de segurança, o URL tem de apontar para um domínio válido associado à aplicação Teams, que é representado pelo ID da aplicação que fornecer.
`page-title`	O título que deve aparecer na parte superior do ecrã quando o utilizador é mostrado o URL para a experiência de destino.

Eis um exemplo de um 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 é o ID da aplicação do YouTube no Teams (com.microsoft.teamspace.tab.youtube). Tenha em atenção que a maioria dos IDs de aplicações do Teams são alfanuméricos e podem ter um aspeto diferente.
URL-to-destination-experience aponta para a experiência na aplicação Teams de destino (https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY).
page-title é o nome do título do ecrã (Security talk) ao carregar o URL.

Se a aplicação YouTube no Teams estiver disponível para si, pode enviar este URL para si próprio e confirmá-lo.

Passo 1b: Codificar o URL

Tem de codificar o URL de referência antes de poder utilizá-lo no anexo. A codificação percentagem garante que a ligação está num formato compatível para utilização programática.

Siga estes passos para codificar o URL de referência. Utilizamos o URL de referência de exemplo descrito anteriormente para demonstrar como codificar o URL.

Percentagem de codificação da parte do URL que vem depois de 0?context=. Não codificar https:// ou = (o símbolo de igual) ou qualquer um dos carateres no meio.

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

Sugestão

Este é o último passo em que a ligação pode ser facilmente validada no chat do Teams. Depois de concluir este passo, pode testar o URL ao enviá-lo para si próprio numa conversa do Teams. A ligação deve ser aberta no Teams para ambiente de trabalho, Web ou dispositivos móveis para qualquer utilizador que tenha acesso à aplicação de destino no Teams.
Substitua todos os. carateres no URL de referência por %2E. Tem de o fazer em todos os carateres no URL de referência, do início ao fim. Se ignorar este passo, o URL de referência poderá não funcionar.

O URL seguinte está pronto para utilização programática.

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 o URL apontar para uma Aplicação Power, certifique-se de que inclui o parâmetro para fazer com que o &source=teamstab início de sessão único (SSO) funcione para o Power Apps e o &skipMobileRedirect=1 parâmetro para ignorar o ecrã que pede aos utilizadores para abrirem o leitor autónomo do Power App.

Passo 2: definir o anexo

Para definir o anexo, especifique as seguintes propriedades no "references" corpo do pedido.

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

Propriedade	Descrição
`reference-URL`	O URL para a experiência de destino, na sintaxe da ligação Modal do Stageview. Para obter detalhes sobre como construir e codificar o URL, veja a secção Passo 1: Configurar o URL de referência deste artigo.
`alias`	O nome da sua aplicação Teams. Quando um utilizador abre a tarefa, vê uma mensagem a indicar "Concluir esta tarefa com <alias> e um botão Iniciar tarefa para aceder à experiência de destino.
`previewPriority`	Deixe como `!`.
`type`	Defina como `TeamsHostedApp`. Isto significa para Planner que a tarefa é uma tarefa com tecnologia de aplicação.

Exemplo

Este exemplo mostra como criar uma tarefa com tecnologia de aplicação chamada "Rever apresentação de práticas de segurança" e atribuí-la a um utilizador com o nome Adele Vance (ID de utilizador 44ee44ee-ff55-aa66-bb77-88cc88cc88cc). Este pedido utiliza o URL de referência de exemplo da secção Passo 1: Configurar o 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"
             }
        }
    }
}

Nota

Este URL de referência de exemplo foi escolhido como uma forma fácil de testar a experiência de tarefas com tecnologia de aplicação com uma aplicação disponível nos ambientes de muitas organizações. Tenha em atenção que, com este URL de referência de exemplo, os utilizadores não conseguirão concluir a tarefa. Isto acontece porque a aplicação do YouTube não está integrada com tarefas com tecnologia de aplicação e não faz uma chamada à API para marcar a tarefa como concluída após o vídeo ser reproduzido.

O aspeto desta funcionalidade na aplicação Planner

Eis o que o utilizador vê quando abre a tarefa na aplicação Planner no Teams. Selecionar o botão Iniciar tarefa leva o utilizador à experiência de destino na aplicação Teams. Neste exemplo, a experiência de destino é um vídeo de práticas de segurança na aplicação YouTube no Teams.

Para saber mais sobre a experiência do utilizador, consulte Trabalhar com tarefas com tecnologia de aplicação na aplicação Planner no Teams.

Compartilhar via

Gerir tarefas com tecnologia de aplicação no Planner para experiências de tarefas personalizadas

Visão geral

Requisitos

Criar uma tarefa com tecnologia de aplicação

Como definir as propriedades no pedido

Passo 1: Configurar o URL de referência

Passo 1a: Construir o URL

Passo 1b: Codificar o URL

Passo 2: definir o anexo

Exemplo

O aspeto desta funcionalidade na aplicação Planner

Comentários

Recursos adicionais

Compartilhar via

Gerir tarefas com tecnologia de aplicação no Planner para experiências de tarefas personalizadas

Visão geral

Requisitos

Criar uma tarefa com tecnologia de aplicação

Como definir as propriedades no pedido

Passo 1: Configurar o URL de referência

Passo 1a: Construir o URL

Passo 1b: Codificar o URL

Passo 2: definir o anexo

Exemplo

O aspeto desta funcionalidade na aplicação Planner

Artigos relacionados

Comentários

Recursos adicionais