Collect Input in Microsoft Teams with Task Modules

Key Takeaways

welcome to the module on collecting input in microsoft teams using task modules hi i'm andrew connell i'm a microsoft mvp in the area of microsoft 365 development i have a lot of experience with sharepoint development microsoft graph microsoft teams developing add-ins for microsoft office as well as developing applications for microsoft identity including azure active directory this video is the first in a series of videos on this microsoft learning module this video is also part of a playlist that includes all the videos that are associated with this module so you can watch them in order the playlist and all its included videos are associated with a microsoft learning module that includes hands-on lab exercises and additional resources check the notes for this video and the associated playlist for more information and where to find the microsoft learning module okay let's get started task modules are modals that you can populate with either an adaptive card or an embedded web or content page for use in your custom microsoft teams app user experience for workflows that require data input task modules allow you to gather information in a teams aware pop-up in this first section we're going to learn the basics of a task module in microsoft teams and how to collect input from users in a custom teams tab we're going to specifically cover an overview of task modules how to invoke task modules and how to dismiss text task modules we'll first start with an overview on task modules task modules allow you to create modal pop-up experiences in your team's applications inside the pop-up you can run your own custom html or javascript code show an iframe based widget such as a youtube or a microsoft stream video or display an adaptive card and they're especially useful for starting and completing tasks or displaying rich information like videos or a power bi dashboard a pop-up experience is often more natural for users starting and completing tasks compared to a tab or a conversational based bot experience task modules build on the foundation of microsoft teams tabs they're essentially a tab inside of a pop-up window they use the same sdk so if you've built a tab you're already 90 of the way to creating a task module now let's look at the structure of a task module or at least what the user experience looks like you can see it has an app icon a short name and then the title of the task module all in the header as well as the close or cancel button as well in that five uh the blue box where we see a five number um that is the entire area that's available to the web page uh if you're using the web page option for rendering your task module everything there you have full control over the ux however if you're using an adaptive card you see how we have in step six or in the section six with the red box around it that's where your adaptive card is going to be rendered and so you see you have a little bit of buffer that's added in the margins for the left and the sides in the top and then finally you also have the adaptive card button that will get added in step seven so you can see the two experiences you've got one gives you full control over the ux in the blue box if you use a web page option whereas an adaptive card is going to be a little bit more constrained but also a more unified look that you have less that you have to worry about now let's talk a little bit about invoking task modules now let's talk a little bit about invoking task modules task modules can be invoked from tabs bots or deep links and the ema code invocation for each one is a little bit different when you invoke it from a tab use the microsoft teams javascript sdk to call the start task method method we'll see that a little bit you can also invoke it from a deep link so what you'll do is you'll create a special url with the details of the task module in the query string and that will tell microsoft teams to launch the task module and then finally you can also invoke it from a bot and you do that by having your bot submit a special invoke message back to microsoft teams let's talk about developing custom microsoft teams task modules task modules can be implemented as a web page and it's very similar to working with custom tabs you're going to display your task module within an iframe so the task module is going to open up just like a tab would open and it's going to have an iframe in it to display the web page users can also close the task module with a traditional x close button in the upper right corner of the iframe but you can also programmatically close the task module as well or submit it using the javascript sdk by calling the submit task method from inside of your webpage to invoke your task module from a tab you're going to call the microsoftteams.tasks.starttask method on the javascript sdk and for that you can pass in two values you can pass in a task info object which is required and a callback the task info object which is actually an object of type task module task info contains a bunch of different properties the title property appears below the app name and to the right of the app icon while the height and width are the number of pixels of the size of the task module or you can use a named size so for example we have small medium and large so what it means for the width is that it's either 20 50 or 60 percent of the width while the height values are 20 50 and 66 percent the url of the page that you specify is what's loaded in the iframe in the task module now this is not used when we work with adaptive cards and the fallback url well if a client doesn't support the task module feature this url is going to be opened up in a browser tab now there are a couple other properties that are used when working with task modules and tabs so like additional properties apply in other scenarios such as like when we use an adaptive card or when we invoke it from a bot i'm going to look at these two scenarios later in this module now the second parameter of the start task method is the callback and the callback can receive a couple different parameters now the callback parameters it can receive is an error object or a string a result string or the result can be really anything microsoft teams will execute the callback if there's an error or when the task module triggers it from within the task module you can submit the data that was collected from the user by calling the submit task method the result object that you pass into that can be either a string or an object and this method will call the registered callback handler in the start task method that you call that you set up if the user closes the task module or an error occurs microsoft teams will close the test module and invoke the provided callback with an error object if there was a problem invoking the task module it's going to be returned to you in one of these following errors that your common errors that you may see there's one error called the values for both card and url were not specified they were specified but we can't have both of them we have to have just one the task info contains values for both the url and the card property these are mutually exclusive you should only use one of these because you're either using a url or a card the second error is you must specify a value for either card or url again they're mutually exclusive but you got to have at least one the invalid app id um what that is is that saying the task info.app id property that's not valid the one that you specify when you said submit task or start task and the user canceled or closed the task module that's notifying the your tab or whatever opened up the task module that the user cancelled out of it