4D-NetKit

Office365Calendar Class

Overview

Office365Calendar is the Microsoft Graph API client for calendar and event management within 4D NetKit. It supports reading, creating, updating, and deleting calendars and events, with optional calendarId and userId scoping.

An Office365Calendar object is accessed via the calendar property of an Office365 object: $office365.calendar.

Event date/time values are accepted as ISO text, {date; time} objects, or Graph {dateTime; timeZone} objects.

Table of Contents

Calendars

Events

Notifications

Properties

An Office365Calendar object exposes the following properties:

Property Type Description
userId Text User identifier used in Service mode. Can be the id or the userPrincipalName.
id Text Calendar identifier. When set, all operations target this specific calendar by default.

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 properties and relationships of the specified calendar, or Null on failure.

Description

.getCalendar() retrieves the properties and relationships of a specific calendar.

Example

var $oAuth2 : cs.NetKit.OAuth2Provider
var $Office365 : cs.NetKit.Office365
var $params; $calendarList; $calendarA : Object

$params:=New object
$params.name:="Microsoft"
$params.permission:="signedIn"
$params.clientId:="your-client-id"
$params.redirectURI:="http://127.0.0.1:50993/authorize/"
$params.scope:="https://graph.microsoft.com/.default"

$oAuth2:=New OAuth2 provider($params)
$Office365:=New Office365 provider($oAuth2)

// Retrieve the entire list of calendars
$calendarList:=$Office365.calendar.getCalendars()

// Retrieve the first calendar in the list using its ID
$calendarA:=$Office365.calendar.getCalendar($calendarList.calendars[0].id)

.getCalendars()

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

Parameters

Parameter Type   Description
param Object -> Set of options to filter, order, or select specific calendar properties (optional).
Result cs.NetKit.GraphCalendarList <- Paginated list of calendar objects. Use next() / previous() to navigate pages.

Description

.getCalendars() retrieves a collection of the user’s calendars.

In param, you can pass the following optional properties:

Property Type Description
select Text Specifies which calendar properties to retrieve. Comma-separated values.
orderby Text Specifies the order of the returned results. Syntax: property name followed by asc or desc.
filter Text OData filter expression to filter the results. Example: "name eq 'Work'".

Example

var $oAuth2 : cs.NetKit.OAuth2Provider
var $Office365 : cs.NetKit.Office365
var $params; $calendarList : Object

$params:=New object
$params.name:="Microsoft"
$params.permission:="signedIn"
$params.clientId:="your-client-id"
$params.redirectURI:="http://127.0.0.1:50993/authorize/"
$params.scope:="https://graph.microsoft.com/.default"

$oAuth2:=New OAuth2 provider($params)
$Office365:=New Office365 provider($oAuth2)

$calendarList:=$Office365.calendar.getCalendars()

Events

.createEvent()

.createEvent( event : Object ) : Object

Parameters

Parameter Type   Description
event Object -> Object containing the details of the calendar event to create.
Result Object <- Status object with an additional event property.

Description

.createEvent() creates a new calendar event.

In event, pass the properties you want to set. See GraphEvent for the full list of available properties. Attachments in event.attachments are uploaded separately after event creation.

Returned object

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

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

Permissions

Type Permission
Delegated (Work/School) Calendars.ReadWrite
Delegated (Personal) Calendars.ReadWrite
Application Calendars.ReadWrite

Example

var $oAuth2 : cs.NetKit.OAuth2Provider
var $Office365 : cs.NetKit.Office365
var $event; $result : Object

$Office365:=New Office365 provider($oAuth2)

$event:={}
$event.subject:="Team Sync"
$event.start:={date: Current date; time: Current time}
$event.end:={date: Current date; time: Current time+3600}
$event.attendees:=[{emailAddress: {address: "colleague@example.com"}}]

$result:=$Office365.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 details for the calendar event to delete.
Result Object <- Status object.

Description

.deleteEvent() deletes a calendar event.

In param, you can pass the following properties:

Property Type Description
eventId Text Required. ID of the event to delete.
calendarId Text ID of the calendar. If not provided, the primary calendar of the currently logged-in user is used.

Returned object

The method returns a standard status object.

Permissions

Type Permission
Delegated (Work/School) Calendars.ReadWrite
Delegated (Personal) Calendars.ReadWrite
Application Calendars.ReadWrite

Example

$status:=$office365.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.GraphEvent

Parameters

Parameter Type   Description
param Object -> Object containing the necessary details to retrieve a specific event.
Result cs.NetKit.GraphEvent <- The requested GraphEvent, or Null when not found or on error.

Description

.getEvent() retrieves details of a specific event, including its properties and relationships. The event is identified by its unique eventId within the specified calendar.

In param, you can pass the following properties:

Property Type Description
eventId Text Required. The unique identifier of the event.
calendarId Text Calendar identifier. If not provided, the user’s primary calendar is used.
timeZone Text Time zone for the response (IANA format). UTC by default.
select Text OData $select — comma-separated list of properties to return.

.getEvents()

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

Parameters

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

Description

.getEvents() retrieves events from a specified calendar. By default, events are pulled from the user’s primary calendar unless another calendar is specified.

Note: If no time range is provided, it returns single-instance meetings and series masters. When both startDateTime and endDateTime are specified, it retrieves all occurrences, exceptions, and single-instance events within the defined time range.

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.
startDateTime Text, Object Filters events by start time. If set, endDateTime must also be provided. Text: ISO 8601 UTC timestamp. Object: Must contain date (date type) and time (time type).
endDateTime Text, Object Filters events by end time. If set, startDateTime must also be provided.
timeZone Text Time zone for the response (IANA format). UTC by default.
select Text Specifies which event properties to return (OData $select).
orderby Text Defines sorting order for results (OData $orderby).
filter Text OData filter expression. Example: "status eq 'confirmed'".
top Integer Maximum number of events per page. Default is 10. Maximum is 999.

Example

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

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

.updateEvent()

.updateEvent( event : Object ) : Object

Parameters

Parameter Type   Description
event Object -> Object containing the updated event properties. The id property is mandatory.
Result Object <- Status object with an additional event property.

Description

.updateEvent() updates an existing calendar event.

In event, pass the event id (mandatory) and the properties you want to update. You only need to include the fields you want to change — any property left out will keep its current value. Attachments in event.attachments are uploaded separately after the update.

Returned object

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

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

Permissions

Type Permission
Delegated (Work/School) Calendars.ReadWrite
Delegated (Personal) Calendars.ReadWrite
Application Calendars.ReadWrite

Example

#DECLARE($eventId : Text)
var $Office365:=New Office365 provider($oAuth2)
var $event; $result : Object

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

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

Notifications

.notifier()

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

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 calendar.
Result cs.NetKit.GraphNotification <- Notification object with start(), stop(), expiration, and isStarted. Call start() to begin monitoring.

Description

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

Two modes are available:

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. See endPoint management.
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
office365 cs.NetKit.Office365 The current Office365 object.
event Object Object with type (Text: "eventCreated", "eventDeleted", or "eventModified") and ids (Collection of affected event IDs).

Returned object

The returned GraphNotification 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 Microsoft call your application whenever a change occurs:

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

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

[
  {
    "class": "NetKit.GraphNotificationHandler",
    "method": "getResponse",
    "regexPattern": "/4dnk-graph-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):

$calNotif:=$office365.calendar.notifier({ \
    timer: 60; \
    onCreate: Formula(handleNewEvent($1; $2)); \
    onModify: Formula(handleEventUpdate($1; $2)) \
})
$status:=$calNotif.start()

// Stop monitoring
$status:=$calNotif.stop()

Status object

Several Office365Calendar 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 Microsoft 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.

See also

This site is open source. Improve this page.