Curiosity Built the App: The Creation of Smartsheet's Microsoft Teams Integration
Published on 10 July 2017
The best software developers are always curious. And, here at Smartsheet that is no different. Our recent integration with Microsoft Teams began as the fruits of curiosity from one of our top engineers.
When Jenny Lam heard about Microsoft's new Teams chat platform she wondered what kind of APIs were offered, and how she could use them. During her exploration she found that there were three different options for integrating with the Teams platform - bots, cards and tabs.
Bots provide a simple "command-line" type interface that allows Teams users to interact with other services by typing a command in the chat window. For instance, a bot for a retail store could be listening to the chat stream for questions about products or orders, and then respond automatically.
Rather than waiting for a question or another event like bots, cards inject events or notifications of events into a chat stream.
Integrating with tabs allows developers to display their service on a dedicated canvas within a channel. This is essentially accomplished by having your application or service run in an IFRAME on its own tab.
Our decision to go with a tabs solution was two-fold. First, the prospect of being able to embed the Smartsheet UI right into a Teams tab provided a rich experience that Smartsheet users were familiar with. The second reason, however, was much simpler: Jenny was curious about something.
As mentioned before, a tabs integration is an application that is running outside of Teams, and is embedded inside a tab through an IFRAME. So, when building your tabs integration, we needed to make sure that our content worked in an IFRAME.
Also, for the IFRAME-ed application to interact with Teams, each page inside the app must include the Microsoft Teams Tab library as a script source. And then, once a page loads successfully, it needs to initialize that library by calling microsoftTeams.initialize(). Without this, Microsoft Teams will not show the page.
The Smartsheet integration uses microsoftTeams.authentication.authenticate() to launch an OAuth2 flow to authenticate the user as a Smartsheet user, and authorize them to connect Teams to their Smartsheet account and data. It is essential that authenticate() is used so that the authentication process will work successfully both in the web and desktop versions of Teams.
When you select the Smartsheet application inside of the "Add a tab" window in Teams, you're asked to login. This will take you through the previously mentioned OAuth2 flow. With this authorization, you will then be allowed to select a sheet, a report or a Sight that will display in the tab.
The selected item must be published in Smartsheet in order for it to be displayed in the tab. If the item isn't already published, you will be given the option to set the publish status on the following screen.
Publishing an item, such as a sheet, allows you to provide the rich Smartsheet interface, while retaining the control of how that sheet is used. The published item can be fully interactive, or read-only. All of these publish settings are available through the Smartsheet API, and utilized in the Teams integration.
The settings saved for the tab will remain in place for the life of the tab. If you want to change which sheet or report is displayed in the tab, you simply delete the unwanted tab and create a new Smartsheet tab with the newly desired sheet.
At the beginning of Jenny's Teams integration journey she went with a tab integration partly because it made sense for Smartsheet, but also because she was curious about building an application with an interactive UI was also a driving factor.
After putting together a proof of concept of the Smartsheet for Teams integration on her own time, and showing it to the team, Jenny was given the green light to prepare her application for production use.
Given a tight timeline to get her application production ready in time for the public launch of Microsoft Teams, Jenny credited the componentized nature of previous Smartsheet integrations that allowed her to utilize sections of code that was common to most Smartsheet integrations, and already written. Namely, a baseline project (developed internally as a starting point for integrations projects) provided the beginnings of an architecture and technology stack that Smartsheet's technical operations team could easily implement as part of their established deployment processes.
This baseline application consisted of a RESTful API written in Java, using the Spring MVC framework, as well as client-side code running AngularJS with Sass (scss).
"If I didn't have sheet picker, it would have taken me twice as long," Jenny said with a laugh.
In the end, the project was an all around success. The project was ready in time to launch as one of the original Teams apps. Jenny got to satisfy her curiosity for new APIs and client-side development. Our customers got to leverage Smartsheet collaboration inside of Microsoft Teams. And, when our customers and employees are both happy, that's definitely a win for Smartsheet.