Creating/Populating MS Teams from data

As of 28/9/2020

Some basic docs in case of unfortunate incident involving a bus.

Code/Files

File/Code in:

/afs/inf.ed.ac.uk/user/n/neilb/work/dice/actions/powershell-teams/dice

Teams.csv - Hand maintained table of: Course EUCLID Code,Team Name, Team Description,UUNs of owners (space separated),Notes (not used)

team-groupids.csv - Generated by CreateTeams.ps1 to maintain the mapping between EUCLID Code, Team Name, Internal Teams groupid. Used by PopulateTeams.ps1 to assign students to Team.

CreateTeams.ps1 - Script that given the input of Teams.csv, actually creates the Teams in MS teams, and assigns the given UUNs as owners. Generates team-groupids.csv to map between EUCLID code and MS internal team/group id.

PopulateTeams.ps1 - Does an authGET of student data from pip.inf. Goes through the list of groups in team-groupids.csv and adds the students with a matching EUCLID code to the appropriate team.

How to use

Setup

Some initial setup is required. Assuming doing this on DICE, then you need PowerShell installed:

profile.packages mEXTRA(powershell-lts-7.0.1-1.rhel.7)

Once that's available, you need to install the MicroSoft Teams module.

PS> Install-Module MicrosoftTeams -AllowPrerelease -RequiredVersion "1.1.3-preview"

Using this version as it supports some calls that other do not (yet).

Once it's installed, you don't need to do that step again.

The CreateTeams and PopulateTeams script assume you are already "connected" to Teams. Then any actions it takes it does as the person signed into Teams. To connect do:

PS> Connect-MicrosoftTeams

You'll be given a code to enter into https://login.microsoftonline.com/common/oauth2/deviceauth Once you've authenticated the PowerShell prompt will return.

Now if you don't Disconnect-MicrosoftTeams or close the shell, this seems to last for days, certainly I've gone a week on a single connection.

Running

Assuming you are running PowerShell and connected to Teams (see above), then with Teams.csv suitably populated then run

PS> ./CreateTeams.ps1

in the same directory, it will confirm the list and then create the lists and also create/update team-groupids.csv.

You can run CreateTeams more than once, subsequent runs will only create new teams not already in team-groupids.csv. It doesn't update existing teams or remove now non-existent ones. See Notes later for a bit more use case.

Whoever authenticates to the "Connect" will be an owner of the Team, along with Alex (hard coded in) and whoever is specified in the Teams.csv file.

Once the teams are created (you should see them within the Teams App), then run the PopulateTeams script

PS> ./PopulateTeams.ps1

It will do an authGET of a pip.inf URL of all the students on a course. (You may need to ask Tim to give you permission to fetch this URL).

The script will go straight into adding student UUNs to the Teams for which there is an entry in the teams-groupids.csv -> Teams.csv file. It takes a few minutes for teams with hundreds of students.

TODO - prompt for confirmation? Make adds more smart, only add new users, could also enable removal of users from teams as well. Though it wasn't thought this would be need to be scripted.

Notes

Basically works, but rough round the edges. The two scripts could certainly do with some changes to make them more useful.

Could this be completely automated? Some keytab ID to allow the authGET to run. Can we connect to a functional account straight from the PowerShell command line, rather than using the web auth?

Look at Team templates. See maths examples EDU_class?

We don't set a mailnickname for the teams. Should we?

Adding teams at a later date. After the initial creation of lists, some other courses have been added, the basic way is to just add the extra information to the Teams.csv file and re-run CreateTeams script. However sometimes the team has been created manually by Alex (or some other), and they just want the automatic population feature. To do this get the EUCLID code and name, etc from Alex as if it was a new list, add it to Teams.csv for completeness, but also (carefully) manually an entry to team-groupids.csv. The trick here being find the GroupId for the Team to put in the csv file. To be able to add the users, Alex should have already made you a Team admin, so having connected to Teams in PowerShell do:

Get-Team -user your-uun@ed.ac.uk

this will list all the Teams you are a member/owner of. Look for the GroupId of the list that needs populated, and add that string, eg b992c0440-b9fc-4a56-8ae65fg23adfoad to the corresponding EUCLID entry in team-groupids.csv. Now when you run PopulateTeams it will be able to add students taking that EUCLID code course to the correct Team.

-- NeilBrown - 28 Sep 2020