officedev / microsoft-teams-sample-task-module-nodejs

Sample app showing off the Teams Task Module, a way to invoke custom code from a bot, a tab, or both! (Node.js/TypeScript version.)

page_type	products	languages	description	urlFragment	extensions
sample	office-teams office office-365	typescript nodejs	A task module allows you to create modal popup experiences in your Teams application.	teams-module-node	contentType createdDate samples 9/17/2018 6:53:22 PM

Microsoft Teams task module - Node.js/TypeScript sample

A task module allows you to create modal popup experiences in your Teams application. Inside the popup, you can run your own custom HTML/JavaScript code, show an <iframe>-based widget such as a YouTube or Microsoft Stream video, or display an Adaptive card.

Task modules build on the foundation of Microsoft Teams tabs: a task module is essentially a tab in a popup window. It uses the same SDK, so if you've built a tab you are already 90% of the way to being able to create a task module.

Try it yourself

This sample is deployed on Microsoft Azure and you can try it yourself by uploading TaskModule.zip to one of your teams and/or as a personal app. (Sideloading must be enabled for your tenant; see step 6 here.) The app is running on the free Azure tier, so it may take a while to load if you haven't used it recently and it goes back to sleep quickly if it's not being used, but once it's loaded it's pretty snappy.

Overview of this sample

This sample app was developed in conjunction with the task module feature itself to exercise as much of it as possible. Here's what's included:

• A channel tab. Add the app to a team, then add a Task Module tab and choose "Task Module Demo" from the dropdown list.
• A bot. Add the app to a team, then chat with it (@Task Module)
• A personal app. When you upload the TaskModule.zip file, choose "Add for you" and "Task Module" will appear in the "..." menu in the Teams app bar. The personal app has both a tab and a bot.

The tab shows how to invoke the task module using the Teams SDK. Source code for the tab is found in TaskModuleTab.ts; the view definition is in taskmodule.pug. This sample app uses Pug (formerly Jade) for HTML rendering.

The following task modules are supported:

• YouTube, which is comprised of a generic template for embedded <iframe> experiences (also used for the PowerApp task module below) plus a four-line stub containing the YouTube embed URL
• PowerApp — unfortunately it doesn't work out of the box; click the button or see the source code for details on how you can customize it for your tenant
• A simple HTML form
• There are two Adaptive card examples:
  • Showing the results of an Action.Submit button returned to the tab
  • Showing the results returned to the bot as a message

The sample app also contains a bot with cards allowing you to invoke these task modules. You can invoke them from an Adaptive card (using the tasks command) or from a Bot Framework thumbnail card (using the bfcard command). RootDialog.ts contains the code for the tasks and bfcard commands, and TeamsBot.ts contains the code for responding to task/fetch and task/submit messages. The task modules when invoked from a bot are the same as for the tab, except for the Adaptive card examples:

• Adaptive Card - Single returns the results to the conversation as a message.
• Adaptive Card - Sequence shows how adaptive cards can be chained together: instead of returning the result to the chat, the result is shown in another Adaptive card.

Implementation notes

• This sample is data-driven as much as possible and shares as much code as possible between the bot and the tabs forms of task module:
  • Metadata used to generate TaskInfo objects is in contants.ts.
  • All cards are generated via JSON templates in the cardTemplates collection in CardTemplates.ts and rendered using the ST-JS (Select Transform) JavaScript library. The values in cardTemplates have data placeholders, e.g. {{title}}; JavaScript objects are created in TaskModuleTab.ts and RootDialog.ts, and helper functions in CardUtils.ts are used to render the cards.
  • Deep links are generated in the taskModuleLink() function in DeepLinks.ts.
  • Except for the JavaScript in the task modules themselves, all code is in TypeScript. Three source files, contants.ts, DeepLinks.ts, and CardTemplates.ts are used on both the client (tab) and server (bot). Browserify is used in the gulpfile.js build script to bundle the JavaScript generated by TypeScript; this script file is referenced by taskmodule.pug.
• The logic for handling task/fetch messages is also data-driven, shared across card types (Adaptive and Bot Framework), and supports chaining of Adaptive card task modules. The data-driven approach for card generation combined with the fact that the Adaptive and Bot Framework card schemas are quite different unfortunately means that the way it works is not obvious. Here's how it works:
  • All the task/fetch and task/submit requests and responses are JavaScript objects defined in the fetchTemplates[] collection in CardTemplates.ts and generated in TeamsBot.ts in the onInvoke() function.
  • The custom properties data.taskModule (for Adaptive card Action.Submit buttons) and value.taskModule (for Bot Framework card actions) are used as lookup values to select a specific response from the fetchTemplates[] collection when a task/fetch message is received.
  • Adaptive card chaining — showing multiple adaptive cards in a sequence — is implemented using the data.taskResponse property on an Adaptive card Action.Submit button. With Adaptive Card - Single, the card is rendered with data.taskResponse set to "message" (show a message to the user); for Adaptive Card - Sequence, the same Adaptive card is rendered with data.taskResponse set to "continue" (show another Adaptive card). This is the only difference between fetchTemplates.adaptivecard1 and fetchTemplates.adaptivecard2. The second Adaptive card (cardTemplates.acSubmitResponse in CardTemplates.ts) in the sequence just shows the JSON submitted in the first; its data.taskResponse is set to "final". The logic for handling the various values of data.taskResponse is in TeamsBot.ts. The taskResponse values form a simple "protocol" for responding to the different ways to respond to task/submit messages: do nothing (complete), show a message to the user, load a subsequent adaptive card in a sequence, or load the final adaptive card in a sequence.
• To avoid hardcoding an appId in customform.pug, the appId is passed in at Pug template rendering time by tabs.ts, the TypeScript which implements the tab routes.
• Theming and simple keyboard handling for the Esc key are supported.

Bonus features

There's also an actester bot command. It's a handy way of seeing what an Adaptive card looks like in Teams - simply copy/paste the JSON of Adaptive cards, e.g. the Samples page on the Adaptive card site, and the bot will render it as a reply.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

microsoft-teams-sample-task-module-nodejs's Issues

Links 404 on Microsoft Teams task module - Node.js/TypeScript sample

A number of URLs on https://docs.microsoft.com/en-us/samples/officedev/microsoft-teams-sample-task-module-nodejs/teams-module-node/ 404 e.g. https://docs.microsoft.com/en-us/samples/officedev/microsoft-teams-sample-task-module-nodejs/teams-module-node/src/views/taskmodule.pug.

Error 403 for the Task module sample

repro steps:

1. add the sample app(from https://github.com/OfficeDev/microsoft-teams-sample-task-module-nodejs/blob/master/TaskModule.zip ) to my teams
2. chat with Task Module
3. click the "Tasks!" button, and found the error bellow:
   

Sample service doesn't seem to be up

Sample service doesn't seem to be up

More ressources / guided steps to use TaskModules

Is is possible to get more documentation and guidelines about using Task Module and specificaly about how to button pop-up call iframe ?

It's hard to figure out how we can use and implement Task Module. Even with using the source code we are not able to : recreate the same behaviour as you did on your TaskModule sample.

Not able to implement the pop-up on the button. Adding the button is OK but having pop-up on click is not explained how-to.
DeepLink are working but need to open a new browser tab.

Also @billbliss is there any chance to have a look on source code on your static web site which is hosting taskmodule pages ?

We are tring to implment taskModule pop-up to call embeded iframe of a PowerApps but without losing / switching contexte for end-user ;)

Many thx for your help & time. If you have any question don't hesitate to ask i will gladly gave you more details

Azure website not reachable

I just noticed that the Azure website used for this example is not reachable anymore.
The link should be: http://taskmoduletest.azurewebsites.net/.
Is that correct?

YouTube url support ?

I am looking at the sample provided here and can't figure out how to embed the youtube url for DeepLink approach. In following piece of code final resolved value of "url" becomes something like this https://08b2243e.ngrok.io/youtube so I was wondering where its is pointing to actual youtube vide url.

exports.fetchTemplates = {
    youtube: {
        "task": {
            "type": "continue",
            "value": {
                "title": constants.TaskModuleStrings.YouTubeTitle,
                "height": constants.TaskModuleSizes.youtube.height,
                "width": constants.TaskModuleSizes.youtube.width,
                "fallbackUrl": `${appRoot()}/${constants.TaskModuleIds.YouTube}`,
                "url": `${appRoot()}/${constants.TaskModuleIds.YouTube}`,
            },
        },
    }

Moreover, task/fetch is not working on emulator. Is this expected ? Can TaskModule run on emulator ?

Getting error while building

I was running "gulp server:start" , but getting the below error Cannot find module './storage'

Trace

C:\GitHub\Personal\BotBuilder-Samples-main\BotBuilder-Samples-main\samples\typescript_nodejs\microsoft-teams-sample-task-module-nodejs-master\build\src\app.js
at Function.Module._resolveFilename (internal/modules/cjs/loader.js:982:15)
at Function.Module._load (internal/modules/cjs/loader.js:864:27)
at Module.require (internal/modules/cjs/loader.js:1044:19)
at require (internal/modules/cjs/helpers.js:77:18)
at Object. (C:\GitHub\Personal\BotBuilder-Samples-main\BotBuilder-Samples-main\samples\typescript_nodejs\microsoft-teams-sample-task-module-nodejs-master\build\src\app.js:35:17)
at Module._compile (internal/modules/cjs/loader.js:1158:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1178:10)
at Module.load (internal/modules/cjs/loader.js:1002:32)
at Function.Module._load (internal/modules/cjs/loader.js:901:14)
at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:74:12) {
code: 'MODULE_NOT_FOUND',
requireStack: [
'C:\GitHub\Personal\BotBuilder-Samples-main\BotBuilder-Samples-main\samples\typescript_nodejs\microsoft-teams-sample-task-module-nodejs-master\build\src\app.js'

How can we make it work in mobile devices?

I do not see the tab in an iPad. How can we develop tabs that are compatible in mobile device?

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request