4D-NetKit

GoogleCalendar Class

Overview

GoogleCalendar is the Google Calendar API client within 4D NetKit. It provides CRUD operations on calendars and events, and exposes a notifier() factory for push/pull change monitoring.

A GoogleCalendar object is accessed via the calendar property of a Google object: $google.calendar.

Properties

A GoogleCalendar object exposes the following properties:

Property	Type	Description
userId	Text	User identifier used to identify the user in Service mode. Can be the `id` or the `userPrincipalName`.

Calendars

.getCalendar()

.getCalendar( { id : Text } ) : Object

Parameters

Parameter	Type		Description
id	Text	->	ID of the calendar to retrieve. To retrieve calendar IDs, call `.getCalendars()`. If `id` is null, empty, or missing, returns the primary calendar of the currently logged-in user.
Result	Object	<-	Object containing the details of the specified calendar. For more details, see the Google Calendar API resource, or `Null` on error.

Description

.getCalendar() retrieves a specific calendar from the authenticated user’s calendar list using an id to identify the calendar, and returns an object containing details about the requested calendar.

Example

var $google : cs.NetKit.Google
var $oauth2 : cs.NetKit.OAuth2Provider
var $param; $Calendars; $myCalendar : Object

$param:={}
$param.name:="google"
$param.permission:="signedIn"
$param.clientId:="your-client-id"
$param.clientSecret:="xxxxxxxxx"
$param.redirectURI:="http://127.0.0.1:50993/authorize/"
$param.scope:=[]
$param.scope.push("https://mail.google.com/")
$param.scope.push("https://www.googleapis.com/auth/calendar")

$oauth2:=New OAuth2 provider($param)
$google:=cs.NetKit.Google.new($oauth2)

// Retrieve the entire list of calendars
$Calendars:=$google.calendar.getCalendars()

// Retrieve the first calendar in the list using its ID
$myCalendar:=$google.calendar.getCalendar($Calendars.calendars[0].id)

.getCalendars()

.getCalendars( { param : Object } ) : cs.NetKit.GoogleCalendarList

Parameters

Parameter	Type		Description
param	Object	->	Set of options to filter or refine the calendar list request (optional).
Result	cs.NetKit.GoogleCalendarList	<-	Paginated list of calendar entries; use `next()` / `previous()` to navigate pages.

Description

.getCalendars() retrieves a list of calendars that the authenticated user can access. The filtering and paging options passed in param are reflected in the returned object.

In param, you can pass the following optional properties:

Property	Type	Description
maxResults	Integer	Maximum number of calendar entries returned per page. Default is 100. Maximum is 250.
minAccessRole	Text	Minimum access role for the user in the returned calendars. Acceptable values: `"freeBusyReader"`, `"owner"`, `"reader"`, `"writer"`.
showDeleted	Boolean	Whether to include deleted calendar list entries in the result. Default is `false`.
showHidden	Boolean	Whether to show hidden entries. Default is `false`.

Example

var $google : cs.NetKit.Google
var $oauth2 : cs.NetKit.OAuth2Provider
var $param; $Calendars : Object

$param:={}
$param.name:="google"
$param.permission:="signedIn"
$param.clientId:="your-client-id"
$param.clientSecret:="xxxxxxxxx"
$param.redirectURI:="http://127.0.0.1:50993/authorize/"
$param.scope:=[]
$param.scope.push("https://mail.google.com/")
$param.scope.push("https://www.googleapis.com/auth/calendar")

$oauth2:=New OAuth2 provider($param)
$google:=cs.NetKit.Google.new($oauth2)

$Calendars:=$google.calendar.getCalendars()

Events

.createEvent()

.createEvent( event : Object { ; param : Object } ) : Object

Parameters

Parameter	Type		Description
event	Object	->	Event object to create. Only `start` and `end` properties are required. The `id` field is stripped automatically.
param	Object	->	Object containing additional creation options (optional).
Result	Object	<-	Status object with an additional `event` property containing the created GoogleEvent on success.

Description

.createEvent() creates a new calendar event.

In param, you can pass the following optional properties:

Property	Type	Description
calendarId	Text	Target calendar ID. Defaults to `"primary"`.
sendUpdates	Text	Defines who receives email notifications. Acceptable values: `"all"`, `"externalOnly"`, `"none"`.
supportsAttachments	Boolean	`true` to allow creation or modification of the `attachments` property. Defaults to `false`.

Returned object

The method returns a status object with an additional event property:

Property	Type	Description
event	Object	Event object returned by the server.
success	Boolean	See status object.
statusText	Text	See status object.
errors	Collection	See status object.

Example

var $Google:=cs.NetKit.Google.new($Oauth)
var $event; $result : Object

$event:={}
$event.summary:="Team Meeting"
$event.start:={date: Current date; time: Current time}
$event.end:={date: Current date; time: Current time+3600}
$event.attendees:=[{email: "first.lastname@gmail.com"}]
$event.description:="Description of the event"

$result:=$Google.calendar.createEvent($event)
If (Not($result.success))
  ALERT($result.statusText)
End if

.deleteEvent()

.deleteEvent( param : Object ) : Object

Parameters

Parameter	Type		Description
param	Object	->	Object containing the details of the event to delete.
Result	Object	<-	Status object.

Description

.deleteEvent() deletes an event from a specified calendar.

In param, you can pass the following properties:

Property	Type	Description
eventId	Text	Required. ID of the event to delete.
calendarId	Text	Calendar ID. If not provided or null, uses the user’s primary calendar. To retrieve calendar IDs, call `.getCalendars()`.
sendUpdates	Text	Controls which attendees receive notifications about the deletion. Acceptable values: `"all"`, `"externalOnly"`, `"none"`.

Returned object

The method returns a standard status object.

Example

var $Google:=cs.NetKit.Google.new($Oauth)

$status:=$Google.calendar.deleteEvent({eventId: $event.id})
If ($status.success)
  ALERT("Calendar event correctly deleted")
Else
  ALERT($status.statusText)
End if

.getEvent()

.getEvent( param : Object ) : cs.NetKit.GoogleEvent

Parameters

Parameter	Type		Description
param	Object	->	Object containing the necessary details to retrieve a specific event.
Result	cs.NetKit.GoogleEvent	<-	The requested event, or `Null` on error or missing required parameters.

Description

.getEvent() retrieves a specific event from a Google Calendar using its unique eventId.

In param, you can pass the following properties:

Property	Type	Description
eventId	Text	Required. The unique identifier of the event to retrieve.
calendarId	Text	Calendar identifier. If not provided, the user’s primary calendar is used.
maxAttendees	Integer	Maximum number of attendees to include in the response.
timeZone	Text	Time zone for the response, formatted as an IANA name (e.g., `"Europe/Zurich"`). Defaults to UTC.

.getEvents()

.getEvents( { param : Object } ) : cs.NetKit.GoogleEventList

Parameters

Parameter	Type		Description
param	Object	->	Object containing filters and options for retrieving calendar events (optional).
Result	cs.NetKit.GoogleEventList	<-	Paginated list of GoogleEvent instances; use `next()` / `previous()` to navigate pages.

Description

.getEvents() retrieves events on the specified calendar. If param is not provided, it returns all events from the user’s primary calendar.

In param, you can pass the following optional properties:

Property	Type	Description
calendarId	Text	Calendar identifier. If not provided, the user’s primary calendar is used.
eventTypes	Text	Specifies the types of events to return. Acceptable values: `"birthday"`, `"default"`, `"focusTime"`, `"fromGmail"`, `"outOfOffice"`, `"workingLocation"`.
iCalUID	Text	Searches for an event by its iCalendar ID.
maxAttendees	Integer	Limits the number of attendees returned per event.
top	Integer	Maximum number of events per page. Default is 250, maximum is 2500.
orderBy	Text	Sort order. Acceptable values: `"startTime"` (ascending, only when `singleEvents=true`), `"updated"`.
search	Text	Free-text search query across event fields.
showDeleted	Boolean	Whether to include deleted events (`status="cancelled"`). Defaults to `false`.
showHiddenInvitations	Boolean	Whether to include hidden invitations. Defaults to `false`.
singleEvents	Boolean	Whether to expand recurring events into single instances. Defaults to `false`.
startDateTime	Text \| Object	Filters events by start time. If set, `endDateTime` must also be provided.
endDateTime	Text \| Object	Filters events by end time. If set, `startDateTime` must also be provided.
timeZone	Text	Time zone for the response, formatted as an IANA name (e.g., `"Europe/Zurich"`). Defaults to UTC.
updatedMin	Text	Filters events based on last modification time (ISO 8601 UTC).

Example

// Get all calendars, then retrieve events from the first one
var $calendars:=$google.calendar.getCalendars()
var $myCalendar:=$calendars.calendars[0]

var $events:=$google.calendar.getEvents({calendarId: $myCalendar.id; top: 10})

.updateEvent()

.updateEvent( event : Object { ; param : Object } ) : Object

Parameters

Parameter	Type		Description
event	Object	->	Event object with updated fields. `id`, `start`, and `end` are required.
param	Object	->	Object containing additional update options (optional).
Result	Object	<-	Status object with an additional `event` property containing the updated GoogleEvent on success.

Description

.updateEvent() updates an existing calendar event.

In param, you can pass the following optional properties:

Property	Type	Description
calendarId	Text	Calendar ID. Defaults to `"primary"`.
sendUpdates	Text	Defines who receives email notifications about the update. Acceptable values: `"all"`, `"externalOnly"`, `"none"`.
supportsAttachments	Boolean	`true` to allow modification of the `attachments` property. Defaults to `false`.
fullUpdate	Boolean	If `true`, the full event is replaced (PUT). If `false` (default), only specified fields are updated (PATCH).

Returned object

The method returns a status object with an additional event property:

Property	Type	Description
event	Object	Updated event object returned by the server.
success	Boolean	See status object.
statusText	Text	See status object.
errors	Collection	See status object.

Example

#DECLARE($eventId : Text)
var $Google:=cs.NetKit.Google.new($Oauth)
var $event; $result : Object

$event:={}
$event.id:=$eventId
$event.summary:="Updated Event Title"
$event.description:="Updated Event description"
$event.start:={date: Current date; time: Current time}
$event.end:={date: Current date; time: Current time+3600}

$result:=$Google.calendar.updateEvent($event)
If (Not($result.success))
  ALERT($result.statusText)
End if

Notifications

.notifier()

.notifier( param : Object { ; calendarId : Text } ) : cs.NetKit.GoogleNotification

Parameters

Parameter	Type		Description
param	Object	->	Callback and mode definitions (see below).
calendarId	Text	->	(optional) Subscribe to changes in that specific calendar. If omitted, subscribe to the default (primary) calendar.
Result	cs.NetKit.GoogleNotification	<-	Notification object with `start()`, `stop()`, `expiration`, and `isStarted`. Call `start()` to begin monitoring.

Description

.notifier() creates and returns a GoogleNotification object allowing you to configure, start, and stop subscriptions to calendar event change notifications.

Two modes are available:

Push (webhook): Real-time notifications via HTTP callbacks. Requires a publicly accessible HTTPS endpoint. The webhook URL is derived as {endPoint}/4dnk-google-notification?state={uuid}.
Pull (polling): Periodic polling of change APIs. No external endpoint needed. Polls the delta query API at the configured interval.

When a resource changes, user-defined callbacks are dispatched in the 4D worker where the notifier’s start() function was originally called.

In param, you can pass the following properties:

Property	Type	Description
endPoint	Text	Webhook URL for push mode. If omitted, uses pull mode. Must be a publicly accessible HTTPS endpoint.
onCreate	4D.Function	Callback for a calendar event creation (optional).
onDelete	4D.Function	Callback for a calendar event deletion (optional).
onModify	4D.Function	Callback for a calendar event modification (optional).
timer	Integer	Polling interval in seconds for pull mode (default: 30) (optional).

Callback functions receive two parameters:

Parameter	Type	Description
google	cs.NetKit.Google	The current Google object.
event	Object	Object with `type` (Text: `"eventCreated"`, `"eventDeleted"`, or `"eventModified"`) and `ids` (Collection of affected event IDs).

Returned object

The returned GoogleNotification object contains the following properties:

Property	Type	Description
endPoint	Text	Publicly accessible HTTPS endpoint that receives notifications.
expiration	Text	Expiration date and time (timestamp). Read-only.
isStarted	Boolean	`true` when notifications are active, `false` when stopped. Read-only.
start()	4D.Function	Starts the subscription. Returns a status object (`success`, `statusText`, `errors`).
stop()	4D.Function	Stops the subscription. Returns a status object (`success`, `statusText`, `errors`).
timer	Integer	Interval in seconds between delta query checks (pull mode).

`endPoint` management

Using an endPoint, you let Google call your application whenever a change occurs:

$parameter.endPoint:="https://mydomain.com/notifications"

If the endPoint port is the same as the host port, the host web server is used automatically.
If no port is specified, standard ports (80 for HTTP, 443 for HTTPS) are used.
In any other case, the 4D NetKit component web server is used.

When the endPoint uses the host web server, add the following entry to Project/Sources/HTTPHandlers.json:

[
  {
    "class": "NetKit.GoogleNotificationHandler",
    "method": "getResponse",
    "regexPattern": "/4dnk-google-notification",
    "verbs": "post"
  }
]

If both a calendar.notifier and a mail.notifier are declared, they must use the same port.

Example

Calendar notifications via delta polling every 60 seconds (pull mode):

var $provider:=SignedInProvider()
var $google:=cs.NetKit.Google.new($provider)
var $notification:={}

$notification.onCreate:=Formula(ALERT("You have a new event!"))
$google.calendar.notifier($notification; "primary").start()

Status object

Several GoogleCalendar functions return a status object containing the following properties:

Property	Type	Description
success	Boolean	`true` if the operation was successful.
statusText	Text	Status message returned by the Google server or last error from the 4D error stack.
errors	Collection	Collection of 4D error items (not returned if a server response is received): `errcode`, `message`, `componentSignature`.

4D-NetKit

GoogleCalendar Class

Overview

Table of Contents

Calendars

Events

Notifications

Properties

Calendars

.getCalendar()

Parameters

Description

Example

.getCalendars()

Parameters

Description

Example

Events

.createEvent()

Parameters

Description

Returned object

Example

.deleteEvent()

Parameters

Description

Returned object

Example

.getEvent()

Parameters

Description

.getEvents()

Parameters

Description

Example

.updateEvent()

Parameters

Description

Returned object

Example

Notifications

.notifier()

Parameters

Description

Returned object

endPoint management

Example

Status object

See also

`endPoint` management