Condividi tramite

Gestire le attività basate su app in Planner per esperienze attività personalizzate

  • Articolo
  • Si applica a:
    Microsoft Teams

Nota

Questa funzionalità è attualmente in anteprima pubblica.

Panoramica

La funzionalità delle attività basate sull'app offre all'organizzazione un maggior controllo su ciò che gli utenti vedono quando aprono le attività nell'app Planner all'interno di Microsoft Teams. Invece di visualizzare solo il set standard di campi delle attività, è possibile offrire agli utenti un'esperienza personalizzata per l'attività in corso. Questa esperienza potrebbe essere un set di campi specifico del flusso di lavoro o indicazioni dettagliate per accompagnare l'utente in un flusso di lavoro dall'inizio alla fine.That experience might be a workflow-specific set of fields or step-by-step guidance to walk the user through a workflow from beginning to end. A questo scopo, è necessario integrare un'app Teams con l'attività e creare queste attività a livello di programmazione.

Supponiamo, ad esempio, che gli utenti dell'organizzazione utilizzino un'app Teams per tenere traccia e completare le ispezioni. È possibile integrare questa app di ispezione con le attività in modo che venga creata una Planner attività per ogni ispezione monitorata nel sistema.

  • Quando un utente apre una di queste attività dall'app Planner in Teams, vede una schermata semplificata con un pulsante per passare direttamente all'esperienza di ispezione basata sull'app di ispezione.
  • Quando completano l'attività e chiudono l'esperienza di ispezione, sono di nuovo in Planner da dove hanno iniziato.

Gli utenti ottengono l'esperienza personalizzata fornita da un'app Teams direttamente dall'interno delle attività assegnate. Non devono passare a un'altra app per completare il lavoro o perdere il contesto in cui si trovano quando hanno lavorato con le loro attività.

Oltre a questi vantaggi quando gli utenti completano attività, la funzionalità delle attività basata sull'app consente alle organizzazioni di riflettere i processi line-of-business richiesti e i flussi di lavoro come attività, in modo che i dipendenti possano vedere tutto il lavoro per cui sono responsabili da un'unica posizione.

Questa esperienza è supportata nell'app Planner su Web, desktop e dispositivi mobili di Teams. È possibile offrire esperienze attività personalizzate per gli utenti con qualsiasi app di Teams che soddisfi i requisiti seguenti.

Requisiti

Le attività basate su app sono una funzionalità di estendibilità che si basa sulla creazione e la gestione programmatica delle attività. I requisiti per usare questa caratteristica sono i seguenti.

Questa funzionalità consente all'app Teams di destinazione di controllare il ciclo di vita delle attività perché alcuni flussi di lavoro potrebbero non avere flussi deterministici. Di conseguenza, l'app Planner non sa se tutti i passaggi necessari sono stati completati. Ad esempio, un ritrovamento durante un'ispezione potrebbe comportare l'inserimento di più passaggi nell'ispezione. Analogamente, agli utenti non è consentito aggiornare i campi delle attività o contrassegnare l'attività come completata. Queste azioni potrebbero portare gli utenti ad apportare modifiche in conflitto con ciò che viene riflesso nell'app Teams di destinazione.

Creare un'attività basata su app

Questa sezione illustra come usare l'API Create businessScenarioTask per creare un'attività basata su app.

Utilizzare la seguente richiesta HTTP POST. Ecco l'aspetto della richiesta, con segnaposto per le proprietà specificate.

Richiesta

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

Le sezioni seguenti illustrano come formare la richiesta in modo più dettagliato.

Come definire le proprietà nella richiesta

Un tipo specifico di allegato differenzia un'attività basata su app da un'attività standard. L'allegato deve essere di tipo TeamsHostedApp e contenere un collegamento appositamente formattato (URL di riferimento) all'esperienza di destinazione nell'app Teams. Ciò significa che Planner che l'attività è basata sull'app.

Tenere presente che l'API fa riferimento a questi allegati come riferimenti.

Prima di tutto, configurare l'URL di riferimento in modo che punti all'esperienza di destinazione. Specificare quindi l'URL di riferimento insieme ad altre proprietà necessarie per l'allegato nel corpo della richiesta.

Passaggio 1: Configurare l'URL di riferimento

L'URL di riferimento usa un formato specifico. Seguire questa procedura per creare e codificare l'URL.

Passaggio 1a: Creare l'URL

L'URL di riferimento all'esperienza di destinazione deve usare la sintassi del collegamento Stageview Modal nel formato seguente:

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

Per creare l'URL di riferimento, specificare i parametri seguenti.

Parametro Descrizione
Teams-app-Id ID dell'app Teams che si sta integrando con l'attività.
URL-to-destination-experience URL che punta all'esperienza di destinazione nell'app Teams di destinazione che si vuole che gli utenti visualizzino quando aprono l'attività. Per motivi di sicurezza, l'URL deve puntare a un dominio valido associato all'app Teams, rappresentato dall'ID app fornito.
page-title Titolo che dovrebbe comparire nella parte superiore dello schermo quando all'utente viene visualizzato l'URL dell'esperienza di destinazione.

Ecco un esempio di URL di riferimento prima della codifica:

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

In questo esempio:

  • Teams-app-Id è l'ID dell'app YouTube in Teams (com.microsoft.teamspace.tab.youtube). Tenere presente che la maggior parte degli ID delle app di Teams è alfanumerica e potrebbe avere un aspetto diverso.
  • URL-to-destination-experience punta all'esperienza all'interno dell'app Teams di destinazione (https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY).
  • page-title è il nome del titolo dello schermo (Security talk) durante il caricamento dell'URL.

Se l'app YouTube in Teams è disponibile, è possibile inviare questo URL a se stessi e confermarne l'apertura.

Passaggio 1b: Codificare l'URL

È necessario codificare l'URL di riferimento prima di poterlo usare nell'allegato. La codifica percentuale assicura che il collegamento sia in un formato compatibile per l'uso programmatico.

Seguire questa procedura per codificare l'URL di riferimento. Per illustrare come codificare l'URL, viene usato l'URL di riferimento di esempio descritto in precedenza.

  1. La percentuale codifica la parte dell'URL che segue 0?context=. Non codificare https:// o = (il simbolo uguale) o i caratteri tra di loro.

    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

    Mancia

    Questo è l'ultimo passaggio in cui il collegamento può essere facilmente convalidato nella chat di Teams. Dopo aver completato questo passaggio, è possibile testare l'URL inviandolo a se stessi in una chat di Teams. Il collegamento dovrebbe aprirsi su Teams desktop, Web o mobile per qualsiasi utente che ha accesso all'app di destinazione in Teams.

  2. Sostituire tutti i. caratteri nell'URL di riferimento con %2E. È necessario eseguire questa operazione su tutti i caratteri nell'URL di riferimento, dall'inizio alla fine. Se si ignora questo passaggio, l'URL di riferimento potrebbe non funzionare.

    L'URL seguente è pronto per l'uso programmatico.

    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 l'URL punta a una Power App, assicurarsi che includa il &source=teamstab parametro per il funzionamento del Single Sign-On (SSO) per Power Apps e il &skipMobileRedirect=1 parametro per ignorare lo schermo che richiede agli utenti di aprire il lettore autonomo di Power App.

Passaggio 2: Definire l'allegato

Per definire l'allegato, specificare le proprietà seguenti nel "references" corpo della richiesta.

        "references": { 
            "{reference-URL}": { 
            "@odata.type": "microsoft.graph.plannerExternalReference", 
            "alias": "{destination app name}", 
            "previewPriority": " !", 
            "type": "TeamsHostedApp" 
         } 
       }
Proprietà Descrizione
reference-URL URL dell'esperienza di destinazione nella sintassi del collegamento Stageview Modal. Per informazioni dettagliate su come creare e codificare l'URL, vedere la sezione Passaggio 1: configurare l'URL di riferimento di questo articolo.
alias Nome dell'app Teams. Quando un utente apre l'attività, viene visualizzato il messaggio "Completa questa attività con <alias> e un pulsante Avvia attività per passare all'esperienza di destinazione.
previewPriority Lascia come !.
type TeamsHostedAppImpostato su . Questo è ciò che significa Planner che l'attività è un'attività basata sull'app.

Esempio

In questo esempio viene illustrato come creare un'attività basata su app denominata "Rivedere la presentazione delle procedure di sicurezza" e assegnarla a un utente denominato Adele Vance (ID utente 44ee44ee-ff55-aa66-bb77-88cc88cc88cc). Questa richiesta usa l'URL di riferimento di esempio della sezione Passaggio 1: Configurare l'URL di riferimento di questo articolo.

Richiesta

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

Questo URL di riferimento di esempio è stato scelto come modo semplice per testare l'esperienza delle attività basata sull'app usando un'app disponibile in ambienti di molte organizzazioni. Tenere presente che con questo URL di riferimento di esempio gli utenti non saranno in grado di completare l'attività. Questo perché l'app YouTube non è integrata con attività basate sull'app e non effettua una chiamata API per contrassegnare l'attività come completata dopo la riproduzione del video.

Aspetto dell'app Planner

Ecco cosa vede l'utente quando apre l'attività nell'app Planner in Teams. Se selezioni il pulsante Avvia attività , l'utente passa all'esperienza di destinazione nell'app Teams. In questo esempio, l'esperienza di destinazione è un video sulle procedure di sicurezza nell'app YouTube in Teams.

Screenshot di un esempio di attività basata su app in Attività personali nell'app Planner in Teams.

Per altre informazioni sull'esperienza utente, vedere Gestire attività basate sull'app nell'app Planner in Teams.