Automating Microsoft Teams Class creation with Microsoft Flow & Graph API
Automation is crucial for a steady and effortless Microsoft Teams life-cycle management. Specially in Higher Education and K-12 environments, where you deal with hundreds or even thousands of courses per semester or quarter, that need to be created, maintained and archived. If you, as an IT Manager or O365 Admin don’t have a clear plan for life-cycle management things could get messy every semester or quarter in your institution.
For this we have multiple solutions, such as custom-made solutions from ISVs partners around the world, Microsoft School Data Sync solution, advanced coding, scripting through PowerShell or Graph API.
Today we are going to cover the last one. This is probably the most flexible, easy to customize and powerful option you have. Now a day most IT managers are pretty busy and don’t have much time left to learn new development skills. That’s why I decided to make this really simple so that anyone with basic knowledge of technology and few admin permissions in the O365 tenant can go through the scenario.
This scenario is intended for University /K-12 and Teams for Education, but it could also fit some other vertical scenarios in commercial environments.
During this tutorial you will be able to automate the Class Teams creation and add the students assigned to that class. We will take the Class and Student information from 2 simple Excel files.
So let’s get started with the automation for Teams Class creation.
Step 1 — Creating an Azure Active Directory (AAD) Application
To make the API Calls to the Microsoft Graph API you could use your user, but in a production environment it’s recommended to have an AAD Application registered in your tenant. This app will provide you with permissions to consume the Graph API from your tenant. This app will be the one calling the Graph API from the Microsoft Flow we are going to create.
To create the AAD App you first need to login to your Azure portal, go to https://portal.azure.com and be sure to login with a user that has AAD permissions to register new AAD Apps.
Once we logged in, go to the Azure Active Directory section on the left. And then click on the App Registrations section (Not the one that says App registrations (Legacy).
Click on the New Registration button to start creating your new app.
Then fill out our application name, it should be something representative, as your institution might have others apps in the AAD already and you may wan’t to identify it clearly. Be sure to check the supported account types for “Accounts in this organization directory only”. And you can leave the rest as is.
Once we register our application we will get some details about your app that we will be using later as the Application ID, and the Directory or Tenant ID, be sure to copy them. Then click on the API Permissions tab on the left.
In the API Permissions configuration tab we will need to add more permissions for the app to be able to consume Graph API methods we will be using to automate class team creation. Click on the Add a Permission button.
As you can see there’s a lot of Microsoft APIs you can consume from your application for multiple scenarios, but in this case we are interested in the first one, the Microsoft Graph.
In this case we will be needing Application permissions as the app will be the one consuming the Graph API. Select the option for Application Permissions.
Next we will see a long list with all the Graph API methods you can assign permissions to your app. In this case we will be just needing access to 2 of them, the Group and the User one.
When moving this scenario to a production environment be sure to check that your app has just the minimum permissions needed, it could be dangerous and an security risk to assign other permissions that aren’t really needed for the scenario you are trying to achieve.
After we finished selecting the methods needed for this scenario, add the permissions and you will see a summary of all the permissions assigned to the app.
Next we will need to create an application secret for being able to authenticate as the app. For this go to Certificates and Secrets in the left and click on New client secret. Then just add a description to it, leave the 1 year expiration date and click on add.
After creating your secret you will see a value with random characters generated, be sure to copy an save this in a safe place as it won’t appear again for security purposes.
Now we are ready to move on, this process of creating your AAD App is only needed once. In case you want to have additional automation scenarios you might want to create separate apps with different permissions and access levels per each scenario.
Step 2 — Creating our Microsoft Flow workflow
For this step we will need an O365 account, depending on your licensing you might need to purchase an additional plan for using premium connectors https://flow.microsoft.com/en-us/pricing/ .
To get started go to your O365 portal at https://portal.office.com and login with your credentials. Once you are in, you will see your O365 apps, search for the Microsoft Flow app.
In Flow, go to the “My Flows” section in the left tab. Then create a new “Instant-From Blank” workflow.
Now we are ready to start creating the workflow to automate team class creation in Flow with our AAD App to consume the Graph API.
Step 3 — Get your files ready
For this scenario we will be getting the Classes, Teachers and Students data from Excel files with tables. You could integrate the flow directly to consume your SIS, LMS or other custom system where you manage the school records.
The format we will be using is pretty simple, it consists of 2 files 1 for Class Data and the other one for Student Enrollments.
Inside the Class Data Excel file be sure to have 2 tables on separate spreadsheets. The first table should have the following columns: Class Name, Teacher Email. In this table you could fill out your classes and assigned teacher email for the period.
The second table in the same file should have the following columns: Class Name, TeamsID, Creation Status, Creation Date. This table should be empty as it will be populated with the final details of the automation process so that we can have a report on the classes created.
Now we will need the enrolled students file. This Excel file should have the following columns: Class Name, Student Email. In this case I’m assuming you will have all the classes and enrolled students in just one file, but it could be easily adapted to fit your institution’s needs.
Once we have both of the files we will need to upload them to a OneDrive for Business account, it could be your account. To upload them, go back to the Office Portal and look for the OneDrive app icon. Upload both files in a folder or in the root as you wish.
Step 4 — Setting up the workflow variables
As we will be doing multiple calls to the Graph API in our workflow, the easiest way to go is to define environment variables including some details we will need to call the Graph API.
In the workflow in Flow, add an initial action, search for variable and select the Initialize Variable option.
We will be needing 3 variables for our workflow. The 3 of them are going to contain the information we set apart while we were creating the AAD App.
The first variable is going to contain the Application ID from the AAD App. In the name put a meaningful name you can reference later on in the workflow. In the type select String and in the value copy your App ID from your AAD App ID.
Then do the same with the Directory Tenant ID and the secret. The 3 of them are String Type. At the end you should have 3 variables.
Step 4 — Getting your data from Excel files
Now we will get the Enrolled Students and Class Data information into the workflow to start working with it.
Add a next step for Excel Online(Business). Look for the “List rows present in a table” action. This will get all the rows from an excel table.
Then configure the step, select your file with the Enrolled Student Data. Be sure to select the table you created in the excel file.
Add a next step and do the same for the Class Data excel file. For this second file be sure to select the table that has the Class information and the data from the teachers, not the other empty table we created. At the end you should have 2 excel connectors that list the rows from the tables.
Step 5 — Loop it up
As you can imagine, we now need to loop or iterate through the Class Data list to create the Class Teams, and then iterate through the Enrolled Students to add them to the created Teams.
For this we are going to use the Apply to Each action in flow to iterate through each of the items.
Once we added it, we will see it has a body in which you can add actions that will execute for each of the items entering that loop. In the output be sure to select the values from the previous step that got the data from the Class Data excel.
Step 6 — Making your first Graph API Call
Now we are ready to make the first call to the Graph API. For this you will need to add the Http Call step.
We are first going to get the UserID for the teacher as we will need it for the creation of the team. When we are creating teams through an AAD App calling the Graph API, its required that you include at least one user as the Owner of the team.
For this first call you are going to need to fill some details for the Http URI, and Authentication Method.
First select the Method as a GET method.
Then in the URI you need to put the method call you will be executing. In this case we will be using the Get User https://docs.microsoft.com/en-us/graph/api/user-get?view=graph-rest-beta&tabs=cs . At the moment of this article the call you should include in the URI field looks like this:
https://graph.microsoft.com/beta/users/At the end of the call we need to add the Teacher Email that is the user we want to get the UserID from the Graph API. For this simply click at the end of call text and in the Dynamic content section search for the Teacher Email column from the Excel.
Then in the Authentication field, select Active Directory OAuth. This will show more options we will need to fill.
In the Authority field simply write:
https://login.microsoft.comIn the Tenant field, click on the field and select your Directory ID or Tenant ID variable we created in step 3.
In the Client ID, click on the field and select your Application ID variable.
In the Audience field simply write:
https://graph.microsoft.comIn the credential type make sure Secret is selected.
And in the secret field select your Secret key variable.
Now we are all set! Your first call should look like this at the end:
You can now save your Flow and click on Test Flow on the top right corner. It
It will then prompt you to Run Flow, click on Run Flow and the test will start.
Be sure to click on see flow activity to see the run history. If you click on the test running you will be able to see the step by step test and look for any errors or bugs.
If there’s no errors with your flow you should see all steps with a green check and in the run history it will tell that the flow ran successfully.
Step 7 — Parsing JSON Results
We already made our first successful API call, but now we might want to look at the body or headers from the Http Response at the Graph API call we just made.
For this we will need to parse the JSON results brought back from the Graph API call we made.
We will add a Parse JSON step next. In the content we will need the Body from the HTTP Call we made, in the Body we have all the information about the user, we just need the Id property.
To parse the body we need to include an schema, for this we are going to use the Graph API Explorer tool to get an example payload for this call.
To access Graph Explorer you just need to navigate in a browser to https://developer.microsoft.com/en-us/graph/graph-explorer , and then login with your O365 credentials. The Graph Explorer will let you try all the available methods in an easy way without having to code anything.
Next in the Query bar on top input https://graph.microsoft.com/beta/users/{userID} and replace the whole {userID} with your O365 email. Be sure to switch to beta and make sure that the method is set to GET.
Then run the query. If everything is right you will get a Success Status Code 200 and a Response preview. Copy all the response preview.
Then go back to Flow and in the Parse JSON step click on the Use sample payload to generate schema. Paste the response preview you got from the Graph API and the step will automatically generate the schema.
TIP: In some cases some users might not have all the fields with data so the schema could start giving you some trouble and errors when running the flow. In case you get errors be sure to check the schema contents that the error is pointing out and if they have a defined type such as:
“type”:”string”or something similar, replace them with just
{}Step 8 — Getting everything together
Now that we have covered the basic steps and made our first successful API we will speed up and set the rest of the steps together to get our automated flow running.
Next we will need to make another HTTP Call to create the class team per each row in the Excel file.
For this we will repeat step 6 but with some minor changes. The method for this call is going to be POST as we are creating something and we need to send some details in the body of the call.
We are going to use the Teams method https://docs.microsoft.com/en-us/graph/api/team-post?view=graph-rest-beta. At the moment of this article the call you should include in the URI field looks like this:
https://graph.microsoft.com/beta/teamsBe sure to include the same information as we did in Step 6 for the authentication, secret, app ID and tenant ID.
Then we need to add the Class Team details in the body. This body can be modified to include more details for the Team, further in this tutorial you will learn how to customize the team. Copy this in the body section for the HTTP Call:
{
“template@odata.bind”: “https://graph.microsoft.com/beta/teamsTemplates('educationClass')",
“displayName”: “ ”,
“description”: “ Class created automatically — ”,
“owners@odata.bind”: [
“https://graph.microsoft.com/beta/users/"
]
}In this case we are creating a Class Team, in case you would like to create a PLC or Staff team, or normal team you will need to change the teamsTeamplates variable to meet your needs.
Then we will need to add the variables from the Excel, in this case the Display name will need the Class Name column from the Excel, in the description you might want to add a generic message with the Class Name too, and then the owner user ID that we parsed from the JSON. The 3 of them should be added from the dynamic content pane.
Your call at the end should look like this:
When a Team is created through Graph API, the response contains some information that we need for the following steps, such as the Team ID. For this we will need to parse the Headers from the HTTP Call we made to create the team.
It’s the same as the past Parse JSON step we did in step 7 , the only thing different is that in this case we need to select Headers for the Content field.
TIP: Be sure to select the Headers from the right call, you might get confused as there’s going to be 2 Headers to pick from.
For the schema of this step I will provide it, just paste it directly in the schema field, no need to click the use sample payload. This is the schema you should use:
{
"type": "object",
"properties": {
"client-request-id": {
"type": "string"
},
"content-type": {
"type": "string"
},
"location": {
"type": "string"
},
"cache-control": {
"type": "string"
},
"request-id": {
"type": "string"
}
}
}At the end your Parse JSON should look like this:
Now that we have both Graph API Calls we will update the Excel table with the report from the Class Teams creations so we can have some insights on when the teams were created and if there’s any errors with any of them.
For this we will add another Excel Online (Business) step. This time we will need the Add Row into a table action.
Configure the file you want to write to, it should be the Class Data file and the second empty table we created.
Then in the Class Name include a dynamic content from the loop to include the class name.
For the Teams ID there’s a little trick we will need to do. For Flow you can use Excel kind of functions and expressions to work with your data. This comes really useful in some cases as this one.
The response we got from the Parse JSON in the Create Team call has a 1 line format for the property location. It looks like this:
“Location”: “/teams(‘a1350f72-add8–4e76-a61c-a4c1e798095b’)/operations(‘151432d5–4794–4502-b124-dc1a1383a6a1’)”,The only ID we need is the first one, after the teams tag. For this we are going to get a sub-string to parse just the GUID we need for the team. Click on the teams id field and instead of picking Dynamic content from the right pane, click on the Expression tab.
This will let us write some Excel like functions. There you should type the following:
substring(body(‘Parse_Response_Headers’)?[‘location’],8,36)In the body parameter, that in my case is Parse_Response_Headers , be sure to replace it with your Parse JSON step that gets the headers from the Create Team call .
The rest of the function just sets the start and end of the substring, that should get us the full GUID from the team we have just created.
In the creation status field we also use another function, in this case a simple If function. It checks if the status code from the HTTP Call is 202 (OK) or if it´s different indicating there was an error during the creation. The function is the following:
if(equals(outputs(‘Create_Class_Team’)[‘statusCode’], 202), ‘Created’, ‘Error’ )In this case is the same as the past function, be sure to replace the Create_Class_Team with the name for your HTTP Call that creates the team.
In the creation date you can add the time to have a creation timestamp. For this just add the following function:
utcNow()Now we are ready to automatically create all the teams in our Class Data Excel File.
Bonus Step — Sending notification Emails to the Class Owners
You might want to send an email to all the teachers or Class owners for the classes you are just about to create. For this we can easily integrate with Outlook to send a simple email.
In the flow create another action in this case from the Office 365 Outlook steps, and select the Send Email action.
Configure the step with the Teacher Email, Class Name, and then customize the body of the email you will be sending. At the end it should look like this:
Step 9 — Adding students to Class Teams
The process of adding students to the created class teams is going to be similar to the steps we included for creating the teams.
First we will need another Apply to Each action using the otuput from the Get Enrolled Students Excel. This will get us the Team ID from the report file we created.
Then we will need to create another Excel Online(Busines) action but this time with the action of Get a Row. Configure the Class Data Excel file details and then we will need to add the Key Column and the Key Value .
For the Key Column select Class Name, and in the Key Value be sure to add a dynamic content for the Class Name you got from the Enrolled Students table.
Then we will need to get the UserID for the student to add it to the team. For this we will replicate our first Graph API Call using another HTTP Call with the parameters we used in step 6.
The only thing different here is that instead of the Teacher Email at the end of the URI call we need to include the Student Email.
After this call, we will need again to have a Parse JSON step as same as we did in step 6, but this time using the Body from the HTTP Call to get the userID from the student email.
Finally we will run another HTTP Call to add each student to their Class Team. For this we will add the HTTP Call and configure it with the following parameters.
We are going to use the Teams method https://docs.microsoft.com/en-us/graph/api/group-post-members?view=graph-rest-beta&tabs=javascript. At the moment of this article the call you should include in the URI field looks like this:
https://graph.microsoft.com/beta/groups/{id}/members/$refBe sure to include the same information as we did in Step 6 for the authentication, secret, app ID and tenant ID.
Replace the {id} with the Teams ID value you get from the previous step.
Then we need to add the user details in the body. . Copy this in the body section for the HTTP Call:
{
"@odata.id": "https://graph.microsoft.com/beta/directoryObjects/"
}TIP: If you get a validation error for the JSON in the body, or any parsing errors from the body, it might be caused by the @ character. To solve this simple add another @ leaving the text like this “@@odata.id”
Then at the end of the Body https call after the / add the Id you parsed from the Body of the Get UserID HTTP call for the student email.
Step 10 — Try it out!
We are done for now with our automated class team creation workflow. At the end it should look like this
Now it’s time to try it out. If you have previously ran any tests during the workflow creation process be sure to clean up everything, delete created teams, delete the rows created in the report table, etc.
To test this out click on the Test button on the right top corner and run your flow. You will start seeing the process of each of the steps in the flow
After the workflow ends running you can go and review the report table we created in the Excel to make sure the Teams were created. All of them should have a Created status and their UTC timestamp, also you will see all the Teams ID populated in the table.
You can also check that the students where added to the teams by going to the Microsoft Teams Admin panel inside the O365 admin portal. There you should see the 7 class teams and their students in each of them.
Wrapping up
As you saw in this tutorial, the Graph API is a really powerful app that provides the interaction directly to O365 functionalities from an unattended or fully automated scenario. Flow is the sticking glue that provides that easy workflow and automation without the need of advanced coding or expert technical skills.
Graph API and Flow can unlock multiple scenarios for education institutions and enterprises that are looking for reducing time, costs, and complexity of O365 related processes.
This scenario is just a base scenario that could be easily adapted to suit your institution or enterprise needs including other Graph API methods or other Flow connectors and actions.
I hope that you find this useful and that it helps you accelerate your Teams adoption and simplify your Teams life-cycle management for this back to school.
Feel free to contact me if you have any questions!
