Microsoft 365 Microsoft Graph

A Lap around Microsoft Graph Toolkit Day 7 – Microsoft Graph Toolkit Providers

Author: Simon Ågren, Microsoft Office Development MVP

Welcome to Day 7 of the Microsoft Graph Toolkit blog series!

So far in this series, you have gotten acquainted with many important pieces of the Microsoft Graph Toolkit. Today we will talk about the last remaining piece of the puzzle, the piece that makes everything magically work – the provider.

The fundamental role of a Microsoft Graph Toolkit provider is to enable all the components to call Microsoft Graph to retrieve and render data. The provider takes care of getting the necessary access token with the requested scopes.

Today you will get a high-level overview of the Microsoft Graph Toolkit Providers, the architecture and even how we could use it outside of the components to make Microsoft Graph calls.

What’s in the box?

Microsoft Graph Toolkit offers ready-to-go providers that are useful in the most common scenarios.

Providers             Description

Msal                     Uses MSAL.js to sign in users and acquire tokens to use with Microsoft Graph.

SharePoint          Authenticates and provides Microsoft Graph access to components inside of  SharePoint web parts.

Teams                  Authenticates and provides Microsoft Graph access to components inside of Microsoft Teams tabs.

Proxy                   Allows the use of backend authentication by routing all calls to Microsoft Graph through your backend.

Custom Provider

All the ready-to-go Microsoft Graph Toolkit providers have been created in the same way that you could create providers yourself. They are reusable and are created for the most common scenarios. When would you create your own custom provider then?

You’d want to create your own provider if you find yourself in a scenario where you have an application with existing authentication code and want to hook into that mechanism. The question you want to ask yourself here is if it makes sense to create a reusable provider. Is this likely a recurrent situation? If the answers are yes, you are at the right spot to learn how to create your own providers. There are two ways to create custom providers:

SimpleProvider

For non-recurrent situations you can use the simple provider. Basically, the role of the simple provider is to return the token from your own authentication code. Instantiate a SimpleProvider class by passing in a function that will return an access token for passed-in scopes.

Here is a sample that Nikola Metulev built with the SimpleProvider and MSAL.js: Simple Provider Sample

IProvider

For resusability in recurrent situations you can create your own provider. All Microsoft Graph Toolkit Providers (including SimpleProvider) extend the IProvider abstract class. You can also extend IProvider to create your own provider.  We suggest you read more here: IProvider Documentation

The Architecture

architecture diagram for Microsoft Graph Toolkit providers.

The image above is an attempt to visualize the Microsoft Graph Toolkit provider architecture at a high level. The image is divided vertically into two sections: Provider Initialization and Provider Consumption. There is actually more going on behind the scenes than shown in this diagram – these are the important things to understand.

The Providers namespace is very central, as it holds the global provider reference that is being used by the components when calling Microsoft Graph.

Provider Initialization

The first thing we need to do is initialize a new provider. Then we need to set the newly initialized provider as the “global provider” in the Providers namespace. You can do this process in two distinct ways.

top portion of providers architecture where it shows provider initialization

By a developer in code

Simple enough, we initialize a new provider instance with the configuration properties we need and set it to be the global provider.

Providers.globalProvider = new MsalProvider({
    ClientId: ‘[CLIENT_ID]’
}); 

Another example could be in a SharePoint Framework Web Part, where we use the Web Part Context to initialize a new SharePointProvider.

protected async onInit() {
    Providers.globalProvider = new SharePointProvider(this.context);
}

Using a Component Provider

In the last post regarding the The Power of mgt-get you saw the usage of the Component Provider mgt-msal-provider.

<mgt-msal-provider client-id=”[CLIENT_ID]”></mgt-msal-provider>

Behind the scenes the component provider initializes a provider in code and sets it as the Global Provider, in a similar fashion as the developer would have done.

this.provider = new MsalProvider(config);
Providers.globalProvider = this.provider;

Provider Consumption

Microsoft Graph Toolkit uses the Microsoft Graph JavaScript SDK for all calls to Microsoft Graph. The IProvider has been designed to work with the SDK and its AuthenticationProvider class.

bottom portion of providers architecture where it shows provider consumption

Each provider implements an instance of the SDK which enables the provider to call Microsoft Graph APIs either from inside of a component or outside. More on this later…

Another cool thing is that the provider keeps track of the user’s authentication state, which is either loading, SignedIn or SignedOut. When the state changes the components gets an update via event handlers, so they know when it’s time to call the Graph.

Each component checks to see if there’s a provider present and if the state is SignedIn before using the SDK to call the Graph.

if (provider && provider.state === ProviderState.SignedIn) {
    const graph = provider.graph.forComponent(this);
}

Extending the mgt-get scenario

In the previous post Cameron Dwyer created a great scenario in order to show you how to use mgt-get to displaying items from a SharePoint list. But what if we would like to do another operation that is not about getting data, what if we want to create or update something?

We will build upon the scenario from the previous post, by grabbing the initialized global provider from the Providers namespace and use it to update the list items in the SharePoint list.

Let’s look at some of the code… (You can also look at this sample in Try-It-Out repo here.)

const provider = mgt.Providers.globalProvider;
let graphClient;
if (provider && provider.state === mgt.ProviderState.SignedIn) {
    graphClient  = provider.graph.client;
}

After grabbing the Global Provider, we check the state to see if the user is considered signed in. If that is the case, we create a reference to the SDK Graph Client.

I have made some small changes to the HTML code as well:

code block that uses mgt-get to build the packing app.

  • The $filter includes all that aren’t ‘Delivered’
  • I have created a status span that depending on status displays a different color
  • If the item status is ‘Requested’ (not Packed) I display a button that lets the user “Pack” it.

This is how it looks like now.

UI with updated functionality that a user can choose to pack an unfulfilled order.

If the user would click the “Pack” button we would run the updateOrder() function in the background:

code block to update UI and data where orders are fulfilled.

This function is in charge of updating the specified list item in SharePoint. It takes two arguments in the constructor: orderId (string) and newStatus (string), and then makes an update() (PATCH) call. I’m using the prepScopes from Microsoft Graph Toolkit in order to utilize the correct scope for the operation.

When the update is done, you’ll get a notification indicating that the packing of the item went well.

UI notification when order is packed

And lastly, the order with the status ‘Requested’ is now considered packed.

UI of SharePoint List changes when order is packed.

Finishing up

Today we have focused on Microsoft Graph Toolkit providers. You have seen an overview of how to use out-of-the-box Microsoft Graph Toolkit providers, gotten some ideas on when and how to create your own, and how easy it is to use the Graph Client (Microsoft Graph JavaScript SDK) outside of the components.

The whole idea behind the Microsoft Graph Toolkit is to make it faster and easier for developers  to create and customize many of the most commonly used  components in Microsoft 365 apps and integrations – without having to focus too much on what is happening behind the scenes.

After today we hope that you understand that you have even more options with Microsoft Graph Toolkit, to call Microsoft Graph in your own preferred way, as the last remaining piece of the puzzle.

Build 2020 and Season 2

Look for us at Build 2020 where we’ll do a session on Microsoft Graph toolkit for beginners. If you would like to code with us, we will also host a live coding session using Microsoft Graph Toolkit and show you how to build apps that are connected to Microsoft Graph in the most efficient way! We will resume our blog series on June 1st for season 2 of A Lap around Microsoft Graph Toolkit. We have articles on each provider accompanied by more samples. Let us know what you think on social network using #MSGraphToolkitLap! See you soon.

filter-icon