Manage app-powered tasks in Planner for tailored task experiences

Overview

The app-powered tasks feature offers your organization more control over what users see when they open their tasks in the Planner app within Microsoft Teams. Instead of showing only the standard set of task fields, you can provide users with an experience tailored to the task at hand. 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. To achieve this, you integrate a Teams app with the task and create these tasks programmatically.

Say, for example, users in your organization use a Teams app to track and complete inspections. You can integrate this inspections app with tasks so that a Planner task is created for each inspection tracked in the system.

• When a user opens one of these tasks from the Planner app in Teams, they see a simplified screen with a button to jump directly to the inspection experience powered by your inspections app.
• When they complete the task and close the inspections experience, they're right back in Planner where they started.

Users get the tailored experience that a Teams app provides right from within their assigned tasks. They don't have to navigate to a different app to get work done or lose context of where they were when working with their tasks.

In addition to these benefits when users complete tasks, the app-powered tasks feature allows organizations to reflect required line-of-business processes and workflows as tasks, so employees can see all the work they're accountable for from a single place.

This experience is supported in the Planner app on Teams web, desktop, and mobile. You can provide tailored task experiences for your users with any Teams app that meets the following requirements.

Requirements

App-powered tasks is an extensibility feature that relies on programmatic creation and management of tasks. The requirements to use this feature are as follows.

• Each app-powered task points to an experience in a destination Teams app, which requires you to provide a reference URL to that experience. We recommend that you point this reference URL to the specific item or screen the user should be working on. This reference URL must be added to the task in a specific way. To learn more, see the Step 1: Configure the reference URL section of this article.

• Tasks must be created and updated using the business scenarios API in Microsoft Graph.

• Users who need to work with the task must have access to the destination app in Teams, as governed by the app policies you set in the Teams admin center. To learn more, see Overview of app management and governance in Teams admin center.

• The destination Teams app is responsible for managing the task lifecycle, which includes the following actions:

  • Create the task. See Create businessScenarioTask.
  • Assign the task. See Update businessScenarioTask.
  • Update the task, if properties change. See Update businessScenarioTask.
  • Mark the task as Completed when all steps are done. See Update businessScenarioTask.
  • Delete the task. See Delete businessScenarioTask.

This feature allows your destination Teams app to govern the task lifecycle because some workflows might not have deterministic flows. As a result, the Planner app doesn't know whether all required steps are completed. For example, a finding during an inspection might result in the inclusion of several more steps in the inspection. Similarly, users are prevented from updating task fields or marking the task as Completed. These actions might result in users making changes that conflict with what's reflected in your destination Teams app.

Create an app-powered task

This section covers how to use the Create businessScenarioTask API to create an app-powered task.

Use the following HTTP POST request. Here's what the request looks like, with placeholders for the properties that you specify.

Request

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

The following sections walk through how to form the request in more detail.

How to define the properties in the request

A specific type of attachment differentiates an app-powered task from a standard task. The attachment must be of type TeamsHostedApp and must contain a specially formatted link (reference URL) to the destination experience in the Teams app. This signifies to Planner that the task is an app-powered task.

Keep in mind that the API refers to these attachments as references.

First, you configure the reference URL to point to the destination experience. Then, specify the reference URL along with other required properties for the attachment in the request body.

Step 1: Configure the reference URL

The reference URL uses a specific format. Follow these steps to construct and then encode the URL.

Step 1a: Construct the URL

The reference URL to the destination experience must use Stageview Modal link syntax in the following format:

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

To construct the reference URL, specify the following parameters.

Here's an example of a reference URL before encoding:

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 this example:

• Teams-app-Id is the app ID of the YouTube app in Teams (com.microsoft.teamspace.tab.youtube). Keep in mind that most Teams app IDs are alphanumeric and might look different.
• URL-to-destination-experience points to the experience within the destination Teams app (https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY).
• page-title is the name of the screen title (Security talk) when loading the URL.

If the YouTube app in Teams is available to you, you can send this URL to yourself and confirm it opens.

Step 1b: Encode the URL

You need to encode the reference URL before you can use it in the attachment. Percent encoding ensures the link is in a compatible format for programmatic use.

Follow these steps to encode the reference URL. We use the example reference URL described earlier to demonstrate how to encode the URL.

1. Percent encode the part of the URL that comes after 0?context=. Don't encode https:// or = (the equal symbol), or any of the characters in between.

   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

   Tip

   This is the last step where the link can be easily validated in Teams chat. After you complete this step, you can test the URL by sending it to yourself in a Teams chat. The link should open on Teams desktop, web, or mobile for any user who has access to the destination app in Teams.

2. Replace all . characters in the reference URL with %2E. You must do this across all characters in the reference URL, from beginning to end. If you skip this step, the reference URL might not work.

   The following URL is ready for programmatic use.

   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

   Note

   If your URL points to a Power App, make sure it includes the &source=teamstab parameter to make single sign-on (SSO) work for Power Apps and the &skipMobileRedirect=1 parameter to skip the screen that prompts users to open the standalone Power App player.

Step 2: Define the attachment

To define the attachment, specify the following properties in "references" in the request body.

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

Example

This example shows how to create an app-powered task named "Review security practices presentation" and assign it to a user named Adele Vance (user ID 44ee44ee-ff55-aa66-bb77-88cc88cc88cc). This request uses the example reference URL from the Step 1: Configure the reference URL section of this article.

Request

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

What this looks like in the Planner app

Here's what the user sees when they open the task in the Planner app in Teams. Selecting the Start task button takes the user to the destination experience in the Teams app. In this example, the destination experience is a security practices video in the YouTube app in Teams.

To learn more about the user experience, see Work with app-powered tasks in the Planner app in Teams.

Related articles

• Use the business scenarios API in Microsoft Graph to integrate with Planner
• Manage the Planner app for your organization in Microsoft Teams