Curiosity Built the App: The Creation of Smartsheet's Microsoft Teams Integration

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 Teams Tab library is the JavaScript hook that connects your application with the tab. Among other things, the library allows you to initiate authentication requests with your service as well as read and manipulate settings inside your user's Teams instance.

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.

When the user saves their selection, the integration uses the Tab JavaScript library to save the publishedUrl of the selected item in the tab settings for the channel. This is done by setting the publishedUrl as the tab's contentUrl in microsoftTeams.settings.setSettings({contentUrl: publishedUrl).

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.

Jenny had ample experience as a backend engineer, but very little opportunity during her career to build UI, or work with client-side technologies such as JavaScript, Sass and AngularJS. So, the chance to build an application with an interactive UI intrigued and excited her.

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).  

The baseline API provided the code for an OAuth2 flow with Smartsheet, as well as a couple of example endpoints for interacting with the Smartsheet Java SDK.

On the client-side, the JavaScript code was organized in clearly defined AngularJS modules, with corresponding directives when needed. One of those modules included a fully interactive expanding-tree sheet picker for which Jenny was extremely grateful. Rather than have to take the time to build her own sheet picker, she could take the sample picker provided in the base application and could simply drop it in her application.

"If I didn't have sheet picker, it would have taken me twice as long," Jenny said with a laugh.

In addition to the modularized nature of the Smartsheet coding resources, she also cited Microsoft's support as key to the success of her rapid development timeline. As she was just starting out, she ran into issues with the Teams JavaScript library, and posted a question to Stack Overflow. Someone from the Microsoft team responded quickly, letting her know that a new version of the Library was available. 

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.