Compartir a través de

Administrar tareas con tecnología de aplicación en Planner para experiencias de tareas personalizadas

  • Artículo
  • Se aplica a:
    Microsoft Teams

Nota

Esta característica se encuentra actualmente en versión preliminar pública.

Información general

La característica de tareas con tecnología de aplicación ofrece a su organización un mayor control sobre lo que ven los usuarios al abrir sus tareas en la aplicación Planner dentro de Microsoft Teams. En lugar de mostrar solo el conjunto estándar de campos de tareas, puede proporcionar a los usuarios una experiencia adaptada a la tarea que esté realizando. Esa experiencia puede ser un conjunto específico de campos de flujo de trabajo o instrucciones paso a paso para guiar al usuario por un flujo de trabajo de principio a fin. Para ello, integre una aplicación de Teams con la tarea y cree estas tareas mediante programación.

Por ejemplo, los usuarios de su organización usan una aplicación de Teams para realizar un seguimiento y completar las inspecciones. Puede integrar esta aplicación de inspecciones con tareas para que se cree una tarea de Planner para cada inspección rastreada en el sistema.

  • Cuando un usuario abre una de estas tareas desde la aplicación Planner en Teams, ve una pantalla simplificada con un botón para ir directamente a la experiencia de inspección con tecnología de la aplicación de inspecciones.
  • Cuando completen la tarea y cierren la experiencia de inspecciones, volverán a Planner donde empezaron.

Los usuarios obtienen la experiencia adaptada que una aplicación de Teams proporciona directamente desde dentro de sus tareas asignadas. No tienen que navegar a una aplicación diferente para realizar el trabajo o perder el contexto de dónde estaban al trabajar con sus tareas.

Además de estas ventajas cuando los usuarios completan tareas, la característica de tareas con tecnología de aplicación permite a las organizaciones reflejar los procesos y flujos de trabajo de línea de negocio necesarios como tareas, para que los empleados puedan ver todo el trabajo del que son responsables desde un único lugar.

Esta experiencia es compatible con la aplicación Planner en la web, el escritorio y los dispositivos móviles de Teams. Puede proporcionar experiencias de tareas adaptadas a los usuarios con cualquier aplicación de Teams que cumpla los siguientes requisitos.

Requirements

Las tareas con tecnología de aplicación son una característica de extensibilidad que se basa en la creación y administración programática de tareas. Los requisitos para usar esta característica son los siguientes.

Esta característica permite que su aplicación de Teams de destino gobierne el ciclo de vida de la tarea porque es posible que algunos flujos de trabajo no tengan flujos deterministas. Como resultado, la aplicación Planner no sabe si se han completado todos los pasos necesarios. Por ejemplo, un hallazgo durante una inspección podría dar lugar a la inclusión de varios pasos más en la inspección. De forma similar, no se permite a los usuarios actualizar los campos de la tarea o marcar la tarea como completada. Estas acciones pueden provocar que los usuarios realicen cambios que entren en conflicto con lo que se refleja en la aplicación de Teams de destino.

Crear una tarea con tecnología de aplicación

Esta sección trata sobre cómo usar la API Create businessScenarioTask para crear una tarea con tecnología de aplicación.

Use la siguiente solicitud HTTP POST. Este es el aspecto de la solicitud, con marcadores de posición para las propiedades que especifique.

Solicitud

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

En las siguientes secciones se explica cómo formar la solicitud con más detalle.

Cómo definir las propiedades de la solicitud

Un tipo específico de datos adjuntos diferencia una tarea con tecnología de aplicación de una tarea estándar. Los datos adjuntos deben ser de tipo TeamsHostedApp y deben contener un vínculo con formato especial (dirección URL de referencia) a la experiencia de destino en la aplicación Teams. Esto significa Planner que la tarea es una tarea con tecnología de aplicación.

Tenga en cuenta que la API hace referencia a estos datos adjuntos como referencias.

En primer lugar, configure la dirección URL de referencia para que apunte a la experiencia de destino. Después, especifique la dirección URL de referencia junto con otras propiedades necesarias para los datos adjuntos en el cuerpo de la solicitud.

Paso 1: Configurar la dirección URL de referencia

La dirección URL de referencia usa un formato específico. Siga estos pasos para construir y codificar la dirección URL.

Paso 1a: Construir la dirección URL

La dirección URL de referencia a la experiencia de destino debe usar la sintaxis del vínculo Modal de Stageview en el siguiente formato:

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

Para construir la dirección URL de referencia, especifique los siguientes parámetros.

Parámetro Descripción
Teams-app-Id El id. de aplicación de la aplicación de Teams que está integrando con la tarea.
URL-to-destination-experience La dirección URL que apunta a la experiencia de destino en la aplicación de Teams de destino que desea que los usuarios vean al abrir la tarea. Por motivos de seguridad, la dirección URL debe apuntar a un dominio válido asociado a la aplicación de Teams, que se representa con el id. de aplicación que proporcione.
page-title El título que debería aparecer en la parte superior de la pantalla cuando se muestre al usuario la dirección URL de la experiencia de destino.

Este es un ejemplo de una dirección URL de referencia antes de la codificación:

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

En este ejemplo:

  • Teams-app-Id es el id. de aplicación de la aplicación de YouTube en Teams (com.microsoft.teamspace.tab.youtube). Tenga en cuenta que la mayoría de los identificadores de aplicación de Teams son alfanuméricos y pueden tener un aspecto diferente.
  • URL-to-destination-experience apunta a la experiencia en la aplicación de teams de destino (https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY).
  • page-title es el nombre del título de la pantalla (Security talk) al cargar la dirección URL.

Si la aplicación de YouTube en Teams está disponible, puede enviarse esta dirección URL y confirmar que se abre.

Paso 1b: Codificar la dirección URL

Debe codificar la dirección URL de referencia para poder usarla en los datos adjuntos. La codificación percentil garantiza que el vínculo tenga un formato compatible para su uso mediante programación.

Siga estos pasos para codificar la dirección URL de referencia. Usamos la dirección URL de referencia de ejemplo descrita anteriormente para demostrar cómo codificar la dirección URL.

  1. Percent codifica la parte de la dirección URL que viene después 0?context=de . No codificas https:// ni = (el símbolo igual) ni ninguno de los caracteres intermedios.

    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

    Propina

    Este es el último paso en el que el vínculo se puede validar fácilmente en el chat de Teams. Después de completar este paso, puede probar la dirección URL enviándosela a sí mismo en un chat de Teams. El vínculo debería abrirse en la versión de escritorio, web o móvil de Teams para cualquier usuario que tenga acceso a la aplicación de destino en Teams.

  2. Reemplace todos los. caracteres de la dirección URL de referencia por %2E. Debe hacerlo en todos los caracteres de la dirección URL de referencia, de principio a fin. Si omite este paso, es posible que la dirección URL de referencia no funcione.

    La siguiente dirección URL está lista para usarse mediante programación.

    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

    Si la dirección URL apunta a una Power App, asegúrese de que incluye el parámetro para hacer que el &source=teamstab inicio de sesión único (SSO) funcione para Power Apps y el &skipMobileRedirect=1 parámetro para omitir la pantalla que pide a los usuarios que abran el reproductor independiente de Power App.

Paso 2: Definir los datos adjuntos

Para definir los datos adjuntos, especifique las siguientes propiedades en "references" el cuerpo de la solicitud.

        "references": { 
            "{reference-URL}": { 
            "@odata.type": "microsoft.graph.plannerExternalReference", 
            "alias": "{destination app name}", 
            "previewPriority": " !", 
            "type": "TeamsHostedApp" 
         } 
       }
Propiedad Descripción
reference-URL La dirección URL a la experiencia de destino, en La sintaxis de vínculo modal de Vista previa de fase. Para obtener más información sobre cómo crear y codificar la dirección URL, vea el Paso 1: Configurar la dirección URL de referencia de este artículo.
alias El nombre de la aplicación de Teams. Cuando un usuario abre la tarea, ve un mensaje que dice "Completar esta tarea en <alias> y un botón Iniciar tarea para ir a la experiencia de destino.
previewPriority Abandonar como !.
type Establecer en TeamsHostedApp. Esto es lo que significa Planner que la tarea es una tarea con tecnología de aplicación.

Ejemplo

En este ejemplo se muestra cómo crear una tarea con tecnología de aplicación denominada "Revisar la presentación de procedimientos de seguridad" y asignarla a un usuario llamado Adele Vance (id. de usuario 44ee44ee-ff55-aa66-bb77-88cc88cc88cc). Esta solicitud usa la dirección URL de referencia de ejemplo del paso 1: configurar la sección url de referencia de este artículo.

Solicitud

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

Esta dirección URL de referencia de ejemplo se ha elegido como una forma sencilla de probar la experiencia de tareas con tecnología de aplicación mediante una aplicación que está disponible en los entornos de muchas organizaciones. Tenga en cuenta que, con esta dirección URL de referencia de ejemplo, los usuarios no podrán completar la tarea. Esto se debe a que la aplicación de YouTube no está integrada con tareas con tecnología de la aplicación y no realiza una llamada a la API para marcar la tarea como completada después de reproducir el vídeo.

Qué aspecto tiene en la aplicación Planner

Esto es lo que ve el usuario al abrir la tarea en la aplicación Planner en Teams. Al seleccionar el botón Iniciar tarea , el usuario se lleva a la experiencia de destino en la aplicación Teams. En este ejemplo, la experiencia de destino es un vídeo de prácticas de seguridad en la aplicación de YouTube en Teams.

Captura de pantalla de un ejemplo de una tarea con tecnología de aplicación en Mis tareas en la aplicación Planner en Teams.

Para obtener más información sobre la experiencia del usuario, consulte Trabajar con tareas con tecnología de aplicación en la aplicación Planner en Teams.