Custom Microsoft Teams Applications — The Easy Way
After Microsoft Teams integrated it’s product to the Office 365 package, over 500 000 organizations actively using the platform as their main tool for communication. Microsoft Teams supports integrations over 230+ established applications at the time this was written, with the possibility of adding your own applications.
I work for a company named Netcompany; a multinational IT company that use Microsoft Teams as a tool for communication. As a company working across countries, we wanted to gather most of our day-to-day applications in one place.
We found that Microsoft Teams gives you the possibility to embed web applications by using tabs for dedicated teams.
The goal of this article will be to show a step-by-step guide how we successfully embed our web applications with Microsoft Teams and making it available on mobile, web and desktop.
Requirements
- Office 365 Developer subscription
- A deployed web application
- Microsoft Teams
Topics:
- Microsoft Teams Tabs
- Creating a Microsoft Teams manifest
- Installing a Custom Application
Tabs in Teams is represented as IFrames, therefore some sacrifices has to be made. Examples of this is authentication, the application can’t navigate to a third-party provider without setting up permissions correctly.
Microsoft Teams Tabs
Microsoft Teams support two different type of tabs, static and configurable. Static tabs gives a private area for individual users, here the user does not share information with rest of the team. Configurable tabs are part of the channel and are single sources of truth, these tabs contain a configuration page in addition to the main content page.
Tabs comes with three different scopes:
- team, can be interacted as a shared experiance
- groupchat, 2 or more users
- personal, private experience
A static tab can only use a personal scope. Whereas a configurable tab can use the team or groupchat scopes. In this article we’ll use a configurable tab with the scope set to team as an example.
A configuration tab requires two different pages, a content page and a configuration page. In this tab you need to include the Microsoft Teams Javascript Client SDK, this gives the application a way to communicate directly with Teams.
The configuration page also requires a few specific lines of code to work, as shown in the gist underneath:
- initialize(); sets up a direct communication to the Microsoft Teams client.
- settings.setValidityState(true); this function accepts the settings that is chosen and gives the user an option to save settings to the application.
Before setting the setValidityState to true, the registerOnSaveHandler makes sure that the tab will keep the settings saved, and redirected users the correct url, this will be done when calling saveEvent.notifySuccess().
When setting the contentUrl, this will redirect the tab to the chosen setting, and view that content for your application.
Creating the Microsoft Teams Manifest
To upload a web application for Microsoft Teams, you need to create a manifest that describes the application. Microsoft supplies a full reference to a Microsoft Teams manifest schema here. This schema can be written manually, or easily created via the App Studio in Teams.
Adding App Studio
Due to the ease of creating the manifest through App Studio, this is the way we will go about it.
Enter apps in the bottom left corner as shown in the picture below, and from here add App Studio to your Teams toolbelt if you don’t already have it.
New manifest
Find the triple dots button […] on the left side in Teams above apps and chose App Studio. Enter the Manifest editor tab, and click the Create new app button.
Within App Studio, we need 4 steps to fulfill the qualifications to distribute your application as a tab:
App Details
The App details page is there to supply base information to your application, such as application name, description and developer information. This is also where you set the application branding by supplying two set of icons that is supposed to represent the application.
This is also where you set up privacy statements and terms of use, this is important if you on a later stage want to deploy your app to the Microsoft Teams Store for other tenants to use.
Tabs
Under the capabilities options we can add what kind of app this is supposed to be. This page consists of two different choices of tabs as we explained earlier; a team tab (configurable tab) and a personal tab (static tab).
Select team tab. This action will prompt a configuration setup, here you enter the configuration URL. Here you get the option to choose scope (team / group chat) and optionally if the tab is hosted via SharePoint.
The configuration URL is needed to set up application settings, for example if you want to use Bing Maps or Google Maps. Example of the configuration URL: https://www.example.com/config.html
Domains and Permissions
Under domains and permissions, you set the domains that the tab can navigate within. If any user tries to navigate outside of the set domains they won’t be allowed, and will be greeted with a Content-Security-Policy and/or X-Frame-Options error.
Here we fill out the domain that we want the application to keep within. We can also use wildcards (*) when navigating around on a specific domain, for example: *.netlify.com or jolly-carson.netlify.com.
Test and distribute
You can install it directly to the team from this page by pressing install, or download the finished manifest by pressing the download button. This allows us to later upload the application internally within a chosen team or distribute it to other teams.
This will download a zip folder that contains 3 files, a manifest.json and two icons that was set earlier in the details section. This zip is now ready for distribution between teams.
You can also submit the app to Teams app store, this requires the application to meet certain guidelines and requirements, and is not within the scope of this article.
Installing Custom Application
Important note: For this step, you will need to have an Office 365 developer account.
Welcome to the last step for this article, integrating the application!
To begin, we start with opening the apps in our bottom left corner again. Here you will find a list of application categories, and on the bottom there will be a “upload a custom app”, as per the picture underneath. From here on choose the zip folder that was downloaded earlier from the manifest editor.
This will create a new category in the apps category list that will be named similar to the company. Click the company named category and see the uploaded app! Use the add button to add the application to the company’s workspace, or use the dropdown functionality to specify which team it should be placed in.
Congratulations!
By following this article, you have successfully integrated a web application with Microsoft Teams. I hope this was helpful for anyone getting into development surrounding Microsoft Teams. There is still more to learn, and this is only part one in a series of articles written towards integrating applications with Teams.
As of today Netcompany is working on expanding our Microsoft Teams applications by integrating with Microsofts Graph API, keep in touch for more around the subject, and see you in the next article!
