Microsoft 365 Community Community Demos, 7 Jun 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Teams JS SDK v2 to extend your Microsoft Teams solutions to Outlook and Office

Description

In this 19-minute developer focused demo – Bob German recaps recently announced enhancements (multi-host support, new namespaces, promises, new API calls, and backward compatibility) in the client-side SDK v2, along with concepts of capabilities and hosts. Client-side calls (deep links) do not overlap calls to Graph. See how new capabilities can be queried, review several capability APIs, and then see capabilities in a demo of an app running in all 3 supported hosts. Code walkthrough and upgrade steps outlined. This PnP Community demo is taken from the weekly Microsoft 365 Platform Community call recorded on June 7, 2022.

Demo Presenter
• Bob German (Microsoft) | @Bob1German

Supporting materials
• Sample - Extend Teams app to other M365 host apps like Outlook, Office.com | aka.ms/teamssdk-v2-sample
• Documentation - Microsoft Teams JavaScript client SDK | aka.ms/TeamsSDK-V2
• NPM Package – Microsoft Teams JavaScript client SDK | https://www.npmjs.com/package/@microsoft/teams-js/

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

A

Hi everyone so quick shifting of gears. Imagine you were going to send an sms message and then you said, wait a minute. First, I want to upgrade to the team's javascript sdk version 2., and so and so that's why we're taking a side step here today. So uh what jeet already started the discussion on this? It's pretty cool stuff, and so let me show you in a little bit more detail.

A

uh First, I'd like to give you just a little bit more context into what is the team's javascript sdk, there's a bunch of different sdks that you may encounter when you're doing development for microsoft, 365.

A

a lot of them call back end rest services, and so I just want to make clear teams. Javascript sdk is the sdk that you use inside of microsoft teams apps that control the client. They they pretty much interact with either the desktop client, the browser-based client or the mobile client, and in general, although there may be some back end processing you're, not really aware of that.

A

So this will get interesting in a few minutes when we get into kind of contrasting what you would use the graph for using probably the graph sdk, or maybe the pnp sdk, but in general I think this one is going to be more you're, going to think of this more as something that you're working with the client application rather than with the server side, if that makes sense, so the biggest enhancement, as would you had already pointed out and was announced in build and demi and demoed by uh rabia by dan's, and my colleague, robio williams- here- are some of the high level enhancements.

A

So multi-host support is big right. So this is the. This is kind of the big splash. Is that now you can run these applications in and still in preview in outlookandoffice.com, but I'll show you that, but it's also still obviously works in teams. There are some new namespaces which I'll talk about a lot of the old version. 1 sdk used callbacks, so it was kind of a little bit retro there now we're using promises.

A

Although there is backward compatibility and I'll talk about that too. There's some new api calls and, as I mentioned, we're backward compatible two concepts that I want you to understand are really capabilities and hosts. So capability is a logical grouping of apis that provide some set of functionality, and you can see them all listed here.

A

So app is something that you would use in all in any app, whereas calendar or chat are relating to calendars and chats hosts are the different microsoft, 365 applications that can run your app and yes, we've got apps inside of apps now, and I guess that's probably been true for a while, but just sort of realizing it here as I'm talking about it anyway.

A

So here you can see a matrix of all of the capabilities and what hosts they are supported in so, for instance, calendar is available in teams and outlook calls and chats are available in teams. Only mail is available only in outlook etc. So it kind of makes sense if you think about it like this is really growing into something that can span more than just teams.

A

There are each one of these capabilities is also a name space in the sdk and these name spaces all support. A single call called is supported, so the correct way to query and say gee is it? Is it possible for me to send a mail, or is it possible for me to initiate a call?

A

You don't really want to go in and say: am I in microsoft teams? Am I in microsoft outlook you can do that I'll. Show you how to do that. There's reasons to do that, but you know what we might change it in the future. We might suddenly start supporting calls in another application.

A

So you're much better off saying, is supported and in this case mail is supported, is going to come back true only if you're in outlook, but that could change in the future so code. You know future proof your code and use the is supported rather than an explicit check on which uh application. So, for example, here I am if I'm in teams mail is supported, is going to come back false, but suppose I just want to show some different information in teams, or maybe I want to theme my page a little differently in teams.

A

Well, there's a way to do that too, and so that would be done using the the team's app context and there's a property in there called host.name and there's also an enumeration microsoft teams.hostname.x, so you can just come in here and say: look is the host name teams and then I can theme it for teams. That's appropriate use of of the context variable as opposed to the is supported flag.

A

I'll show a few of the capability apis here, just as a sample. These are just selected. I couldn't fit it on the slide. There's too many notice that they all have is supported.

A

So you can just check before you go trying to compose a meeting or a chat and and just make sure that you're in an environment where that's supported, the other thing is, and would you keep me honest on this please, but looking at this, what I'm seeing is that, although some of these things might appear to overlap what we have in the microsoft graph, these are really client-side calls.

A

So what's going to happen, is and a lot of these used to be available and still are available as deep links.

A

So, for instance, there was always a deep link if I want to chat with dan and if, if his network is working better and I can chat with him, I could do a deep link that would open up teams in a chat with dan right now. I can do that with an sdk call called open chat, which is nice, because it's smart enough to know if at some point a a chat should be available in some other host other than teams. You don't have now hard-coded a deep link into teams right.

A

So that's that's a a really nice way to do it, but keep in mind that open chat is not going to like the graph would allow you to code up some messages and send them under program control. That's not what this does. This is going to open up the chat window, and so these tend to be more user interface types of features. For instance, compose mail is going to put you into a new mail view in the ui or, um let's see people select.

A

People is not going to do a programmatic selection, it's going to launch a people picker and then return to you, which person got picked so just to sort of kind of de-confuse a little bit. Maybe what you would do in the graph versus what you would do with this sdk so without further ado, let's get into a demo and I'll show you an app that's running in all of these hosts that are currently supported.

A

So here I am in teams- and if I come down here to- and this is the same demo by the way that robia uh showed in build- and she did the the sdk conversion and all the upgrades on this. So this is a lot of her good work here. So I want to take my hat off to robia williams on this.

A

So here I am and yeah russell asks isn't sharepoint a supported host. I would love it if somebody else could answer that, because I really don't understand myself.

B

I can probably quickly comment on that one for now it's not uh potentially in the future, so so technically sharepoint does support already microsoft teams applications, but we haven't validated it to be v2 completely compliant. So so it will be there in the future so already today and in there for many years. Actually you can track any microsoft teams, application to microsoft, er, sorry, sharepoint, app, catalog and start using that in the pages so.

A

Thanks yeah, I was a little confused about that myself and I never. I never want to speculate on what the product teams are doing, so thanks so much visa for clarifying. So so back to the demo. Here we are, and I'm in my north wind orders application.

A

This is the experimental version by the way this is coming soon in a lab environment near you, you'll be able to build this lab up called something in an environment called teams app camp which robbie and I and other teammates are working on, uh and this will show kind of give you a hands-on of converting a sas application or a single page app into a teams app with all the different features. So it's a lot of fun anyway. What robia did here is she took this and made it sdkv2 and I'll show you the code.

A

Some code changes in a minute, but let me just show you what it does so here I am inside of my. I can see all my orders from northwind right. I can also come in and see products and kind of browse into those and do all sorts of things, and you know I I could get into this functionality more. But let's, let's focus on the multi-host part right. So another thing I could do is I could go into office home.

A

This has surprised me. A lot of people live in this, so some people will say like. Why do I care about office home? Other people are like? Oh wow. I live in this right because here's my app right. So if you want to know how to get to an app there, it is notice that the ui is slightly different and she took the chart out here and I'll show you how that's done in the code, but that was intentional.

A

It's it's reasonable that your app would maybe behave a little bit differently when it's running in office or in teams and then the other option, which is in outlook. So here's the same app running in outlook right and so that works the same way and the auth is all there, nice and uh and um single sign-on and all that kind of stuff. Another fun thing I can do because outlook is, I can use a messaging extension, so if you're not familiar with these, they work in teams. Of course already.

A

But now I can come in here and send somebody an email and could you check inventory.

A

And what do I want to check inventory on so in the bad old days? I would go. Look up the skew for the item that I needed and type it into my email and then katie would get the email and she would have to go look up the sku to figure out what it was and then she'd go to the warehouse and all that kind of fun stuff.

A

Now I can just come in here and uh click on the little apps in right, underneath where I'm wording my uh composing my email and I can come in here and actually search for a product and there's some products. So let's go into aniseed syrup, which is conveniently begins with the letter a which is why I like it and um we've just gotten a huge shipment. So we now have a hundred of these, and so I could actually update or the recipient of this email more realistically could update the stock.

A

So I'm going to do it right now so that I don't have to switch users. Oh doesn't like it until I send it all right. Keep me honest. Keep me honest. Let's send this and then I'll go over here to my sent items and I'll update it here and I can update the stock and wow. That's great. So now I've just saved I've just really streamlined things because katie upon getting this email, she doesn't have to go. Look it up. She doesn't have to open another application.

A

She can work from this actionable message right inside of outlook, and this came from my team's app, which is or now an m365 app and in fact, if I come back to my overall view and let's go into products- and I believe that was a condiment yep there, it is and there's the updated inventory so very nice. So let's look at the code, so the first thing that I had to do was I had to update my schema.

A

So if you are, there's not a lot of changes, but the version number matters. Okay. So if you are going to use the preview functionality of hosting in outlook and office, then you need version 1.13.

A

If you want to just use the new sdk for just future proof, keeping up getting bug fixes getting some of those other enhancements, but you're only going to run it in teams, then the fully supported version is 1.12, so 1.12 shipped at build and lets you use the v2 sdk 1.13 is in preview and supports office and outlook just to be really clear about that. So let me show you some some code samples here.

A

We are actually initializing the sdk now you're only supposed to initialize once and I had fun writing an article about how to do this, where I've got different web components that are firing off requests. At the same time, we're actually going to store the promise centrally and then teams.app.initialize returns a promise to prevent calling the initialize more than once. It doesn't cause any huge problems, but it does flag an er so trying to be a good citizen here and not initialize it more than once notice that this.

A

If you are familiar with this, the old call didn't have the dot app name space in there. So it was just microsoft. Teams done initialized and it used a callback. So then you were constantly wrapping functions and functions and stuff, so this is much much cleaner and easier. The old way still works for backward compatibility, but you know eventually it's officially deprecated but still works. So you know over time. You've got some time now to migrate things over to the new calling syntax and of course it makes your your code a lot simpler.

A

Now, I'm going to scroll down a little and show you the theming.

A

So when the theming gets set on the page, we're going to look to see if we're in microsoft 365, which is our own little function here and if it, if the initialize fails, it's going to be mean that we're not even in any m365 location and then we're going to grab the context and then check context.app.host.name.

A

And, depending on, if that's teams, outlook or office we're going to set different style sheets on here, and if it's teams we're also going to register a theme change handler so that we can update our background, color, etc. When somebody does, you know, changes the theme in teams so that we can be nice and up-to-date by the way. This is not to I'm occasionally glancing at uh at the uh chat. Can this be done in bulk? I think the team's toolkit has some assist on that, but I'm not up to date on it.

A

I don't still think it's in bulk. I think it would be like bring your app in and it will help with conversion. Is it an spf x app? No, it is not. This is a standalone, vanilla, javascript, app and in fact, spfx does not yet support the sdk v2. To my knowledge, that is going to require more work by the sharepoint team. So this is a standalone teams app, which means it's running in an iframe and the messaging extension is running using the bot framework.

A

The taskbar is on the left. Does that mean bob is still on 110? Yes, it does, please don't get too mad at me. I like the fact that I can hide the date and time and that I can keep the taskbar on the left, where I have more real estate than down at the bottom, so uh someday I'll switch my development machine over to windows 11 when they provide me with those those features. So anyways, that's that's the point there.

A

Now, let's look at the identity stuff, so this particular app knows how to run inside or outside of m365. So it's actually going to revert to using msl for authentication if we're running outside. So you can see a little bit of that here. We're going to get an this is just a generic get access. Token again, I don't want to get the access token too often, if I have different parts of the code, so I'm going to cache a promise here and then I'm going to go ahead and grab this access token.

A

If I'm in m365, I just call get auth token again. This used to be callbacks, isn't it wonderful? Now it's just a promise. Promises are beautiful, especially when people keep their promises, which this does and if not, then we start digging into m cell goodness right. So that's that's kind of how that piece works and then, finally, let me show you one other little thing.

A

So if I'm in teams and go back to my teams, one and I go into one of these details right, one of the things I can do is chat with the sales contact for this order right, maybe something came up, I'm trying to get those uh scottish long, breads and the long breads came in too short this year. So you know what am I going to do.

A

I need to chat with the sales rep, so I click the button and bang I'm in a chat and that's what I mean see what I mean by it's a user. It's a client level function, so that was one of those new capabilities and yeah. It's not actually up sending the chat message, it's putting me in the ui so that I can send the chat message if that makes sense right so anyway, that is only going to be visible.

A

If I'm inside of teams, so let's go back to the code and what you'll see is that it's going to say if microsoft teams, dot chat, dot is supported is true, so if all of a sudden outlook has a chat capability or microsoft, you know some other feature. Part of microsoft starts supporting chat, they're, trying to sort of ease away from like kind of hard-coded. This is these are the five apps that we have or whatever and sort of make it a little bit more open-ended.

A

If it's supported, then we're going to go ahead and make the adaptive card and display it and go ahead and send the open group chat when someone clicks the button makes sense and and go ahead and make use of one of those new sdks.

A

So I think that's about it for the demo. Let me just go back quickly to slide and show the call to action.

A

So if you would like to upgrade right now, the first step is to install the sdk there's the npm command, if you're not bundling, and some of the cool kids are not bundling these days, you can actually there's cdn links and all sorts of things up there on npm, where you can grab that, then you want to update your team's app, manifest to either 1.12 or 1.13, and then over time, update your code check out the capabilities and hosts translate your callbacks into promises. Rejoice that your code is much shorter and easier to read.