Microsoft Teams 'Todo List' sample tab app

  • Code Sample
Browse code

Build Status

This is an example tab app for Microsoft Teams. The point of this sample to illustrate how simple it is to convert an existing web app into a Microsoft Teams tab app. The existing web app, TodoMVC for React, provides a basic task manager which integrates with your personal Outlook Tasks. With only a few minor modifications, this web view can be added to a channel as a tab app. Take a look at the code diff between the 'before' and 'after' branches to see what changes were made.

Note: This is not a realistic example of a team collaboration app. The tasks shown belong to the user's individual account and not to a shared team account.

For more information on developing experiences for Microsoft Teams, please review the Microsoft Teams developer documentation.

Prerequisites

  1. An Office 365 account with access to Microsoft Teams.
  2. This sample is built using Node.js. Download and install the recommended version if you don't already have it.

Run the app

Host the tab apps "configuration page" and "content page"

As the tab configuration and content pages are web apps, they must be hosted.

First, we'll prepare the project:

  1. Clone the repo.
  2. Open a command line in the repo subdirectory.
  3. Run npm install (included as part of Node.js) from the command line.

To host the app locally:

  • In the repo subdirectory, run npm start to start the webpack-dev-server to enable the dev app to function.
  • Note that the dev manifest is set up to use localhost, so no additional configuration would be needed.

Optionally, to build a deployable app, which you can host in your own environment:

  • In the repo subdirectory, run npm run build to generate a deployable build.
  • Modify the config.url in the prod manifest to point to your hosting location. See below

Add the tab to Microsoft Teams

  1. Download the tab app dev package zip file for this sample.
  2. Create a new team for testing, if necessary. Click Create team at the bottom of the left-hand panel.
  3. Select the team from the left-hand panel, select ... (more options) and then select View Team.
  4. Select the Developer (Preview) tab, and then select Upload.
  5. Navigate to the downloaded zip file from step 1 above and select it.
  6. Go to any channel in the team. Click the '+' to the right of the existing tabs.
  7. Select your tab from the gallery that appears.
  8. Accept the consent prompt.
  9. If needed, sign in using your Office 365 work/school account. Note that the code will try to do silent authentication if possible.
  10. Validate authentication information.
  11. Hit Save to add the tab to channel.

Note: To re-upload an updated package, with the same id, click the 'Replace' icon at the end of the tab's table row. Don't click 'Upload' again: Microsoft Teams will say the tab already exists.

It is advisable to have multiple configs, one per environment. The names of the zip files can be anything such as todo.dev.zip, todo.prod.zip etc. but the zip must contain a manifest.json with a unique id. See Creating a manifest for your tab.

Code walk through

While the master branch shows the latest state of the sample, take a look at the following code diff between:

  • before: the initial app

  • after: the app after integration with Microsoft Teams.

Going through this step by step:

  1. We have added a new config.html and config.tsx page which is responsible for the the application to allow the user to manipulate any settings, perform single signon Authentication etc. during the first launch. This is required so that the team administrator can configure the application/settings. See Create the configuration page.

  2. We have added the same config.html file to our webpack.common.js configuration so that it can inject the right bundles during runtime.

  3. We add a reference to MicrosoftTeams.js in our index.html and added MicrosoftTeams.d.ts for Typescript intellisense.

  4. We have added a manifest.dev.json, manifest.prod.json and two logos for size 44x44 and 88x88. Remember to rename these as manifest.json in your zip files that you upload to Microsoft Teams.

  5. We have added some styles to our app.css.

  6. Finally we have modified the authentication in outlook.tasks.ts to depend instead on 'useMicrosoftTeamsAuth', a new feature from the beta version of OfficeHelpers referenced in this sample.

Invoking the Authentication dialog

When the user adds the tab, the configuration page is presented (config.html). In this case, the code authenticates the user if possible.

Authentication leverages a new Teams-specific function in the latest (>0.4.0) version of the office-js-helpers library. This helper function will attempt to silently authenticate, but if it cannot, it will call the Microsoft Teams specific auth dialog for you. For more information on the full Authentication process in Microsoft Teams, please review Authenticating a user in the Microsoft Teams developer documentation.

In outlook.tasks.ts:

 return this.authenticator.authenticate('Microsoft')
    .then(token => this._token = token)
    .catch(error => {
        Utilities.log(error);
        throw new Error('Failed to login using your Microsoft Account');
    });

Handling the 'Save' event

After successful sign-in, the user will Save the tab into the channel. The following code enables the Save button, and sets the SaveHandler, which will store what content to display in the tab (in this case, just the project's index.html).

In config.tsx:

    initialize({ groupId, upn}) {
        this.setState({ groupId, upn });
        console.log(this.state);
        /** Enable the Save button  */
        microsoftTeams.settings.setValidityState(true);
        /** Register the save handler */
        microsoftTeams.settings.registerOnSaveHandler(saveEvent => {
            /** Store Tab content settings */
            microsoftTeams.settings.setSettings({
                contentUrl: `${location.origin}/index.html`,
                suggestedDisplayName: "My Tasks",
                websiteUrl: `${location.origin}/index.html`
            });
            saveEvent.notifySuccess();
        });
    }

Technology used

This sample uses the following stack:

  1. React by Facebook as the UI Framework.
  2. TypeScript as the transpiler.
  3. TodoMVC base for TodoMVC functionality.
  4. Webpack as the build tool.

Additional Resources

Registering an application to authenticate with Microsoft

Note that this will not be necessary if you use the local Dev option above, but if you choose to host this tab in your own environment, you must register the application in order to authenticate.

  1. Go to the Microsoft Application Registration Portal.
  2. Sign in with your Office 365 work/school account. Don't use your personal Microsoft account.
  3. Add a new app.
  4. Take note of your new Application ID.
  5. Click on Add Platform and choose Web.
  6. Check Allow Implicit Flow and configure the redirect URL to be https://<mywebsite>/config.html.

For more information on hosting your own tab pages, see the Microsoft Teams 'Get Started' sample README.

Note: By default, your organization should allow you to create new apps. But if it doesn't, you can get a developer test tenant, a one-year trial subscription of Office 365 Developer at no charge. Here's how.

Credits

This project is based on the TodoMVC Typescript - React template located here.

Contributing

Please read Contributing for details on our code of conduct, and the process for submitting pull requests to us.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the License file for details