The purpose of this demo application is showcase Microsoft Graph in a real-world application. In particular, the scenario this application aims to address is student project management. We aim to Ignite the Spark that will drive success for all developers; we can ensure breadth partners are set up for success through helpers and reusable components that can enable any developer to quickly accomplish the same success.
| File/folder | Description |
|---|---|
teams |
Manifest and assets to create Microsoft Teams app |
web |
Example code, also a self contained npm project |
web/src |
Source code for the project. |
- Microsoft Graph integration
- Microsoft Graph Toolkit components
- Progressive Web App
- Microsoft Teams integration with the Teams javascript SDK
- Microsoft Identity
- ES 6 , HTML 5, CSS
- Integration with Microsoft Planner for task management
- Integration with group calendar for scheduling
- Integration with Microsoft Teams for managing study groups
- Integration with people and classes for course information
- Integration with excel for assignment tracking and collaborative updates
- Progressive Web App install and teams tab install
- Integration with web notifications
Create your own Azure tenant.
-
Ensure you register the app as multi-tenant, make sure the ID token authentication is set. Set the redirect URI to https://localhost8080, or configure it to your projects requirements. Sign in as an admin to grant all the necessary permissions.
-
Retrieve the clientID Azure Portal and set the environment variables accordingly.
Applications will need to populate the following variables via an environment variable. For instance, a locally run application might create a .env file.
If you choose to deploy this app to Azure, you can set environment variables in the Azure App Service User Interface.
- CLIENT_ID (mandatory)
- START_DATE (optional)
- END_DATE (optional)
- YEAR (optional)
Some permissions require Admin consent. It is recommended to first sign in with an admin account and approve permissions for entire tenant. It might take few minutes for permissions to propagate.
Navigate to the web folder and run the following commands:
-
npm ito install dependencies -
npm startto build + deploy to http://localhost:9000/ -
ngrok http 8080 -host-header=localhost:9000to host locally using ngrok
npm run buildto compile production code that will be output into the web/dist folder.- Use Azure App Service to host your application.
- Set your environment variables accordingly
- Example Demo Deployment
We provide a sample manifest located in the teams folder that can be used to install the application as a Teams tab. To test your own app locally we recommend leveraging ngrok until you have quality tested functionality and are ready for public app deployment. Developers will need to update all URLs in the manifest for their own app instance. Once the manifest is updated a developer can install the app with App Studio for Microsoft Teams
- App Studio for Microsoft Teams Ngrok
- PWA Builder
- Teams JS
- Microsoft Graph Toolkit
- Graph explorer
- Best practice for private config data
In this section, I walk the reader through a few code snippets.
If you have not heard about the powerful Microsoft Graph Toolkit, allow us to introduce you to the People-Picker component. The Mgt-People-Picker allows a developer to enable a user to select colleagues within an Azure tenant in a clean cross platform interface.
Below is the HTML for the people picker that can be found in create-study-group-flyout.html. Note, the div wrapper is used for CSS styling.
<div class="people-picker">
<mgt-people-picker class="people-picker"></mgt-people-picker>
</div>
Now, let's take a look at how to access the chosen people in the create-study-group-flyout.ts file.
const peoplePicker = <MgtPeoplePicker>this.shadowRoot!.querySelector('mgt-people-picker');
[...]
const people = peoplePicker!.selectedPeople;
Now we can do some neat stuff with the chosen individuals.
The below function showcases an integration between the People-Picker and Microsoft Teams. In this project we are sending a message to our colleagues when on creation of a new teams channel.
async sendChatMessage(people, channelId, groupNameInput) {
[...define variables...]
for (let i = 0; i < people.length; i++) {
let mentionInstance = {
id: i,
mentionText: people[i]["displayName"],
mentioned: {
user: {
displayName: people[i]["displayName"],
id: people[i]["id"],
userIdentityType: "aadUser"
}
}
};
mentionsJsonArray.push(mentionInstance);
contentString += `<at id=\"${i}\">${people[i]["displayName"]}</at>, `;
}
[... HTTP post to Microsoft graph ...]
}
Teams integrations is another cool aspect of this project. For example, let’s examine the contents of the providers-helper.ts under the services folder. The below code snippet is fundamental to this app’s authorization flow.
public static initGlobalProvider(){
const clientId = ConfigHelper.CLIENT_ID;
if (!clientId) {
throw new Error('Missing clientId value in env');
}
if (TeamsProvider.isAvailable) {
TeamsProvider.microsoftTeamsLib = microsoftTeams;
Providers.globalProvider = new TeamsProvider({
clientId: clientId,
authPopupUrl: 'index.html', // TODO: fix this
scopes: this._scopes
});
} else {
Providers.globalProvider = new MsalProvider({
clientId: clientId,
scopes: this._scopes
});
}
}
If the app is running Microsoft Teams the Teams auth architecture is used, otherwise, the web app Microsoft Graph auth flow is leveraged.
The helpers folder is chalk full of fantastic open source integrations, if we look at the pwa-builder-helpers.ts we can find all the logic that enables us to pre-cache files and download the app onto a machines operating system. The Open Source PWA Builder initiative has many cross platform features available to help developers supercharge their applications!
The below code gives an example of how to integrate a service worker into a babel/webpack project. Rather than manually copy/pasting a service worker to the root of the project, we can import the PWA service logic to the bellows-app.ts file and maintain a modular codebase. This ensures service worker benefits are bundled on build into the distribution instance of our app.
if ('serviceWorker' in navigator) {
if (navigator.serviceWorker.controller) {
console.log('[PWA Builder] active service worker found, no need to register');
} else {
// Register the service worker
const scriptUrl: string = './pwabuilder-sw.js';
const reg = await navigator.serviceWorker.register(scriptUrl, { scope: './' });
console.log('[PWA Builder] Service worker has been registered for scope: ' + reg.scope);
}
}
This project defines many custom web components. The visual HTML template elements and the bussiness logic of a compnent live in web/src/components subfolders.
Modularization of code is an important principle of software engineering, for a canonical example of modern web components and the robust nature pf typescript and objecxt oriented design checkout the inheritance of component.ts into view.ts.
THIS REPOSITORY IS FOR DEMO PURPOSES - AS IS.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.