pushing updates for v2.21.0

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 * [Changelog](#changelog)
+  * [2.21.0](#2210)
   * [2.20.2](#2202)
   * [2.20.1](#2201)
   * [2.20.0](#2200)
@@ -64,6 +65,15 @@
 
 ***
 
+## 2.21.0
+
+* [PR #130](https://github.com/scrthq/PSGSuite/pull/130) / [Issue #129](https://github.com/scrthq/PSGSuite/issues/129)
+  * Added: Support for UserRelations management in `New-GSUser -Relations $relations` and `Update-GSUser -Relations $relations` via `Add-GSUserRelation` helper function. - _Thanks, [@mattwoolnough](https://github.com/mattwoolnough)!_
+  * Added: Logic to `Update-GSUser` to enable clearing of all values for user properties `Phones`, `ExternalIds`, `Organizations`, and `Relations` by REST API call via passing `$null` as the value when calling `Update-GSUser`. - _Thanks, [@mattwoolnough](https://github.com/mattwoolnough)!_
+* [Issue #129](https://github.com/scrthq/PSGSuite/issues/129)
+  * Fixed: Documentation for `Get-GSSheetInfo` around the `Fields` parameter.
+  * Added: Additional correction of casing for `Fields` values in `Get-GSSheetInfo` so that it will always submit the values using the correct case, even if providing the incorrect case as the value to the parameter.
+
 ## 2.20.2
 
 * [Issue #120](https://github.com/scrthq/PSGSuite/issues/120)

PSGSuite/PSGSuite.psd1

@@ -12,7 +12,7 @@
     RootModule            = 'PSGSuite.psm1'
 
     # Version number of this module.
-    ModuleVersion         = '2.20.2'
+    ModuleVersion         = '2.21.0'
 
     # ID used to uniquely identify this module
     GUID                  = '9d751152-e83e-40bb-a6db-4c329092aaec'

PSGSuite/Public/Helpers/Add-GSUserRelation.ps1

@@ -6,16 +6,34 @@ function Add-GSUserRelation {
     .DESCRIPTION
     Builds a Relation object to use when creating or updating a User
 
-    .PARAMETER CustomType
-    If the external ID type is custom, this property holds the custom type
-
     .PARAMETER Type
-    The type of the organization.
+    The type of relation.
 
-    If using a CustomType
+    Acceptable values are:
+    * "admin_assistant"
+    * "assistant"
+    * "brother"
+    * "child"
+    * "custom"
+    * "domestic_partner"
+    * "dotted_line_manager"
+    * "exec_assistant"
+    * "father"
+    * "friend"
+    * "manager"
+    * "mother"
+    * "parent"
+    * "partner"
+    * "referred_by"
+    * "relative"
+    * "sister"
+    * "spouse"
 
     .PARAMETER Value
-    The value of the ID
+    The name of the person the user is related to.
+
+    .PARAMETER CustomType
+    If the value of `Type` is `custom`, this property contains the custom type.
 
     .PARAMETER InputObject
     Used for pipeline input of an existing UserExternalId object to strip the extra attributes and prevent errors
@@ -37,16 +55,17 @@ function Add-GSUserRelation {
     Param
     (
         [Parameter(Mandatory = $false, ParameterSetName = "Fields")]
-        [String]
-        $CustomType,
-        [Parameter(Mandatory = $false, ParameterSetName = "Fields")]
+        [ValidateSet("admin_assistant","assistant","brother","child","custom","domestic_partner","dotted_line_manager","exec_assistant","father","friend","manager","mother","parent","partner","referred_by","relative","sister","spouse")]
         [String]
         $Type,
         [Parameter(Mandatory = $false, ParameterSetName = "Fields")]
         [String]
         $Value,
         [Parameter(Mandatory = $false, ParameterSetName = "Fields")]
         [String]
+        $CustomType,
+        [Parameter(Mandatory = $false, ParameterSetName = "Fields")]
+        [String]
         $ETag,
         [Parameter(Mandatory = $false, ValueFromPipeline = $true, ParameterSetName = "InputObject")]
         [Google.Apis.Admin.Directory.directory_v1.Data.UserRelation[]]
@@ -60,8 +79,9 @@ function Add-GSUserRelation {
             'ETag'
         )
         if ($PSBoundParameters.Keys -contains 'CustomType') {
-            $PSBoundParameters['Type'] = 'CUSTOM'
+            $PSBoundParameters['Type'] = 'custom'
         }
+        $PSBoundParameters['Type'] = $PSBoundParameters['Type'].ToString().ToLower()
     }
     Process {
         try {

PSGSuite/Public/Sheets/Get-GSSheetInfo.ps1

@@ -2,45 +2,45 @@ function Get-GSSheetInfo {
     <#
     .SYNOPSIS
     Gets metadata about a SpreadSheet
-    
+
     .DESCRIPTION
     Gets metadata about a SpreadSheet
-    
+
     .PARAMETER SpreadsheetId
     The unique Id of the SpreadSheet to retrieve info for
-    
+
     .PARAMETER User
     The owner of the SpreadSheet
-    
+
     .PARAMETER SheetName
     The name of the Sheet to retrieve info for
-    
+
     .PARAMETER Range
     The specific range of the Sheet to retrieve info for
-    
+
     .PARAMETER IncludeGridData
     Whether or not to include Grid Data in the response
-    
+
     .PARAMETER Fields
     The fields to return in the response
 
     Available values are:
-    * "NamedRanges"
-    * "Properties"
-    * "Sheets"
-    * "SpreadsheetId"
-    
+    * "namedRanges"
+    * "properties"
+    * "sheets"
+    * "spreadsheetId"
+
     .PARAMETER Raw
     If $true, return the raw response, otherwise, return a flattened response for readability
-    
+
     .EXAMPLE
     Get-GSSheetInfo -SpreadsheetId '1rhsAYTOB_vrpvfwImPmWy0TcVa2sgmQa_9u976'
 
     Gets the info for the SpreadSheet provided
     #>
     [cmdletbinding()]
     Param
-    (      
+    (
         [parameter(Mandatory = $true)]
         [String]
         $SpreadsheetId,
@@ -99,7 +99,7 @@ function Get-GSSheetInfo {
                 $request.Ranges = [Google.Apis.Util.Repeatable[String]]::new([String[]]$Range)
             }
             if ($Fields) {
-                $request.Fields = "$($Fields -join ",")"
+                $request.Fields = "$(($Fields | ForEach-Object {$f = $_;@("namedRanges","properties","sheets","spreadsheetId") | Where-Object {$_ -eq $f}}) -join ",")"
             }
             elseif ($PSBoundParameters.Keys -contains 'IncludeGridData') {
                 $request.IncludeGridData = $IncludeGridData
@@ -124,4 +124,4 @@ function Get-GSSheetInfo {
             }
         }
     }
-}
+}

PSGSuite/Public/Users/Update-GSUser.ps1

@@ -48,16 +48,29 @@ function Update-GSUser {
 
     This parameter expects a 'Google.Apis.Admin.Directory.directory_v1.Data.UserExternalId[]' object type. You can create objects of this type easily by using the function 'Add-GSUserExternalId'
 
+    To CLEAR all values for a user, pass `$null` as the value for this parameter.
+
     .PARAMETER Organizations
     The organization objects of the user
 
     This parameter expects a 'Google.Apis.Admin.Directory.directory_v1.Data.UserOrganization[]' object type. You can create objects of this type easily by using the function 'Add-GSUserOrganization'
 
+    To CLEAR all values for a user, pass `$null` as the value for this parameter.
+
+    .PARAMETER Relations
+    A list of the user's relationships to other users.
+
+    This parameter expects a 'Google.Apis.Admin.Directory.directory_v1.Data.UserRelation[]' object type. You can create objects of this type easily by using the function 'Add-GSUserRelation'
+
+    To CLEAR all values for a user, pass `$null` as the value for this parameter.
+
     .PARAMETER Phones
     The phone objects of the user
 
     This parameter expects a 'Google.Apis.Admin.Directory.directory_v1.Data.UserPhone[]' object type. You can create objects of this type easily by using the function 'Add-GSUserPhone'
 
+    To CLEAR all values for a user, pass `$null` as the value for this parameter.
+
     .PARAMETER IncludeInGlobalAddressList
     Indicates if the user's profile is visible in the G Suite global address list when the contact sharing feature is enabled for the domain. For more information about excluding user profiles, see the administration help center: http://support.google.com/a/bin/answer.py?answer=1285988
 
@@ -198,6 +211,7 @@ function Update-GSUser {
                 $body = New-Object 'Google.Apis.Admin.Directory.directory_v1.Data.User'
                 $name = New-Object 'Google.Apis.Admin.Directory.directory_v1.Data.UserName'
                 $nameUpdated = $false
+                $toClear = @{}
                 foreach ($prop in $PSBoundParameters.Keys | Where-Object {$body.PSObject.Properties.Name -contains $_ -or $name.PSObject.Properties.Name -contains $_}) {
                     switch ($prop) {
                         PrimaryEmail {
@@ -241,32 +255,52 @@ function Update-GSUser {
                             $body.Emails = $emailList
                         }
                         ExternalIds {
-                            $extIdList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserExternalId]'
-                            foreach ($extId in $ExternalIds) {
-                                $extIdList.Add($extId)
+                            if ($null -ne $ExternalIds) {
+                                $extIdList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserExternalId]'
+                                foreach ($extId in $ExternalIds) {
+                                    $extIdList.Add($extId)
+                                }
+                                $body.ExternalIds = $extIdList
+                            }
+                            else {
+                                $toClear['externalIds'] = $null
                             }
-                            $body.ExternalIds = $extIdList
                         }
                         Organizations {
-                            $orgList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserOrganization]'
-                            foreach ($organization in $Organizations) {
-                                $orgList.Add($organization)
+                            if ($null -ne $Organizations) {
+                                $orgList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserOrganization]'
+                                foreach ($organization in $Organizations) {
+                                    $orgList.Add($organization)
+                                }
+                                $body.Organizations = $orgList
+                            }
+                            else {
+                                $toClear['organizations'] = $null
                             }
-                            $body.Organizations = $orgList
                         }
                         Relations {
-                            $relList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserRelation]'
-                            foreach ($relation in $Relations) {
-                                $relList.Add($relation)
+                            if ($null -ne $Relations) {
+                                $relList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserRelation]'
+                                foreach ($relation in $Relations) {
+                                    $relList.Add($relation)
+                                }
+                                $body.Relations = $relList
+                            }
+                            else {
+                                $toClear['relations'] = $null
                             }
-                            $body.Relations = $relList
                         }
                         Phones {
-                            $phoneList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserPhone]'
-                            foreach ($phone in $Phones) {
-                                $phoneList.Add($phone)
+                            if ($null -ne $Relations) {
+                                $phoneList = New-Object 'System.Collections.Generic.List`1[Google.Apis.Admin.Directory.directory_v1.Data.UserPhone]'
+                                foreach ($phone in $Phones) {
+                                    $phoneList.Add($phone)
+                                }
+                                $body.Phones = $phoneList
+                            }
+                            else {
+                                $toClear['phones'] = $null
                             }
-                            $body.Phones = $phoneList
                         }
                         IsAdmin {
                             if ($userObj.IsAdmin -eq $PSBoundParameters[$prop]) {
@@ -293,6 +327,14 @@ function Update-GSUser {
                 }
                 $request = $service.Users.Update($body, $userObj.Id)
                 $request.Execute() | Add-Member -MemberType NoteProperty -Name 'User' -Value $U -PassThru
+                if ($toClear.Keys.Count) {
+                    $header = @{
+                        Authorization = "Bearer $(Get-GSToken -Scopes "https://www.googleapis.com/auth/admin.directory.user" -Verbose:$false)"
+                    }
+                    $uri = [Uri]"https://www.googleapis.com/admin/directory/v1/users/$U"
+                    Write-Verbose "Clearing out all values for User '$U' on the following properties: [ $($toClear.Keys -join ", ") ]"
+                    $null = Invoke-RestMethod -Method Put -Uri $uri -Headers $header -Body $($toClear | ConvertTo-Json -Depth 5 -Compress) -ContentType 'application/json' -Verbose:$false -ErrorAction Stop
+                }
             }
             catch {
                 if ($ErrorActionPreference -eq 'Stop') {
@@ -304,4 +346,4 @@ function Update-GSUser {
             }
         }
     }
-}
+}

README.md

@@ -131,9 +131,18 @@ Update-GSSheetValue               Export-GSSheet
 
 ### Most recent changes
 
+#### 2.21.0
+
+* [PR #130](https://github.com/scrthq/PSGSuite/pull/130) / [Issue #129](https://github.com/scrthq/PSGSuite/issues/129)
+  * Added: Support for UserRelations management in `New-GSUser -Relations $relations` and `Update-GSUser -Relations $relations` via `Add-GSUserRelation` helper function. - _Thanks, [@mattwoolnough](https://github.com/mattwoolnough)!_
+  * Added: Logic to `Update-GSUser` to enable clearing of all values for user properties `Phones`, `ExternalIds`, `Organizations`, and `Relations` by REST API call via passing `$null` as the value when calling `Update-GSUser`. - _Thanks, [@mattwoolnough](https://github.com/mattwoolnough)!_
+* [Issue #129](https://github.com/scrthq/PSGSuite/issues/129)
+  * Fixed: Documentation for `Get-GSSheetInfo` around the `Fields` parameter.
+  * Added: Additional correction of casing for `Fields` values in `Get-GSSheetInfo` so that it will always submit the values using the correct case, even if providing the incorrect case as the value to the parameter.
+
 #### 2.20.2
 
-* [Issue #120](https://github.com/scrthq/PSGSuite/issues/120)
+* [Issue #128](https://github.com/scrthq/PSGSuite/issues/128)
   * Added: `Update-GSMobileDevice` to allow taking action on Mobile Devices
   * Fixed: Bug in `Remove-GSMobileDevice` with incorrect variable name