Exercise 2: Using adaptive cards and deep links in task modules

In this exercise, you’ll learn how to use adaptive cards in a custom task module in a custom Microsoft Teams app. You’ll also learn how to invoke task modules from anywhere within Microsoft Teams using deep links.

[!IMPORTANT] This exercise assumes you have created the Microsoft Teams app project with the Yeoman generator that contains a personal tab from the previous exercise in this module. You’ll update the project to add a new task module that uses an Adaptive Card.

Task 1: Create video selector as an adaptive card

In this section, you’ll create an Adaptive Card that mirrors the functionality of the video selector task module created in a previous exercise. Adaptive Cards are defined using JSON that can be written by hand or using the Microsoft Teams Developer Portal.

1. In the browser, navigate to https://dev.teams.microsoft.com and sign in with the credentials of a Work and School account.

2. Select the Tools from the left-hand navigation then select Adaptive Cards editor (Preview) app:

1. In the Card editor, select New card.

1. Provide a card name. The card we’re creating is used as the YouTube Video Selector card. Select Save. The tool will display a list of example cards. Select Blank Card.

2. The Card editor will show a default card and its live preview. You can use this interface to design your card and see how it will be rendered.

1. From the json tab, replace the contents of the default card with the following JSON:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "YouTube Video Selector",
          "weight": "bolder",
          "size": "extraLarge"
        }
      ]
    },
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Enter the ID of a YouTube video to show in the task module player.",
          "wrap": true
        },
        {
          "type": "Input.Text",
          "id": "youTubeVideoId",
          "value": ""
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Update"
    }
  ]
}

1. This JSON code instructs Microsoft Teams to render a textbox and button. When the button is selected, it will submit the card.

2. Copy and paste this JSON into a new file, YouTubeSelectorCard.json, into the folder in the existing project ./src/client/youTubePlayer1Tab/.

Task 2: Create a new task module that uses the Adaptive Card

After creating the Adaptive Card, the next step is to create a task module that will display it and handle the submission action.

1. Within the existing Microsoft Teams app project, locate the file ./src/client/youTubePlayer1Tab/YouTubePlayer1Tab.tsx that contains the custom personal tab.

2. Find the following import statement at the top of the file that imports components from the Fluent UI - React library:

import { app, dialog } from "@microsoft/teams-js";

Replace the previous statement with the following import statement:

import { app, dialog, tasks } from "@microsoft/teams-js";

1. Locate the return statement and add the following code to add a button after one of the existing buttons:

<Button content="Change Video ID (AdaptiveCard)" onClick={() => onChangeVideoAdaptiveCard()}></Button>

1. Next, add the following method to the YouTubePlayer1Tab class:

const onChangeVideoAdaptiveCard = (): void => {
  const taskModuleInfo = {
    title: "YouTube Video Selector",
    width: 350,
    height: 250
  };

  const submitHandler = (err: string, result: any): void => {
  };

  tasks.startTask(taskModuleInfo, submitHandler);
};

[!NOTE] The dialog.open() method used in the previous exercise does not yet support an Adaptive Card as the body of the dialog. This exercise is using the deprecard tasks.startTask() method which still works.

1. The next step is to load the Adaptive Card and set the value of the video ID to display when it loads. Do this by adding the following code to the top of the onChangeVideoAdaptiveCard() method:

// load adaptive card
const adaptiveCard: any = require("./YouTubeSelectorCard.json");
// update card with current video ID
adaptiveCard.body.forEach((container: any) => {
  if (container.type === "Container") {
    container.items.forEach((item: any) => {
      if (item.id && item.id === "youTubeVideoId") {
        item.value = youTubeVideoId;
      }
    });
  }
});

1. Next, implement the callback. When the Adaptive Card executes the submit action, it will send an object back with all the input objects as properties. Update the existing submitHandler() in the onChangeVideoAdaptiveCard() function. This code will update the state with the value of the video ID specified in the Adaptive Card:

const submitHandler = (err: string, result: any): void => {
  console.log(`Submit handler - err: ${err}`);
  setYouTubeVideoId(result.youTubeVideoId);
};

1. Lastly, add a new card property to the taskModuleInfo object, and set its value to the adaptive card. The resulting taskModuleInfo should look like the following code:

const taskModuleInfo = {
  title: "YouTube Video Selector",
  card: adaptiveCard,
  width: 350,
  height: 250
};

Test the Adaptive Card task module

1. Save the modified files. The ngrok task will detect the changes and rerun the webpack task. Upon completion, the web page should refresh to show the updated content.

2. In the browser, navigate back to the tab in the Microsoft Teams interface and select the new button Change Video ID (AdaptiveCard). Microsoft Teams will open a task module with the rendered Adaptive Card:

1. Replace the video ID in the input box and select Update. Notice the video ID displayed in the tab is updated to reflect this new value.

Task 3: Invoking task modules with deep links

Task modules can be invoked by selecting a button in the Microsoft Teams experience, or using a deep link. Deep links allow you to trigger a task module invocation from outside of Teams, or within Teams from a conversation.

1. The format for a deep link is as follows:

https://teams.microsoft.com/l/task/<APP_ID>?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>

1. Consider if you wanted to open a task module from a conversation that would display the following video on an Overview of teams and channels.

2. As you learned in a previous exercise, the URL to display the video in the player task module would be the following:

https:///youTubePlayer1Tab/player.html?vid=VlEH4vtaxp4

1. The deep link to launch the video player task module would be the following (assuming your custom Microsoft Teams app’s ID is 3386faf0-109f-11ea-9799-77a28170bd5d):

https://teams.microsoft.com/l/task/3386faf0-109f-11ea-9799-77a28170bd5d?url=https:///youTubePlayer1Tab/player.html?vid=VlEH4vtaxp4&height=700&width=1000&title=YouTube%20Player:%20Overview%20of%20teams%20and%20channels

1. In Microsoft Teams, go to a channel, select the Conversations tab, and select the Format button in the message dialog:

1. Enter a message to post to the channel. Select some of the text and use the Link feature to add the deep link to the message:

1. Now, select the link to see the task module open without having to trigger it from the custom tab.

Summary

In this exercise, you learned how to use adaptive cards in a custom task module in a custom Microsoft Teams app. You also learned how to invoke task modules from anywhere within Microsoft Teams using deep links.