Friday 8 March 2019

Create Microsoft Teams from a template

One thing we’ve been waiting for is the ability to create many Teams from a template, in the same way that many organisations do with SharePoint sites. Microsoft have now released this (in preview at the time of writing), and we can define a template in JSON defining exactly what the Team should look like, including the channels, tabs, installed apps, owners and various configuration settings. This is great, because we can now work on scenarios such as a project team, which might have channels for “Technical”, “Account management”, “Project delivery”, “Client success” and so on. You can imagine various tabs being defined in the different channels - perhaps the Account Management channel would have a tab with a widget to bring in summary data from CRM. Maybe the Technical channel would have a tab displaying current work items from Azure Dev Ops too. Apps being made available across many Teams could be 3rd party apps available in the Teams store, or something custom that has been developed in-house.

The things you need to work with templated teams can be summarised as:



So this is all quite developer-led. It isn’t as though the template is being stored in the Teams service somewhere for example - ultimately a dev is writing code to pass some JSON to a call to the Graph. And this JSON contains all details for team creation – the name, the description, the channel settings, installed apps and so on. As I’ve been working with the API, I’m finding that some code which splits out building the JSON somewhat is useful. In particular, it seems useful to split it into two parts:

  • Things that change for every team being created (name, description, owners)

    ..and..

  • Things that stay the same and are considered part of the template (channel settings, installed apps and so on)
So this post is to provide some simple code around that in case others find it useful. There’s nothing too complex here, but I’m trying to get more in the habit of sharing little bits of code via Github.

For details on the JSON structure and the Graph call, see https://docs.microsoft.com/en-us/graph/api/team-post?view=graph-rest-beta. As the documentation shows, the sample JSON to create a team might look like this (this is the very sample from docs):

So, although we’re constructing this JSON and passing it to the Graph, a developer working with this might choose to:

  • Create a static JSON file with the non-changing parts, and treat this as the “template”
  • Write some code to append JSON representing the team name, description and owner(s)

You might notice from the extract above that the owner needs to be specified in the form of a GUID, rather than what you most likely have (the user’s account name/e-mail address). This GUID is the user identifier in AAD. Consequently, we’ll also need a method in our code to lookup a user GUID from an account name.

What exactly can we define in a Teams template?

Here’s a summary:

Setting Example
Visibility Public/Private
Installed apps [Any app from app catalog]
Owners [List of users]
Channel details Tabs, favourite by default
Member settings Allow create channels, allow add apps etc.
Guest settings Allow create channels, allow delete channels
Fun settings Allow giphys, stickers and memes, content rating
Messaging settings Allow edit/delete of messages, allow team and channel mentions

The code

The main helper code I wanted was a method I could call which would accept parameters for the team name, description, and owner(s) so I could call it many times. Perhaps it could become the core code behind something that reads from an Excel file to create many Teams in bulk. Or perhaps it would be behind a custom form in a nice end-user self-service request process. In terms of authentication, this code uses app-only auth to create the Team (using an AAD client ID and client secret), rather than delegated auth (in the context of the user). But, you can take either approach depending on your needs.

So, the core code I came out with is (shown here in the context of a simple console app - but you can drop the core method into whatever you need):


You might notice that I have a “TeamDetails” class which is also doing some of the work. This is where the code to manipulate the JSON is, providing methods to append the team name, description, and owner(s) to the other details being specified:


Of course, the full code is available in Github – it’s at the following address: https://github.com/chrisobriensp/TeamsProvisioning

The result

We can now create as many teams as we like wih the CreateTeam() method shown above. Each one will be created with the channels, tabs and other properties specified in the template. For example, here are the channels and tabs as defined in the sample JSON shown above:



Summary

Creating many Microsoft Teams in a consistent way with the right set of tools is now possible, and we can do it with app-only permissions too (so no need to do anything dodgy around storing details of a high-privilege account). You might find the code in this article useful if you start working with the Graph API methods to do this. In addition to creating Teams with the 'standard' template, note that Microsoft themselves are also providing some specific base templates baked-in to the service - and these might suit your needs out-of-the-box. For now, these base templates are targeted at education, retail and healthcare scenarios - but more will come in the future no doubt.

Either way, we have some new options for rolling out Teams with specific functionality. Hopefully the Graph methods which underpins this will come out of preview very soon, so this approach can be used in production solutions.

No comments: