DEV Community: Mariya Frolikova

Application Calendars

Mariya Frolikova — Mon, 18 Nov 2024 10:13:48 +0000

If you're building an application that requires scheduling for venues, properties, or any resource not tied to a specific person's calendar, Cronofy’s Application Calendars offer a flexible solution. They function as dedicated calendars within the Cronofy ecosystem, allowing you to leverage Cronofy's scheduling tools without the need for a "real" mailbox as a data store.

By using Application Calendars, you can seamlessly integrate scheduling functionality for various use cases, such as booking meeting rooms, managing equipment availability, or coordinating events at specific locations. This guide will walk you through creating and managing Application Calendars, adding events, and utilizing them with Cronofy's scheduling functions, helping you extend your application's scheduling capabilities efficiently.

Creating an Application Calendar

To create an Application Calendar, you specify the application_calendar_id so it operates as an upsert operation:

Example request

POST /v1/application_calendars HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "client_id": {CLIENT_ID},
  "client_secret": {CLIENT_SECRET},
  "application_calendar_id": "my-unique-string"
}

You can then retrieve the calendar’s details as needed by using the same application_calendar_id for subsequent calls to the application_calendars endpoint. The response will include important information, such as the calendar’s access_token which is necessary for utilising Cronofy’s scheduling functionality with that calendar.

The application_calendar_id can be linked back to the meeting venue on the integrator’s side. This way, you can easily tie the Application Calendar to what it is managing availability for.

💡 The Application Calendar’s ID can be defined by the integrator and can be any string - for example, a GUID (globally unique identifier) or a numeric value.

Adding Events to Application Calendars

The process of creating events in an Application Calendar is the same as with user accounts. First, you retrieve the calendar_id via the List Calendars endpoint (you’ll need the access_token from the step above):

Example request

GET /v1/calendarsHTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

Using the calendar_id and the access_token, you can then proceed with a call to create the event:

POST /v1/calendars/{calendar_id}/events HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2024-10-26T15:30:00Z",
  "end": "2024-10-26T17:00:00Z",
  "location": {
    "description": "Board room"
  }
}

Using Application Calendars with scheduling functions

You can check an Application Calendar’s availability the same way you would with standard Cronofy accounts:

{
  "participants": [
    {
      "members": [
        { "sub": "apc_64b17fbb8090ea21640c9152" },
        { "sub": "acc_5ba21743f408617d1269ea1e" }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2024-10-25T09:00:00Z",
      "end": "2024-10-25T18:00:00Z"
    },
    {
      "start": "2024-10-26T09:00:00Z",
      "end": "2024-10-26T18:00:00Z"
    }
  ]
}

Other Cronofy functionalities that are supported by Application Calendars include:

Assigning Availability Rules and Available Periods.
Using the Availability Query to drive Real-Time Scheduling links.
Combining Cronofy’s calendar synchronisation and scheduling API with companion UI Elements.

Considerations

Because Application Calendars are hosted by Cronofy and do not have a mailbox, they are unable to send and receive invites to events. Instead, you can create the event within the Application Calendar and send a Smart Invite to any attendees, so that once accepted, the event is also created in the attendee’s calendar.

Managing calendar event changes with Push Notifications

Mariya Frolikova — Mon, 28 Oct 2024 12:06:10 +0000

Web push notifications are messages sent from an application to a user's device, even when the user is not actively browsing the site. They enable real-time communication with users, allowing websites to deliver timely updates, alerts, and personalized content. Push notifications are an effective alternative to polling, enabling the server to proactively send data to the client when new information is available, reducing unnecessary network traffic and server load.

To understand this more, lets see how Cronofy, a scheduling infrastructure layer with calendar APIs, uses push notifications to inform you once a change has occurred so that you can then call the API and retrieve the changes.

The result of this is being able to keep your view of the data up-to-date while only performing updates when there has been genuine changes to it.

Keeping your application up to date with an end user’s calendar using Push Notifications

First, if you haven’t already, create a developer account with Cronofy (it’s free for devs 💫). You can find the getting started guide for building scheduling functionality into your application which will be good context to follow along for the rest of the guide.

In order to be certain that the user’s events stay up to date in your system, you can utilise Push Notifications, Read Events, and regular weekly syncs.

Step 1. Make the Create Push Notifications Channel request in Postman.
Example request

POST /v1/channels HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "callback_url": {CALLBACK_URL},
  "filters": {
    "calendar_ids": ["cal_n23kjnwrw2_sakdnawerd3"],
    "only_managed":false}
}

Step 2. Create, move, or delete an event in Google Calendar to trigger a change notification.

Step 3. See the ‘change’ push notification come through.
Example Push Notification Request

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "change",
    "changes_since": "2024-10-23T09:24:16Z"
  },
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {
      "calendar_ids": ["cal_n23kjnwrw2_sakdnawerd3"],
      "only_managed":false
    }
  }
}

Note that ‘change’ notifications will include a changes_since parameter that can be used as the last_modified parameter for a subsequent Read Events request, allowing integrators to only have to query for data that changed since the last observed change within Cronofy.

Step 4. Run a Read Events call on the associated calendar_id to poll for the changes made that triggered the notification.
Example Request

GET /v1/events?from={FROM_DATE}&to={TO_DATE}&tzid={TZID} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

An important caveat in this context is the fact that every API will have different sync windows which will determine the balance between the frequency of your application performing sync operations (potentially impacting performance) and how current the data remains (impacting accuracy and responsiveness). In Cronofy’s case, sync windows start at 42 days in the past and ends 201 days into the future.

To avoid overloading the notification channel, a Push Notification will not be triggered when an event becomes visible due to the sync window moving. As a result, the event will not get synced unless you schedule regular polling of the calendar to catch any events moving into the sync window. To sync these events, you can set up a manual Read Events call towards the end of the sync window and catch the events far in advance. For example, a weekly request polling for events before the end of our default sync window can look like this:

GET /v1/events?from={194_days_from_today}&to={201_days_from_today}&tzid={TZID} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

When leveraging push notifications in your application, consider the frequency of running syncs to ensure full coverage of event changes are captured. In the case of building calendar push notifications, we recommend running a weekly or daily sync by carrying out a read events call for all events for the calendar. While the other steps will ensure complete coverage, this occasional full sync provides robustness.

You’ve now learnt how to utilize push notifications in the context of calendar event changes but the principals covered here can also be applied to other contexts such as profile disconnections, initial sync completion after an end-user connects their calendar to your platform for the first time, or when they submit a GDPR deletion request.