diff --git a/CHANGELOG.md b/CHANGELOG.md index e36c6519..ffb856bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Changelog * [Changelog](#changelog) + * [2.24.0](#2240) * [2.23.2](#2232) * [2.23.1](#2231) * [2.23.0](#2230) @@ -76,6 +77,11 @@ *** +## 2.24.0 + +* [Issue #159](https://github.com/scrthq/PSGSuite/issues/159) + * Added: `Revoke-GSStudentGuardianInvitation` to revoke student guardian invitations (Classroom API) + ## 2.23.2 * Fixed logic issue with Get-GSUsageReport for reports returning no entities where errors would be thrown. Resolved by guarding against acting on `$null` values in the loop. diff --git a/PSGSuite/PSGSuite.psd1 b/PSGSuite/PSGSuite.psd1 index 11223262..5973ef22 100644 --- a/PSGSuite/PSGSuite.psd1 +++ b/PSGSuite/PSGSuite.psd1 @@ -12,7 +12,7 @@ RootModule = 'PSGSuite.psm1' # Version number of this module. - ModuleVersion = '2.23.2' + ModuleVersion = '2.24.0' # ID used to uniquely identify this module GUID = '9d751152-e83e-40bb-a6db-4c329092aaec' diff --git a/PSGSuite/Public/Classroom/Revoke-GSStudentGuardianInvitation.ps1 b/PSGSuite/Public/Classroom/Revoke-GSStudentGuardianInvitation.ps1 new file mode 100644 index 00000000..f4a94be3 --- /dev/null +++ b/PSGSuite/Public/Classroom/Revoke-GSStudentGuardianInvitation.ps1 @@ -0,0 +1,102 @@ +function Revoke-GSStudentGuardianInvitation { + <# + .SYNOPSIS + Revokes a student guardian invitation. + + .DESCRIPTION + Revokes a student guardian invitation. + + This method returns the following error codes: + + * PERMISSION_DENIED if the current user does not have permission to manage guardians, if guardians are not enabled for the domain in question or for other access errors. + * FAILED_PRECONDITION if the guardian link is not in the PENDING state. + * INVALID_ARGUMENT if the format of the student ID provided cannot be recognized (it is not an email address, nor a user_id from this API), or if the passed GuardianInvitation has a state other than COMPLETE, or if it modifies fields other than state. + * NOT_FOUND if the student ID provided is a valid student ID, but Classroom has no record of that student, or if the id field does not refer to a guardian invitation known to Classroom. + + .PARAMETER StudentId + The ID of the student whose guardian invitation is to be revoked. The identifier can be one of the following: + + * the numeric identifier for the user + * the email address of the user + + .PARAMETER InvitationId + The id field of the GuardianInvitation to be revoked. + + .PARAMETER User + The user to authenticate the request as + + .EXAMPLE + Revoke-GSStudentGuardianInvitation -StudentId aristotle@athens.edu -InvitationId $invitationId + + .EXAMPLE + Import-Csv .\Student_Guardian_List_To_Revoke.csv | Revoke-GSStudentGuardianInvitation + + Process a CSV with two columns containing headers "Student" and "Guardian" and revokes the invites accordingly, i.e. + + | StudentId | InvitationId | + |:--------------------:|:------------------:| + | aristotle@athens.edu | 198okj4k9827872177 | + | plato@athens.edu | 09120uuip21ru0ff0u | + #> + [OutputType('Google.Apis.Classroom.v1.Data.GuardianInvitation')] + [cmdletbinding(SupportsShouldProcess = $true,ConfirmImpact = "High")] + Param + ( + [parameter(Mandatory = $true,ValueFromPipelineByPropertyName = $true)] + [Alias('Student')] + [String] + $StudentId, + [parameter(Mandatory = $true,ValueFromPipelineByPropertyName = $true)] + [Alias('Invitation','InviteId','Invite')] + [String[]] + $InvitationId, + [parameter(Mandatory = $false)] + [String] + $User = $Script:PSGSuite.AdminEmail + ) + Begin { + if ($User -ceq 'me') { + $User = $Script:PSGSuite.AdminEmail + } + elseif ($User -notlike "*@*.*") { + $User = "$($User)@$($Script:PSGSuite.Domain)" + } + $serviceParams = @{ + Scope = 'https://www.googleapis.com/auth/classroom.guardianlinks.students' + ServiceType = 'Google.Apis.Classroom.v1.ClassroomService' + User = $User + } + $service = New-GoogleService @serviceParams + } + Process { + if ( -not ($StudentId -as [decimal])) { + if ($StudentId -ceq 'me') { + $StudentId = $Script:PSGSuite.AdminEmail + } + elseif ($StudentId -notlike "*@*.*") { + $StudentId = "$($StudentId)@$($Script:PSGSuite.Domain)" + } + } + foreach ($invId in $InvitationId) { + try { + if ($PSCmdlet.ShouldProcess("Revoking Guardian Invitation '$invId' for Student '$StudentId'")) { + Write-Verbose "Revoking Guardian Invitation '$invId' for Student '$StudentId'" + $body = New-Object 'Google.Apis.Classroom.v1.Data.GuardianInvitation' -Property @{ + State = "COMPLETE" + } + $request = $service.UserProfiles.GuardianInvitations.Patch($body,$StudentId,$invId) + $request.UpdateMask = "state" + $request.Execute() + } + } + catch { + if ($ErrorActionPreference -eq 'Stop') { + $PSCmdlet.ThrowTerminatingError($_) + } + else { + Write-Error $_ + } + } + } + } +} diff --git a/README.md b/README.md index 7f8a3b9f..1c137bf6 100644 --- a/README.md +++ b/README.md @@ -143,14 +143,7 @@ Update-GSSheetValue Export-GSSheet [Full CHANGELOG here](https://github.com/scrthq/PSGSuite/blob/master/CHANGELOG.md) -#### 2.23.2 +#### 2.24.0 -* Fixed logic issue with Get-GSUsageReport for reports returning no entities where errors would be thrown. Resolved by guarding against acting on `$null` values in the loop. - -#### 2.23.1 - -**This update changes the output of `Get-GSUsageReport` -- please review the output changes before updating if you have scripts that use that function!!** - -* Fixed: `Get-GSUsageReport` wasn't displaying critical report information (such as the Entity info) due to Select-Object being hardcoded. Function has been updated to parse the resulting Parameters and Entity info out to the top-level object. - * Added: `Flat` switch to specify that the parsed properties match what GAM returns, i.e. `'gmail:num_outbound_unencrypted_emails' = 6`. Normal behavior would be to parse that into an ordered dictionary, i.e. `gmail['num_outbound_unencrypted_emails'] = 6`, so that only `gmail` is seen from the top level object and all relevant report data is captured in the underlying dictionary. - * Added: `Raw` switch to allow the raw UsageReportsValue to be returned instead of parsing it out. +* [Issue #159](https://github.com/scrthq/PSGSuite/issues/159) + * Added: `Revoke-GSStudentGuardianInvitation` to revoke student guardian invitations (Classroom API)