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

Articolo
11/15/2024
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. Si sceglie di 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 abbandonano 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à basate sull'app consente alle organizzazioni di riflettere i processi line-of-business obbligatori e i flussi di lavoro come attività, in modo che i dipendenti possano vedere tutte le attività assegnate a loro da un'unica posizione.

Questa esperienza è supportata nell'app Planner su Web, desktop e dispositivi mobili di Teams. È possibile aggiornare qualsiasi app di Teams per creare attività basate su app e offrire esperienze attività personalizzate per gli utenti.

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.

Ogni attività basata su app deve avere un URL di riferimento che punta a un'esperienza in un'app Teams di destinazione. È consigliabile indirizzare questo URL di riferimento all'elemento o alla schermata specifica su cui l'utente dovrebbe lavorare. Questo URL di riferimento deve essere aggiunto all'attività in un modo specifico. Per altre informazioni, vedere la sezione Configurare l'URL di riferimento di questo articolo.
Le attività devono essere create e aggiornate usando l'API degli scenari aziendali in Microsoft Graph.
Gli utenti che devono lavorare con l'attività devono avere accesso all'app di destinazione in Teams, disciplinata dai criteri dell'app impostati nell'interfaccia di amministrazione di Teams. Per altre informazioni, vedere Panoramica della gestione e della governance delle app nell'interfaccia di amministrazione di Teams.
L'app Teams di destinazione è responsabile della gestione del ciclo di vita delle attività, che include le azioni seguenti:
- Creare l'attività. Vedere Creare businessScenarioTask.
- Assegnare l'attività. Vedere Aggiornare businessScenarioTask.
- Aggiornare l'attività, se le proprietà cambiano. Vedere Aggiornare businessScenarioTask.
- Contrassegnare l'attività come Completata al termine di tutti i passaggi. Vedere Aggiornare businessScenarioTask.
- Eliminare l'attività. Vedere Eliminare businessScenarioTask.
  
  Questa funzionalità consente all'app Teams di destinazione di governare il ciclo di vita dell'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.

Usare la seguente richiesta HTTP POST, dove {your-business-scenario-ID} si trova l'ID dello scenario aziendale.

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

Di seguito è illustrata una richiesta con segnaposto per le proprietà specificate nel corpo della richiesta.

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

Definire l'allegato

Ciò che differenzia un'attività basata su app da un'attività standard è la presenza di un allegato specifico. L'allegato contiene un collegamento (URL di riferimento) all'esperienza di destinazione nell'app Teams, che consente a Planner di riconoscere un'attività come basata su app.

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

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 formattare e codificare l'URL, vedere la sezione 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`	`TeamsHostedApp`Impostato su .

Configurare l'URL di riferimento

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

Specificare i seguenti parametri nell'URL di riferimento.

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 specifica nell'app Teams di destinazione che si vuole che gli utenti visualizzino quando aprono l'attività. Il dominio dell'URL deve essere un dominio valido per l'ID app.
`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.

Codificare l'URL di riferimento

È 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.

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.
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.

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'esempio di URL di riferimento.

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

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 è un video sulle procedure di sicurezza nell'app YouTube in Teams.

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

Condividi tramite

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

Panoramica

Requisiti

Creare un'attività basata su app

Definire l'allegato

Configurare l'URL di riferimento

Formattare l'URL

Codificare l'URL di riferimento

Esempio

Aspetto dell'app Planner

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

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

Panoramica

Requisiti

Creare un'attività basata su app

Definire l'allegato

Configurare l'URL di riferimento

Formattare l'URL

Codificare l'URL di riferimento

Esempio

Aspetto dell'app Planner

Articoli correlati

Commenti e suggerimenti

Risorse aggiuntive