v2.32.0 release with enhancements for #229 #231 #232 and doc and test…

… updates ## 2.32.0 - 2019-09-12 * [Issue #229](#229) * Added: `Update-GSGmailLanguageSettings` and `Get-GSGmailLanguageSettings` functions to update/get a users default language settings in Gmail. * [Issue #231](#231) * Added: `Update-GSCalenderSubscription` function to updated existing calendar subscriptions. * Removed: Default values for the following parameters on `Add-GSCalendarSubscription` to prevent automatically adding notifications for new CalendarList entries (subscriptions): * `DefaultNotificationType` * `DefaultNotificationMethod` * `DefaultReminderMethod` * `DefaultReminderMinutes` * Added: `Notifications` and `Reminders` parameters to `Add-GSCalenderSubscription` and `Update-GSCalenderSubscription` * Added: `Reminders` parameter to `New-GSCalendarEvent` and `Update-GSCalendarEvent` functions to set custom reminders on calendar events. * Added: `Add-GSCalendarEventReminder` and `Add-GSCalendarNotification` helper functions. * Updated: `DisableReminder` switch parameter name on `New-GSCalendarEvent` and `Update-GSCalendarEvent` functions to `DisableDefaultReminder` to better align with what that actually effects (default reminder inheritance only, not reminder overrides). The previous parameter name has been set as an alias to maintain backwards compatibility. * Added: `RemoveAllReminders` parameter to `Update-GSCalendarEvent` to remove all custom reminders and disable calendar inheritance. * [Issue #232](#232) * Added: `Visibility` parameter on `New-GSCalendarEvent` and `Update-GSCalendarEvent` to set the visibility of a calendar event. * Miscellaneous * Forced `Type` parameter values to lower on the `Add-GSUser*` helper functions to ensure case senstive field matches whats expected. * Updated Google .NET SDKs to latest versions. * Updated and corrected a LOT of comment based function help. * Added function help tests to validate that functions contain expected help content.
SCRT-HQ · Sep 13, 2019 · c034226 · c034226
1 parent ac428db
commit c034226
Show file tree

Hide file tree

Showing 42 changed files with 838 additions and 82 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -100,11 +100,26 @@
 ## 2.32.0 - 2019-09-12
 
 * [Issue #229](https://github.com/scrthq/PSGSuite/issues/229)
-  * Added: `Update-GSGmailLanguageSettings` and `Get-GSGmailLanguageSettings` functions to update/get a user's default language settings in Gmail.
+  * Added: `Update-GSGmailLanguageSettings` and `Get-GSGmailLanguageSettings` functions to update/get a users default language settings in Gmail.
 * [Issue #231](https://github.com/scrthq/PSGSuite/issues/231)
-  * Added: `None` support to DefaultNotificationType parameter values on `Add-GSCalendarSubscription`.
+  * Added: `Update-GSCalenderSubscription` function to updated existing calendar subscriptions.
+  * Removed: Default values for the following parameters on `Add-GSCalendarSubscription` to prevent automatically adding notifications for new CalendarList entries (subscriptions):
+    * `DefaultNotificationType`
+    * `DefaultNotificationMethod`
+    * `DefaultReminderMethod`
+    * `DefaultReminderMinutes`
+  * Added: `Notifications` and `Reminders` parameters to `Add-GSCalenderSubscription` and `Update-GSCalenderSubscription`
+  * Added: `Reminders` parameter to `New-GSCalendarEvent` and `Update-GSCalendarEvent` functions to set custom reminders on calendar events.
+  * Added: `Add-GSCalendarEventReminder` and `Add-GSCalendarNotification` helper functions.
+  * Updated: `DisableReminder` switch parameter name on `New-GSCalendarEvent` and `Update-GSCalendarEvent` functions to `DisableDefaultReminder` to better align with what that actually effects (default reminder inheritance only, not reminder overrides). The previous parameter name has been set as an alias to maintain backwards compatibility.
+  * Added: `RemoveAllReminders` parameter to `Update-GSCalendarEvent` to remove all custom reminders and disable calendar inheritance.
 * [Issue #232](https://github.com/scrthq/PSGSuite/issues/232)
   * Added: `Visibility` parameter on `New-GSCalendarEvent` and `Update-GSCalendarEvent` to set the visibility of a calendar event.
+* Miscellaneous
+  * Forced `Type` parameter values to lower on the `Add-GSUser*` helper functions to ensure case senstive field matches whats expected.
+  * Updated Google .NET SDKs to latest versions.
+  * Updated and corrected a LOT of comment based function help.
+  * Added function help tests to validate that functions contain expected help content.
 
 ## 2.31.1 - 2019-08-30
 

diff --git a/PSGSuite/Public/Authentication/Get-GSToken.ps1 b/PSGSuite/Public/Authentication/Get-GSToken.ps1
@@ -1,20 +1,25 @@
 function Get-GSToken {
     <#
-    .Synopsis
+    .SYNOPSIS
     Requests an Access Token for REST API authentication. Defaults to 3600 seconds token expiration time.
 
     .DESCRIPTION
     Requests an Access Token for REST API authentication. Defaults to 3600 seconds token expiration time.
 
+    .PARAMETER Scopes
+    The list of scopes to request the token for
+
+    .PARAMETER AdminEmail
+    The email address of the user to request the token for. This is typically the Admin user.
+
     .EXAMPLE
     $Token = Get-GSToken -Scopes 'https://www.google.com/m8/feeds' -AdminEmail $User
     $headers = @{
         Authorization = "Bearer $($Token)"
         'GData-Version' = '3.0'
     }
     #>
-    Param
-    (
+    Param (
         [parameter(Mandatory = $true)]
         [Alias('Scope')]
         [ValidateNotNullOrEmpty()]

diff --git a/PSGSuite/Public/Authentication/New-GoogleService.ps1 b/PSGSuite/Public/Authentication/New-GoogleService.ps1
@@ -1,4 +1,27 @@
 function New-GoogleService {
+    <#
+    .SYNOPSIS
+    Creates a new Google Service object that handles authentication for the scopes specified
+
+    .DESCRIPTION
+    Creates a new Google Service object that handles authentication for the scopes specified
+
+    .PARAMETER Scope
+    The scope or scopes to build the service with, e.g. https://www.googleapis.com/auth/admin.reports.audit.readonly
+
+    .PARAMETER ServiceType
+    The type of service to create, e.g. Google.Apis.Admin.Reports.reports_v1.ReportsService
+
+    .PARAMETER User
+    The user to request the service for during the authentication process
+
+    .EXAMPLE
+    $serviceParams = @{
+        Scope       = 'https://www.googleapis.com/auth/admin.reports.audit.readonly'
+        ServiceType = 'Google.Apis.Admin.Reports.reports_v1.ReportsService'
+    }
+    $service = New-GoogleService @serviceParams
+    #>
     [CmdletBinding()]
     Param(
         [Parameter(Mandatory = $true,Position = 0)]

diff --git a/PSGSuite/Public/Calendar/Add-GSCalendarSubscription.ps1 b/PSGSuite/Public/Calendar/Add-GSCalendarSubscription.ps1
@@ -12,12 +12,20 @@ function Add-GSCalendarSubscription {
     .PARAMETER CalendarID
     The calendar ID of the calendar you would like to subscribe the user to
 
+    .PARAMETER ColorRgbFormat
+    Whether to use the foregroundColor and backgroundColor fields to write the calendar colors (RGB). If this feature is used, the index-based colorId field will be set to the best matching option automatically.
+
     .PARAMETER Selected
     Whether the calendar content shows up in the calendar UI. Optional. The default is False.
 
     .PARAMETER Hidden
     Whether the calendar has been hidden from the list. Optional. The default is False.
 
+    .PARAMETER Reminders
+    A list of reminders to add to this calendar.
+
+    This parameter expects a 'Google.Apis.Calendar.v3.Data.EventReminder[]' object type. You can create objects of this type easily by using the function 'Add-GSCalendarEventReminder'
+
     .PARAMETER DefaultReminderMethod
     The method used by this reminder. Defaults to email.
 
@@ -31,15 +39,20 @@ function Add-GSCalendarSubscription {
 
     Valid values are between 0 and 40320 (4 weeks in minutes).
 
+    .PARAMETER Notifications
+    A list of notifications to add to this calendar.
+
+    This parameter expects a 'Google.Apis.Calendar.v3.Data.CalendarNotification[]' object type. You can create objects of this type easily by using the function 'Add-GSCalendarNotification'
+
     .PARAMETER DefaultNotificationMethod
-    The method used to deliver the notification. Defaults to email.
+    The method used to deliver the notification.
 
     Possible values are:
     * "email" - Reminders are sent via email.
     * "sms" - Reminders are sent via SMS. This value is read-only and is ignored on inserts and updates. SMS reminders are only available for G Suite customers.
 
     .PARAMETER DefaultNotificationType
-    The type of notification. Defaults to eventChange.
+    The type of notification.
 
     Possible values are:
     * "eventCreation" - Notification sent when a new event is put on the calendar.
@@ -63,41 +76,50 @@ function Add-GSCalendarSubscription {
     [cmdletbinding()]
     Param
     (
-        [parameter(Mandatory = $true,Position = 0,ValueFromPipeline = $true,ValueFromPipelineByPropertyName = $true)]
+        [parameter(Mandatory,Position = 0,ValueFromPipeline,ValueFromPipelineByPropertyName)]
         [Alias("PrimaryEmail","UserKey","Mail")]
         [ValidateNotNullOrEmpty()]
         [String]
         $User,
-        [parameter(Mandatory = $true)]
+        [parameter(Mandatory,Position = 1)]
         [String[]]
         $CalendarId,
         [parameter(Mandatory = $false)]
         [Switch]
+        $ColorRgbFormat,
+        [parameter()]
+        [Switch]
         $Selected,
-        [parameter(Mandatory = $false)]
+        [parameter()]
         [Switch]
         $Hidden,
-        [parameter(Mandatory = $false)]
+        [parameter()]
+        [Google.Apis.Calendar.v3.Data.EventReminder[]]
+        $Reminders,
+        [parameter()]
         [ValidateSet('email','sms','popup')]
         [String]
-        $DefaultReminderMethod = 'email',
-        [parameter(Mandatory = $false)]
+        $DefaultReminderMethod,
+        [parameter()]
         [ValidateRange(0,40320)]
         [Int]
         $DefaultReminderMinutes = 30,
-        [parameter(Mandatory = $false)]
+        [parameter()]
+        [Google.Apis.Calendar.v3.Data.CalendarNotification[]]
+        $Notifications,
+        [parameter()]
         [ValidateSet('email','sms')]
         [String]
-        $DefaultNotificationMethod = 'email',
-        [parameter(Mandatory = $false)]
+        $DefaultNotificationMethod,
+        [parameter()]
         [ValidateSet('eventCreation','eventChange','eventCancellation','eventResponse','agenda')]
         [String]
-        $DefaultNotificationType = 'eventChange',
-        [parameter(Mandatory = $false)]
+        $DefaultNotificationType,
+        [parameter()]
         [ValidateSet("Periwinkle","Seafoam","Lavender","Coral","Goldenrod","Beige","Cyan","Grey","Blue","Green","Red")]
         [String]
         $Color,
-        [parameter(Mandatory = $false)]
+        [parameter()]
         [String]
         $SummaryOverride
     )
@@ -136,16 +158,32 @@ function Add-GSCalendarSubscription {
                     Selected = $Selected
                     Hidden = $Hidden
                 }
-                $DefaultReminders = New-Object 'Google.Apis.Calendar.v3.Data.EventReminder' -Property @{
-                    Method = $DefaultReminderMethod
-                    Minutes = $DefaultReminderMinutes
+                if ($PSBoundParameters.ContainsKey('Reminders')) {
+                    $body.DefaultReminders = $Reminders
+                }
+                elseif ($PSBoundParameters.ContainsKey('DefaultReminderMethod')) {
+                    $DefaultReminders = New-Object 'Google.Apis.Calendar.v3.Data.EventReminder' -Property @{
+                        Method = $DefaultReminderMethod
+                        Minutes = $DefaultReminderMinutes
+                    }
+                    $body.DefaultReminders = [Google.Apis.Calendar.v3.Data.EventReminder[]]$DefaultReminders
+                }
+                if ($PSBoundParameters.ContainsKey('Notifications')) {
+                    $body.NotificationSettings = New-Object 'Google.Apis.Calendar.v3.Data.CalendarListEntry+NotificationSettingsData' -Property @{
+                        Notifications = [Google.Apis.Calendar.v3.Data.CalendarNotification[]]$Notifications
+                    }
                 }
-                $body.DefaultReminders = [Google.Apis.Calendar.v3.Data.EventReminder[]]$DefaultReminders
-                $DefaultNotification = New-Object 'Google.Apis.Calendar.v3.Data.CalendarNotification'
-                $DefaultNotification.Method = $DefaultNotificationMethod
-                $DefaultNotification.Type = $DefaultNotificationType
-                $body.NotificationSettings = New-Object 'Google.Apis.Calendar.v3.Data.CalendarListEntry+NotificationSettingsData' -Property @{
-                    Notifications = [Google.Apis.Calendar.v3.Data.CalendarNotification[]]$DefaultNotification
+                elseif ($PSBoundParameters.ContainsKey('DefaultNotificationMethod') -or $PSBoundParameters.ContainsKey('DefaultNotificationType')) {
+                    $DefaultNotification = New-Object 'Google.Apis.Calendar.v3.Data.CalendarNotification'
+                    if ($PSBoundParameters.ContainsKey('DefaultNotificationMethod')) {
+                        $DefaultNotification.Method = $DefaultNotificationMethod
+                    }
+                    if ($PSBoundParameters.ContainsKey('DefaultNotificationType')) {
+                        $DefaultNotification.Type = $DefaultNotificationType
+                    }
+                    $body.NotificationSettings = New-Object 'Google.Apis.Calendar.v3.Data.CalendarListEntry+NotificationSettingsData' -Property @{
+                        Notifications = [Google.Apis.Calendar.v3.Data.CalendarNotification[]]$DefaultNotification
+                    }
                 }
                 foreach ($key in $PSBoundParameters.Keys) {
                     switch ($key) {
@@ -161,6 +199,9 @@ function Add-GSCalendarSubscription {
                 }
                 Write-Verbose "Subscribing user '$User' to Calendar '$($calId)'"
                 $request = $service.CalendarList.Insert($body)
+                if ($PSBoundParameters.ContainsKey('ColorRgbFormat')) {
+                    $request.ColorRgbFormat = $ColorRgbFormat
+                }
                 $request.Execute()
             }
         }

diff --git a/PSGSuite/Public/Calendar/Get-GSCalendar.ps1 b/PSGSuite/Public/Calendar/Get-GSCalendar.ps1
@@ -39,6 +39,11 @@ function Get-GSCalendar {
     To ensure client state consistency minAccessRole query parameter cannot be specified together with nextSyncToken. If the syncToken expires, the server will respond with a 410 GONE response code and the client should clear its storage and perform a full synchronization without any syncToken. Learn more about incremental synchronization.
 
     Optional. The default is to return all entries.
+
+    .EXAMPLE
+    Get-GSCalendar
+
+    Gets the list of calendar subscriptions for the AdminEmail user.
     #>
     [OutputType('Google.Apis.Calendar.v3.Data.CalendarListEntry')]
     [cmdletbinding(DefaultParameterSetName = "List")]

diff --git a/PSGSuite/Public/Calendar/Get-GSCalendarEvent.ps1 b/PSGSuite/Public/Calendar/Get-GSCalendarEvent.ps1
@@ -6,16 +6,19 @@ function Get-GSCalendarEvent {
     .DESCRIPTION
     Gets the calendar events for a user
 
-    .PARAMETER User
-    The primary email or UserID of the user. You can exclude the '@domain.com' to insert the Domain in the config or use the special 'me' to indicate the AdminEmail in the config.
-
-    Defaults to the AdminEmail in the config
+    .PARAMETER EventId
+    The Id of the event to get info for
 
     .PARAMETER CalendarId
     The calendar ID of the calendar you would like to list events from.
 
     Defaults to the user's primary calendar
 
+    .PARAMETER User
+    The primary email or UserID of the user. You can exclude the '@domain.com' to insert the Domain in the config or use the special 'me' to indicate the AdminEmail in the config.
+
+    Defaults to the AdminEmail in the config
+
     .PARAMETER Filter
     Free text search terms to find events that match these terms in any field, except for extended properties.
 
@@ -44,6 +47,12 @@ function Get-GSCalendarEvent {
     .PARAMETER SingleEvents
     Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves.
 
+    .PARAMETER PrivateExtendedProperty
+    Extended properties constraint specified as a hashtable where propertyName=value. Matches only private properties.
+
+    .PARAMETER SharedExtendedProperty
+    Extended properties constraint specified as a hashtable where propertyName=value. Matches only shared properties.
+
     .PARAMETER TimeMin
     Lower bound (inclusive) for an event's end time to filter by. If TimeMax is set, TimeMin must be smaller than timeMax.
 

diff --git a/PSGSuite/Public/Calendar/New-GSCalendarEvent.ps1 b/PSGSuite/Public/Calendar/New-GSCalendarEvent.ps1
@@ -47,7 +47,12 @@ function New-GSCalendarEvent {
     .PARAMETER EventColor
     Color of the event as seen in Calendar
 
-    .PARAMETER DisableReminder
+    .PARAMETER Reminders
+    A list of reminders to add to this calendar event other than the default calendar reminder.
+
+    This parameter expects a 'Google.Apis.Calendar.v3.Data.EventReminder[]' object type. You can create objects of this type easily by using the function 'Add-GSCalendarEventReminder'
+
+    .PARAMETER DisableDefaultReminder
     When $true, disables inheritance of the default Reminders from the Calendar the event was created on.
 
     .PARAMETER LocalStartDateTime
@@ -124,9 +129,13 @@ function New-GSCalendarEvent {
         [ValidateSet("Periwinkle","Seafoam","Lavender","Coral","Goldenrod","Beige","Cyan","Grey","Blue","Green","Red")]
         [String]
         $EventColor,
+        [parameter()]
+        [Google.Apis.Calendar.v3.Data.EventReminder[]]
+        $Reminders,
         [parameter(Mandatory = $false)]
+        [Alias('DisableReminder')]
         [Switch]
-        $DisableReminder,
+        $DisableDefaultReminder,
         [parameter(Mandatory = $false)]
         [DateTime]
         $LocalStartDateTime = (Get-Date),
@@ -194,6 +203,7 @@ function New-GSCalendarEvent {
                 if ($Attendees) {
                     $body.Attendees = [Google.Apis.Calendar.v3.Data.EventAttendee[]]$Attendees
                 }
+                $RemindersData = $null
                 foreach ($key in $PSBoundParameters.Keys) {
                     switch ($key) {
                         EventColor {
@@ -227,11 +237,17 @@ function New-GSCalendarEvent {
                                 $ExtendedProperties.Shared.Add($prop,$SharedExtendedProperties[$prop])
                             }
                         }
-                        DisableReminder {
-                            $reminder = New-Object 'Google.Apis.Calendar.v3.Data.Event+RemindersData' -Property @{
-                                UseDefault = (-not $DisableReminder)
+                        Reminders {
+                            if ($null -eq $RemindersData) {
+                                $RemindersData = New-Object 'Google.Apis.Calendar.v3.Data.Event+RemindersData'
                             }
-                            $body.Reminders = $reminder
+                            $RemindersData.Overrides = $Reminders
+                        }
+                        DisableDefaultReminder {
+                            if ($null -eq $RemindersData) {
+                                $RemindersData = New-Object 'Google.Apis.Calendar.v3.Data.Event+RemindersData'
+                            }
+                            $RemindersData.UseDefault = (-not $DisableDefaultReminder)
                         }
                         Default {
                             if ($body.PSObject.Properties.Name -contains $key) {
@@ -240,6 +256,9 @@ function New-GSCalendarEvent {
                         }
                     }
                 }
+                if ($RemindersData) {
+                    $body.Reminders = $RemindersData
+                }
                 if ($ExtendedProperties) {
                     $body.ExtendedProperties = $ExtendedProperties
                 }