From dfa4207cb3ca5b3537aa5d1e958b40f47421307f Mon Sep 17 00:00:00 2001 From: Luke Tainton Date: Sun, 22 Mar 2020 14:21:57 +0000 Subject: [PATCH] Standardise (#1) * Actually write it as a function Signed-off-by: Luke Tainton * Fix readme headers --- Import-TeamsUsers.ps1 | 53 -------------------------- Import-TeamsUsers.psm1 | 84 ++++++++++++++++++++++++++++++++++++++++++ README.md | 16 +++----- 3 files changed, 90 insertions(+), 63 deletions(-) delete mode 100644 Import-TeamsUsers.ps1 create mode 100644 Import-TeamsUsers.psm1 diff --git a/Import-TeamsUsers.ps1 b/Import-TeamsUsers.ps1 deleted file mode 100644 index cef3fac..0000000 --- a/Import-TeamsUsers.ps1 +++ /dev/null @@ -1,53 +0,0 @@ -function Import-TeamsUsers { - Param( - [parameter(Mandatory=$true,HelpMessage="Specify Group ID")] - $GroupId, - [parameter(Mandatory=$true,HelpMessage="Specify CSV file")] - $File - ) - - # Import CSV file and required module - $Users = Import-CSV $File - $UserCount = $Users | Measure-Object | Select-Object -expand count - Import-Module -Name MicrosoftTeams - - # Check Team exists - Try { - $Team = Get-Team -GroupId $GroupId - If ($Team) { - $TeamName = $Team.DisplayName - Write-Host -ForegroundColor Green "Team $TeamName exists!" - } - } Catch [System.UnauthorizedAccessException] { - # User is not authenticated - Write-Host -ForegroundColor Red "You need to authenticate to Microsoft Teams before continuing. Please run 'Connect-MicrosoftTeams' and try again." - Break - } Catch [System.Net.Http.HttpRequestException] { - # Team does not exist - Write-Host -ForegroundColor Red "Team with ID $GroupId does not exist!" - Break - } - - $Consent = Read-Host -Prompt "You are about to add $UserCount users. Are you sure? [y/N]" - If ($Consent -eq "y" -Or $Consent -eq "Y") { - $Users | ForEach-Object { - $User = $_.email - $Role = $_.role - Write-Host "Adding user $User with role $Role" - Add-TeamUser -GroupId $GroupId -Role $Role -User $User -ErrorAction SilentlyContinue - } - } Else { - Write-Host -ForegroundColor Red "Aborting." - } - -} - - -$GroupId = "" -$File = "" - -If ($GroupId -And $File) { - Import-TeamsUsers -GroupId $GroupId -File $File -} Else { - Write-Host -ForegroundColor Red "`$GroupId and/or `$File missing." -} diff --git a/Import-TeamsUsers.psm1 b/Import-TeamsUsers.psm1 new file mode 100644 index 0000000..c6c35b5 --- /dev/null +++ b/Import-TeamsUsers.psm1 @@ -0,0 +1,84 @@ +Function Import-TeamsUsers { + +<# + .SYNOPSIS + Import-TeamsUsers is a Powershell function that will enrol users from a CSV file into a given Microsoft Teams group. + + .DESCRIPTION + Import-TeamsUsers is a Powershell function that will enrol users from a CSV file into a given Microsoft Teams group. + It has two required parameters (switches): -GroupId and -File. + + .PARAMETER GroupId + Specifies the unique identified for the destination Team. This can be retrieved from Powershell by executing the Get-Team cmdlet. + + .PARAMETER File + The path to the CSV file that contains your users. Can either be an absolute path or relative path. + + .EXAMPLE + Import-TeamsUsers -GroupId "00000000-0000-0000-0000-000000000000" -File "users.csv" +#> + + Param( + [parameter(Mandatory=$true, position=0, ParameterSetName='Params', HelpMessage="Specify Group ID")] + [string]$GroupId, + [parameter(Mandatory=$true, position=1, ParameterSetName='Params', HelpMessage="Specify CSV file")] + [string]$File + ) + + Begin { + ##### IMPORT CSV FILE ##### + If ($File) { + $Users = Import-CSV $File + } Else { + Write-Host -ForegroundColor Red "CSV file not specified or does not exist." + Exit + } + + ##### CHECK MODULE IS INSTALLED AND IMPORTED ##### + if (Get-Module -ListAvailable -Name MicrosoftTeams) { + Import-Module -Name MicrosoftTeams + Connect-MicrosoftTeams + } else { + Write-Host -ForegroundColor Red "Module MicrosoftTeams doesn't exist. Please run 'Install-Module -Name MicrosoftTeams' and retry." + Exit + } + + ##### CHECK TEAM EXISTS ##### + Try { + $Team = Get-Team -GroupId $GroupId + If ($Team) { + $TeamName = $Team.DisplayName + Write-Host -ForegroundColor Green "Team $TeamName exists!" + } + } Catch [System.UnauthorizedAccessException] { + # User is not authenticated or does not have access + Write-Host -ForegroundColor Red "You do not have access to manage this team." + Exit + } Catch [System.Net.Http.HttpRequestException] { + # Team does not exist + Write-Host -ForegroundColor Red "Team with ID $GroupId does not exist." + Exit + } + + } + Process { + $UsersAdded = 0; + $UserCount = $Users | Measure-Object | Select-Object -expand count + $Consent = Read-Host -Prompt "You are about to add $UserCount users. Are you sure? [y/N]" + If ($Consent -eq "y" -Or $Consent -eq "Y") { + $Users | ForEach-Object { + $User = $_.email + $Role = $_.role + Write-Host "Adding user $User with role $Role" + If (Add-TeamUser -GroupId $GroupId -Role $Role -User $User -ErrorAction SilentlyContinue) {$global:UsersAdded++} + } + } Else { + Write-Host -ForegroundColor Red "Aborting." + Exit + } + } + + End { + Write-Host -ForegroundColor Green "$UsersAdded added successfully." + } +} diff --git a/README.md b/README.md index 6c516cb..c958330 100644 --- a/README.md +++ b/README.md @@ -3,26 +3,22 @@ A Powershell script that imports users from a CSV into a Microsoft Teams team. # Setting up your device This script runs via PowerShell. If you're on Windows, you'll already have this. If not, please download it from the [releases page](https://github.com/PowerShell/PowerShell/releases). Once you've got PowerShell: -1. Open PowerShell. +1. Open PowerShell as an administrator. 2. Allow remote scripts to execute by running `Set-ExecutionPolicy RemoteSigned`. If you don't do this, the script won't run. 3. Install the Microsoft Teams module. To do this, run `Install-Module -Name MicrosoftTeams`. Accept any prompts that you are given. # Gathering information You'll need to do a few things before you can run the script: 1. Have a CSV file with the users you want to add. This needs to be in the format `email,role`. You can copy the template if required. -2. Import the Microsoft Teams module. Run `Import-Module -Name MicrosoftTeams` in your Powershell terminal. -3. Authenticate to Microsoft Teams. Run `Connect-MicrosoftTeams` in your Powershell terminal and follow the instructions. -4. Get your group ID. Run `Get-Team -User `, substituting `` for your Office 365 email address, to list all teams you are a member of. +2. Get your group ID. Import the MS Teams module (`Import-Module -Name MicrosoftTeams`) and run `Get-Team -User `, substituting `` for your Office 365 email address, to list all teams you are a member of. # Running the script -1. Copy or move the CSV file to the same folder that the `Import-TeamsUsers.ps1` file is in. -2. Open the `Import-TeamsUsers.ps1` file. -3. Modify the `$GroupId` variable to the Group ID you found from step 4 in the section above. -4. Modify the `$File` variables to the name of your CSV file. -5. Run the script. +1. Download the repository to your PC. +2. Change directory to where you downloaded the repository and import the Import-TeamsUsers module (`Import-Module ./Import-TeamsUsers.psm1`). +3. Run `Import-TeamsUsers -GroupId -File `. # Need help? -If you require assistance running the script, please [send me an email](mailto:luke@tainton.uk?subject=I%20need%20help%20running%20Import-TeamsUsers). +If you require assistance running the script, see the help by executing `Get-Help Import-TeamsUsers` (requires importing the module first - see step 2 above). If you still need help, please [send me an email](mailto:luke@tainton.uk?subject=I%20need%20help%20running%20Import-TeamsUsers). # Issues? Want a new feature? If you're having problems with the script or have an idea for a new feature, please check [here](https://github.com/luketainton/Import-TeamsUsers/issues) to see if someone else is having the same problem, and open an issue if one doesn't already exist. If you can implement a fix or feature request, please file a pull request!