Google Calendar Activities

Google Calendar Activities

Version: 1.0.5  ·  ID: zoan-packages-googlecalendar  ·  Author: Zoan Software

The Google Calendar package creates, updates, searches and responds to events, and manages their guests, directly through Google’s API: book meetings from requests, reschedule in bulk, read the day’s agenda to prepare work or send invitations without opening the calendar.

Authentication

Everything starts with Google Calendar — Connect, which supports two modes in authType:

Mode	What you need	When it fits
oauth (default)	A Zoan Cloud Google OAuth connection authorized with the Calendar permission (https://www.googleapis.com/auth/calendar). Pass it in credential as credential("code-name"); Zoan Cloud refreshes the token for you.	The robot manages the agenda of a person or a team account.
service-account	A service account key (full JSON) stored as a credential, in serviceAccount. With impersonateUser (domain-wide delegation) it works on that Workspace user’s calendar; without it, only on calendars shared with the service account’s email.	Unattended runs with no person’s consent.

Place the other activities inside Connect’s body so they inherit the session (ZoanGoogleCalendarSession) and it closes by itself at the end.

Calendars, dates and notifications

• calendarId: primary by default, the account’s main calendar. For another calendar use its ID, which you get from Get calendars (it usually looks like an email).
• Dates: pass a DateTime directly (e.g. DateTime.Today.AddDays(1)) or ISO 8601 text (2026-06-15T14:30:00). They do not depend on the machine’s language or regional settings: they are sent to Google with an explicit offset. Since version 1.0.5.
  • A time without an offset (a plain DateTime or text without Z or -05:00) is read in the timeZone zone or, if empty, in the calendar’s zone; never in the robot machine’s zone.
  • With an offset (2026-06-15T14:30:00-05:00, a DateTimeOffset or a UTC DateTime) the exact instant is kept.
  • Text like 04/03/2026 is rejected: it is ambiguous (day/month or month/day).
• All day: with allDay = true only the date is used. In Google the end date of an all-day event is exclusive: a June 15 event goes from 2026-06-15 to 2026-06-16.
• notify: decides whether Google emails the guests on create, change or cancel. Keep it off while testing so no real invitations go out.

Event data

Create event, Update event, Get events, Get event by ID, Add attendee and Respond return each event as a Dictionary with these keys:

Key	Type	Content
id	string	Event ID. For recurring events, each occurrence has its own ID.
summary	string	Title.
description	string	Description (null if none).
location	string	Location (null if none).
start	string	Start: ISO 8601 with offset (e.g. 2026-06-15T14:30:00.0000000-05:00) or just a date (2026-06-15) for all-day events.
end	string	End, same format. For all-day events the date is exclusive (the day after the last one).
allDay	bool	true for an all-day event.
status	string	confirmed, tentative or cancelled.
organizer	string	Organizer’s email.
attendees	List	Guests: each one a Dictionary with email (string), response (string: needsAction, accepted, declined or tentative) and optional (bool). Null if the event has no guests.
htmlLink	string	Link to the event in Google Calendar.
meetLink	string	Google Meet link, if the event has one; otherwise null.

Activities

Activity	Type	Output	Description
Google Calendar — Connect	googlecalendar-connect	ZoanGoogleCalendarSession	Opens an authenticated Google Calendar session
Google Calendar — Create event	googlecalendar-create-event	Dictionary<string,object>	Creates an event on a calendar
Google Calendar — Update event	googlecalendar-update-event	Dictionary<string,object>	Updates fields of an existing event (only the ones you set)
Google Calendar — Get events	googlecalendar-get-events	List<Dictionary<string,object>>	Lists or searches events within a date range
Google Calendar — Get event by ID	googlecalendar-get-event	Dictionary<string,object>	Gets a single event by its ID
Google Calendar — Get calendars	googlecalendar-get-calendars	List<Dictionary<string,object>>	Lists the calendars the account can access
Google Calendar — Add attendee	googlecalendar-add-attendee	Dictionary<string,object>	Adds one or more guests to an event (keeps existing ones)
Google Calendar — Respond (RSVP)	googlecalendar-respond	Dictionary<string,object>	Responds to an invitation: accept, decline or tentative
Google Calendar — Delete event	googlecalendar-delete-event	—	Deletes an event from a calendar
Google Calendar — Close	googlecalendar-close	—	Closes a Google Calendar session

Google API errors

When Google rejects a call, the activity fails with a GoogleApiException whose message starts with The service calendar has thrown an exception. HttpStatusCode is … followed by Google’s text:

Code	Usual cause	What to do
NotFound	The calendarId or eventId does not exist, or the account cannot see that calendar.	Check the IDs with Get calendars and Get events.
Gone	The event was already deleted.	If you wanted it deleted, the outcome is already what you expected: catch it and continue.
BadRequest	Rejected data: end before or equal to start (The specified time range is empty), invalid guest email, unknown time zone.	Review dates, emails and timeZone.
Forbidden	The account can only read that calendar, is not the event organizer, the connection lacks the Calendar permission, or a quota was exceeded.	Use a calendar where the account can edit, or re-authorize the connection.
Unauthorized	The token is no longer valid (access revoked, connection expired).	Reconnect the connection in Zoan Cloud.
TooManyRequests	Google’s per-minute request quota was exceeded.	Wrap the activity in Retry with a delay.

Catch any of them with Try / Catch; error.Type is GoogleApiException.