In this article, we would like to share our story of how we helped a client to integrate their unique company workflow into Microsoft Teams by building a custom app for Teams. We will let you in on the challenges we faced, how we managed to solve them and what has happened on the Microsoft Teams platform since then.
The widely used collaboration platform Microsoft Teams has become an essential part of many organisations. Employees can interact via chats and video conferencing, make use of the integrated calendar and file service, or even customise the functionality with a set out of over 700 available apps.
However, your company-specific workflow is likely to contain non-standard use cases, which are not covered by any of the generalised existing Microsoft Teams apps. In this case, the Microsoft Teams developer platform provides the possibility to develop your own custom apps and integrate them into your Microsoft Teams context.
Why use a custom Microsoft Teams app?
This is exactly what we did for one of our clients, a large automotive supplier from Germany named Brose Fahrzeugteile SE & Co. KG.
This client uses Microsoft Teams as the company-wide collaboration platform for internal and external communication. A regular use case is the invitation of external guest users into the company’s Microsoft Teams channels and teams, whereby the invitation has to pass through a company-specific approval process, which involves several roles such as responsible people for guest users and managers.
Up to this point, this approval workflow forced the employees to make use of additional tools and maintain these guest users manually. In order to get rid of this overhead and avoid the context switches from Microsoft Teams to other tools, a custom Teams App, which covers the full invitation, approval and maintaining process within Teams, should be developed.
Microsoft Teams Platform
Available Microsoft Teams Platform features
The Teams platform provides a set of different features for building custom apps depending on your specific use case. With the Bots feature you can create a conversational chatbot for automated user interaction. The messaging extension feature lets your users interact with your web service, for example, trigger actions in an external system of yours. Meeting extensions could be, for example, a reminder or an interactive task during a Teams call. Notification subscriptions from other apps can be implemented via webhooks and connectors. With the Microsoft Graph API data like large numbers of users and teams can be managed within your Active Directory. Further information about all available features can be found in the official Microsoft documentation.
Figure 1: Teams platform features
The Tabs feature concept explained
In our described use case, we wanted specific user roles to operate our custom app and request, review or grant guest user permissions. That’s why the Tabs feature turned out to be most suitable for us. Tabs are Teams-aware web pages embedded in Microsoft Teams. They can be added as part of a channel within a team, a group chat or, as in our case, a personal app for an individual user.
Let’s have a look at how the tabs feature of custom Microsoft Teams apps technically works. The custom app is basically a regular web application that is hosted in a location of your choice, for example in the Azure cloud. Within Microsoft Teams you simply upload the so-called app.zip folder, which contains some metadata of your application, such as the app name and the app icon. The location of your app is referenced by the app manifest file within the app.zip folder, which integrates your application in an iFrame within Microsoft Teams. Further configuration aspects, such as content URLs and permissions, can be specified in the app manifest file as well. If you would like more detailed information about the app manifest file, we recommend you take a look at the official documentation.
Figure 2: Teams doesn’t host your app
What build environment options are there?
Since the custom Microsoft Teams app is essentially a regular web app, there are several development options available regarding how to build the app. The Microsoft developer documentation offers a recommendation of appropriate languages and development tools depending on your use case and a good set of code samples and tutorials to get started with your choice of technology setup.
Figure 3: Build environment options
In our approval workflow scenario, we decided to use a tech stack consisting of known web technologies (HTML, CSS, JavaScript) including React, which is recommended for Tabs.
The development process
Development setup
How did we set up our development environment?
A good starting point for building Microsoft Teams – regardless of the technology stack you choose – is Visual Studio Code with the Teams Toolkit extension. The toolkit provides some predefined examples for setting up Microsoft Teams apps that can be adapted to your needs. However, when we started the development, the toolkit had just been released and generated only a simple Tab-based React web application with JavaScript. The generated application could simply be started locally and accessed in the browser on localhost.
The next step was to get the app working within Microsoft Teams so that we could also develop the app locally and use some special features, such as using the available Teams user token for authorization. At this time, unfortunately, the locally run app could not be referenced in Microsoft Teams, even if Microsoft Teams was running in a protected environment, Teams only allows apps from a secure source. In order to get the app running in Teams, we had to set up a tunnel. For this purpose, we used the tool ngrok, which creates a secure tunnel to your localhost and exposes the local server to the public internet, which was accepted by Teams.
After setting up the tunnel, we were able to include all the necessary information in the app manifest file. Since we also needed permissions to work with the Graph API and to retrieve the user token from Microsoft Teams, we had to add an app registration in Azure Active Directory where all these permissions could be set up. The information about the app registration also had to be included in the app manifest file. The App Studio, an application available in Teams, helped us a lot in creating the app manifest file and the .zip folder.
Figure 4: Local application exposed by ngrok to make it accessible within Microsoft Teams
Once the app manifest file was completed, we could upload the .zip folder and the app was then available in our Microsoft Teams app. Thus, we were able to develop the app like a normal web application. But these steps had to be taken by all developers in order to have an individual locally running application within Teams.
Even then, Microsoft held out the prospect that it would eventually be possible to launch the Teams app directly from the toolkit, but the function had not yet been implemented at the time of our project completion. However, in order to keep this promise, Microsoft has put a lot of work into the Microsoft Teams toolkit and the integration with Microsoft Teams, which has made development much easier.
How would we set up a development environment today?
Today, when creating a new Microsoft Teams app, the toolkit launches a wizard to set up the basic configuration of the new Teams app. For example, the developer can decide whether to start with an empty app or with a sample provided by Microsoft and whether the React app should use JavaScript or TypeScript, things we could not choose back then. In addition, it is also now possible to launch the app directly in Visual Studio Code. Neither a protected tunnel nor a manually created individual app registration in Azure AD is necessary anymore. All this information is configured in generated files of the project and can be easily adjusted if necessary. This includes the permissions to retrieve the user token from the Teams app as well as the required Graph API permissions.
When the app is started in Visual Studio Code, the required .zip folder is generated based on the newly added configuration files and added automatically to Microsoft Teams. Also, an app registration with the required permissions in the Azure AD is created. The default browser then opens in a new window, starts Microsoft Teams and prompts you to add the new app. Once added, the app is available with all the necessary permissions and can be developed like a regular web app. All the steps we had to do ourselves are now taken over by the toolkit, which makes it much easier to get started.
Figure 5: The locally running application in Teams
However, some restrictions have remained. Each developer must add their own local app to Teams in order to develop locally and not overwrite the co-developer’s changes during development. For this, the developer needs both permission to add an app to the Teams environment and permission to create an app registration in Azure AD.
Deployment
As we saw in the last section, the way a Microsoft Teams app can be developed has been greatly improved, but a lot of progress has also been made regarding the deployment and integration of an app in Microsoft Teams.
How did we deploy our Microsoft Teams App?
Since the Microsoft Teams app we developed was basically an ordinary React app, the app could be deployed likewise. Consequently, we set up a repository and CI/CD pipeline in Azure DevOps and resources in Azure. To host the app, we chose an Azure App Service because we needed to create an App Service plan for the backend application and it was the most convenient and cost-effective way to deploy the web app on this plan as well. However, you can deploy the app in the way you prefer as long as the web application is accessible to your Microsoft Teams.
After the app had been successfully deployed, the app registration for the app had to be created manually. When creating the app registration, the app had to be given all the necessary permissions, practically the same steps as for the local setup. Finally, we were able to use App Studio to create the app manifest file and .zip-folder and submit it to Microsoft Teams. This had to be done by our client’s administrator owning the required permissions for productive environments.
How can Microsoft Teams App be deployed today?
For deployment, the toolkit for Visual Studio Code has gained many features over time that are helpful in delivering a Teams application but were not available when we encountered these challenges.
First, an Azure account with sufficient rights to create cloud resources and app registrations and an Azure subscription have to be connected to the toolkit. In this way, it is possible to automatically provision all the necessary resources in Azure. Basically, all resources are set up with one click. In contrast to our project, the toolkit creates a storage account where the created React app can be stored and retrieved. The Azure storage account provides a dedicated service for hosting static websites. To move the app to Azure, another button in the toolkit provides the option to deploy the app to the cloud. The toolkit then builds the app based on the related environment and configuration files and transfers the resulting files to the Blob service in Azure. At the same time, the app registration is created with the required permissions.
Finally, the app can be submitted to Teams via the ‘Publish to Teams’ button. For this purpose, the toolkit creates the required .zip folder with the automatically configured app manifest file and uploads it to Teams. There, the organisation’s administrator receives the information about a newly submitted app and can either accept or reject it.
Figure 6: The options provided by the VS Code toolkit for deploying the Teams app
But even though it has become very easy to deploy your Microsoft Teams app from your local system, we strongly recommend that you deploy your app through a CI/CD pipeline, especially for your production environment. This way, you can easily set up a review process and run automated tests within the pipeline, which will ensure the quality of the app in the long run. The steps to deploy your Microsoft Teams app via a pipeline supported by the toolkit can be found in the official documentation. However, the ability to deploy the application directly from Visual Studio Code is great and allows the developer to quickly deploy and test the application in test environments.
Overview of the process
The entire process from launch to deployed application is well illustrated in the following figure. For more information on this process, see the official Microsoft documentation.
Figure 7: Steps from creating a new Teams app to publishing the app
User Interface
Get the Microsoft look with Fluent UI Components
In order to achieve the typical Microsoft Teams look in your custom app, you can build the frontend using Fluent UI components, recommended by Microsoft. These UI components are designed specifically for building Teams apps, work across different screen sizes and are available in light and dark themes. The library covers the most frequently used UI elements, such as buttons, form elements and tables. The React component library has a few underlying concepts, which can seem unfamiliar at first, but should be well understood when integrating the components, for example, Shorthand Props and Render Props.
Figure 8: Fluent UI key value pair components
What did we end up building?
Project architecture
In the following section, we would like to give you a brief overview of the final architecture. In the end, it turned out to be a basic client-server architecture. The backend, written in .NET Core and C#, was responsible for communicating with the database and the Graph API and delivering the requested data to the frontend via a REST API. The frontend in this case was the deployed web application displayed in Microsoft Team.
Since all services were hosted on Azure, we decided to use AzureSQL to store the data. Another very helpful feature was the Azure Functions to reuse some existing and already used batch scripts. These functions could be easily used via REST calls.
As mentioned earlier, we used the token provided by the Teams client to authenticate users. With this token, the backend could identify and authorise a user and allow or deny the incoming requests.
In the end, the different components worked together very well. We were able to implement the use cases required by the client without any serious problems. Furthermore, we could rely on known solutions, with the difference that the website was displayed in Microsoft Teams, which was the most challenging part.
Figure 9: Overview of the architecture
What is our takeaway?
The Microsoft Teams custom app we developed still works well for our customer’s use case and integrates nicely in the company’s business context. Since the users can operate the required guest user approval process within Microsoft Teams, no context switch to other applications is needed anymore, which accelerates and improves their daily workflow.
The most challenging part was the configuration and setup of the project. The app content itself is implemented using known web technologies, which makes it easy for our client’s developers to make changes to the app themselves and evolve it independently. In addition, the custom application is stand-alone, because it is only referenced by Microsoft Teams and therefore can be updated in isolation.
When we started developing the custom app, the Microsoft Teams toolkit for Visual Studio Code was rather new and many complex manual steps were required in order to obtain a functioning development setup and deployment. Some features like push notifications could not yet be implemented with our tabs solution. The Graph API was also limited in some functionalities such as filters and request units back then and provided some features we needed only in the beta version.
The Fluent UI library offers a good set of UI components that bring the Microsoft look to your app. However, the documentation could have been a bit more detailed. For some use cases – especially customised multiple selection dropdowns – we had to analyse the source code on GitHub.
Today, about a year and a half later, a lot of progress has been made by the Microsoft Teams developer team. The toolkit seems much more simplified and offers a complete automatically generated development and deployment setup. Microsoft keeps its promise and works on making Microsoft Teams the central business platform by delivering essential updates and feature extensions regularly.
One question remains for our custom app: How difficult would it be to upgrade from our manual setup to the current automated development setup? In case we get the chance to extend the existing custom app, we will let you know 😉
