Google Calendar Event ID Support

[Foggy2]

Is your feature request related to a problem? Please describe.
I am trying to implement a system where our school time tables are automatically published to Google Calendar for all users. With the added inclusion of the events being update upon room/staffing changes at the last minute.
So I am trying to determine an easy way to identify pre-existing events on a calendar and determine which classes they represent. So that details can be cross checked and updated where required.

Describe the solution you'd like
From reviewing the Google Calendar API reference. An obvious solution would be to use the customisable ID field for each event and embed a unique code that can be deciphered later on to identify the lesson/class.
Currently, the ID field is not supported by the New-GSCalendarEvent function.

EDIT: In fact as I review the API reference further. The Extended Properties is probably a better fit for my needs as it will be more flexible by allowing the use of multiple custom key/value pairs. It appears that the Get-GSCalendarEventList could also support filtering events on these key/value pairs which would be very convenient and efficient to manage locally.

So I think I could work with either but my preference in terms of flexibility would be that the Extended Properties be supported in the New-GSCalendarEvent and Get-GSCalendarEventList commands.

Describe alternatives you've considered
The alternatives for identifying events would be to match events based on other fields which could be messy but theoretically doable.
Or to locally cache the automatically generated IDs at event creation. I will be caching this data but my intention is to try and have my script be fault tolerant so that if the cache is corrupt or missing, it can re-parse all events and re-identify them. And also expire the cache periodically so that if an event differs between G-Suite and the cache it can be rectified.

[scrthq]

Hey @Foggy2 - Valid request! Let me know if I summarized it correctly:

• New-GSCalendarEvent
  • Add Id parameter
  • Add ExtendedProperties parameter
• Get-GSCalendarEventList
  • Add the following parameters for additional List filter possibilities:
    • Query (Q/Filter)
    • PrivateExtendedProperty
    • SharedExtendedProperty

[Foggy2]

@scrthq - Your summary looks good!

[scrthq]

@Foggy2 - awesome! Going to try working on it this weekend if I'm able to, I'll let you know!

Also worth noting is that I've been on sort of a quest to removed any public Get-*List functions for a while. My plan of action is to allow the function to perform either a Get or List request depending on the parameter(s) passed to it. Any existing functions like Get-GSCalendarEventList will become aliases so backwards compatibility is retained.

What this looks like specifically for Get-GSCalendarEventList is...

• The function will now be named Get-GSCalendarEvent
• Get-GSCalendarEventList will become an alias to Get-GSCalendarEvent
• An additional EventId parameter will be added to support only pulling event info for specific events.

Hopefully that's clear! Please do let me know if you have any questions/comments/concerns! The main takeaway is this will not break any scripts that leverage the existing *List function already.

[Foggy2]

That makes perfect sense! No issues from me with what you intend to do.

[scrthq]

Hey @Foggy2 - Given how the values for PrivateExtendedProperty and SharedExtendedProperty are expected, what do you feel is most natural for how they should be handled in PowerShell-land? Visually, they're key-value pairs, which in my head makes sense as a hashtable or an array of hashtables, but the parameter value type is literally an array of strings, so:

@(
	'key1=value1'
	'key2=value2'
	etc etc....
)

The 2 options that come to my mind are...

1. Accepting a hashtable or array of hashtables and converting it in the function to the appropriate type.
   • This would offer the greatest readability for someone else maintaining the script after you, but strays furthest from what Google's documentation states.
2. Accepting an array of strings and letting Google's API's handle formatting errors.
   • This would be the most true to the original API docs as far as parameter value types are concerned, but may not be as digestable.

Link for reference: https://developers.google.com/calendar/v3/reference/events/list

[Foggy2]

@scrthq - That is a good question.
Personally I like the option of using a hashtable as it is the most natural and appropriate way of working with key/value pairs in PowerShell.
It does stray a bit further away from the Google APIs specified type but I feel as though the pros outweigh the cons in this instance by keeping the PowerShell side of things as simple as possible. End users won't need to go re-inventing the wheel to come up with code to generate the required format.

Having said that, in what format would the ExtendedProperties property of an event return data? Would it be best to maintain uniformity between putting data in and getting data out?

If you do opt for the array of strings, perhaps adding some utility functions for easily parsing a hashtable to strings and vice versa is a compromise?

[scrthq]

@Foggy2 - I had a long reply to this, but then I started playing with it a bit more and this is the way I think this should go:

For Get-GSCalendarEvent, the filters for PrivateExt... and SharedExt... are fine as Hashtables since they are only applicable as filters in this scenario.

For New-GSCalendarEvent and Update-GSCalendarEvent, I'm adding in 3 parameters:

• PrivateExtendedProperties: This accepts a hashtable to allow setting directly from script
• SharedExtendedProperties: Same as PrivateExtendedProperties
• ExtendedProperties: This accepts the full data type returned by Get-GSCalendarEvent for this property, Google.Apis.Calendar.v3.Data.Event+ExtendedPropertiesData. This will allow you to Get one event with the ExtendedProperties you already want and create a new event with the same extended properties, i.e.:

$existing = Get-GSCalendarEvent -EventId lkjasdflkjasldfjlasdf
New-GSCalendarEvent -Summary "New Event" -ExtendedProperties $existing.ExtendedProperties

[scrthq]

@Foggy2 - v2.20.0 is out now with the updated! Enjoy!