Connecting Google Calendar to a scheduling application involves more than displaying external events. Your app needs to obtain users’ authorization to access their calendars, handle differences in event formats, and ensure that edits in your app reach Google Calendar. <\/p>\n
The DHTMLX scheduler-google-calendar-demo<\/a> demonstrates how to integrate DHTMLX Scheduler<\/a> with a user\u2019s Google calendar using a Node.js and Express server that handles OAuth 2.0. The official integration guide<\/a> covers setup step by step. This article focuses on the architecture: how authentication works, how events are mapped, how edits reach Google, and how recurring events are handled. At the end, you\u2019ll find instructions on how to run the demo locally. <\/p>\n Before adapting the integration to your own solution, it is important to understand how events move between Scheduler and Google Calendar. The demo syncs data in both directions, but each flow works differently: <\/p>\n The demo does not register webhooks to detect changes made in Google Calendar. These changes appear in Scheduler only after a page refresh or when the user navigates to a date range that Scheduler has not yet loaded. So the integration relies on explicit API requests rather than push updates from Google Calendar Scheduler. <\/p>\n Now, we need to clarify how the application obtains permission to access calendars and protects its API routes.<\/p>\n The app uses OAuth 2.0 to request permission to access a user\u2019s Google Calendar. The demo uses OAuth for Google Calendar access, handling the authentication process with Passport and the passport-google-oauth20 strategy.<\/p>\n The following route configuration in auth.route.ts<\/a> starts the Google Calendar sign-in flow:<\/p>\n The scope option defines which permissions the app asks the user for. The https:\/\/www.googleapis.com\/auth\/calendar scope gives the app full access to the user’s calendars, so it can list calendars and read, create, update, and delete events. The profile and email scopes give access to the user’s name and email address. <\/p>\n Two authentication settings are also relevant. accessType: “offline”<\/strong> requests a refresh token alongside the short-lived access token. prompt: “consent”<\/strong> displays the consent screen even if the user has already authorized the app. Without prompt: “consent”<\/strong>, Google Calendar may issue a refresh token only on the first authorization, which can lead to a missing refresh token on subsequent sign-ins. <\/p>\n When Google redirects back, Passport attaches both tokens to the user object, and serializeUser\/deserializeUser<\/strong> put that object into the session as is. Our demo does not use a database for user data or tokens. We intentionally keep this implementation simple, but a production system would normally store tokens securely in persistent storage and handle token rotation and revocation. <\/p>\n The \/events<\/strong> endpoint routes are protected by a small middleware in server\/index.ts<\/a>. Requests without an authenticated session receive a 401 response instead of reaching the route handlers.<\/p>\n While your consent configuration has the Testing publishing status, sign-in works only for accounts you explicitly listed as testers. Moving to Production status requires Google’s verification process.<\/p>\n Let’s see how the stored credentials are used to make actual Google Calendar API calls.<\/p>\n With tokens stored in the session, each outgoing request to Google carries them. The googleService.ts<\/a> source file contains the server-side implementation of the JavaScript Google Calendar API integration, using the googleapis library to make requests.<\/p>\n For every operation, the oauthClent()<\/strong> function creates a new OAuth2 client using OAuth2 client out of the session tokens and passes this client into the appropriate Calendar API v3 method:<\/p>\n Two things in this snippet are easy to miss. If the browser does not specify a calendar, the entry lands in the account’s primary one. The conferenceDataVersion: 1 option<\/strong> enables support for conference data, including Google Meet details. Without it, the API silently ignores any conference data in the request. <\/p>\n Because the refresh token is passed to the client object, Google’s library can renew an expired access token on its own. A new client is created for each API call and the refreshed access token is not saved back to the session. The updated token is not retained by the app, therefore, a subsequent request may need to refresh the access token again.<\/p>\n Now, we can proceed to the next step focused on how Scheduler communicates with the server. <\/p>\n The server exposes four REST endpoints that match the request and response format Scheduler’s DataProcessor expects:<\/p>\n The tid<\/strong> value returned after creation may look like a minor detail, but subsequent updates and deletions depend on it. Why exactly is explained below, where we follow edits back to Google Calendar.<\/p>\n In the browser, the DHTMLX JavaScript event scheduler opens in week mode, and dynamic loading is on:<\/p>\n With the setLoadMode()<\/strong> method, the widget requests only the dates the user can currently see, adding from and to parameters to the request URL. The server converts these two values into Google’s timeMin<\/strong> and timeMax<\/strong> query parameters:<\/p>\n First, the handler fetches the list of calendars, then requests events for all of them concurrently, and runs each entry through the mapper. The reply has two sections: an array of entries already converted to Scheduler’s format, and the calendars list placed under collections. Scheduler remembers such collections<\/a>, so later the client code can retrieve the list by calling the serverList()<\/strong> method with the “calendars” key, and the DataProcessor relies on precisely this.<\/p>\n Event conversion is implemented in a separate eventMapper.ts module, which holds most of the integration’s complexity. Google Calendar and Scheduler describe the same event in noticeably different ways: <\/p>\n TABLE!!!<\/p>\n The toDhxEvent()<\/strong> function copies the event’s title and description, records which calendar the event belongs to, and then branches by event type. Timed events get their start_date<\/strong> and end_date<\/strong> directly from Google’s dateTime<\/strong> values. All-day events carry dates only, so the mapper converts them to midnight timestamps. <\/p>\n Now you are familiar with how events reach Scheduler from Google Calendar. Next, we\u2019ll consider how edits made in Scheduler reach Google Calendar.<\/p>\n The reverse synchronization flow includes a few noteworthy aspects, such as preparing event data for Google Calendar\u2019s format, handling time zones correctly, and keeping event IDs consistent across both systems. So let us consider how these tasks are addressed in our demo project.<\/p>\n Scheduler sends every change a user makes (adding, editing, or removing an event) to a single callback function. The demo defines this callback in main.ts<\/a>, where the client sets up Scheduler:<\/p>\nHow Two-Way Sync Works in the Demo<\/h2>\n
\n
Signing In with Passport and OAuth 2.0<\/h2>\n
\n "\/google"<\/span>,<\/span>
\n passport.authenticate<\/span>(<\/span>"google"<\/span>,<\/span> {<\/span>
\n scope:<\/span> [<\/span>"profile"<\/span>,<\/span> "email"<\/span>,<\/span> "https:\/\/www.googleapis.com\/auth\/calendar"<\/span>]<\/span>,<\/span>
\n accessType:<\/span> "offline"<\/span>,<\/span>
\n prompt:<\/span> "consent"<\/span>,<\/span>
\n }<\/span>)<\/span>
\n)<\/span>;<\/span><\/div><\/div>\nFrom Session Tokens to Requests<\/h2>\n
\n const<\/span> client =<\/span> new<\/span> google.auth<\/span>.OAuth2<\/span>(<\/span>
\n config.GOOGLE_CLIENT_ID<\/span>,<\/span>
\n config.GOOGLE_CLIENT_SECRET<\/span>,<\/span>
\n config.GOOGLE_REDIRECT_URI<\/span>
\n )<\/span>;<\/span>
\n client.setCredentials<\/span>(<\/span>{<\/span>
\n access_token:<\/span> tokens.accessToken<\/span>,<\/span>
\n refresh_token:<\/span> tokens.refreshToken<\/span>,<\/span>
\n }<\/span>)<\/span>;<\/span>
\n return<\/span> client;<\/span>
\n}<\/span>
\n
\n\/\/ ...<\/span>
\n
\nexport<\/span> async function<\/span> createEvent(<\/span>
\n tokens:<\/span> GoogleOAuthTokens,<\/span>
\n calendarId:<\/span> string |<\/span> undefined<\/span>,<\/span>
\n gEvent:<\/span> calendar_v3.Schema<\/span>$Event
\n)<\/span>:<\/span> Promise<<\/span>calendar_v3.Schema<\/span>$Event><\/span> {<\/span>
\n const<\/span> {<\/span> data }<\/span> =<\/span> await calendarClient.events<\/span>.insert<\/span>(<\/span>{<\/span>
\n auth:<\/span> oauthClient(<\/span>tokens)<\/span>,<\/span>
\n calendarId:<\/span> calendarId ||<\/span> "primary"<\/span>,<\/span>
\n requestBody:<\/span> gEvent,<\/span>
\n conferenceDataVersion:<\/span> 1<\/span>,<\/span>
\n }<\/span>)<\/span>;<\/span>
\n return<\/span> data;<\/span>
\n}<\/span><\/div><\/div>\nThe REST Contract<\/h2>\n
\n
Loading Events from Google to Scheduler<\/h2>\n
\nscheduler.setLoadMode<\/span>(<\/span>"week"<\/span>)<\/span>;<\/span><\/div><\/div>\n
\nconst<\/span> toQuery =<\/span> typeof<\/span> req.query<\/span>.to<\/span> ===<\/span> "string"<\/span> ?<\/span> req.query<\/span>.to<\/span> :<\/span> undefined<\/span>;<\/span>
\n
\nconst<\/span> minDate =<\/span> fromQuery ?<\/span> new<\/span> Date<\/span>(<\/span>fromQuery)<\/span>.toISOString<\/span>(<\/span>)<\/span> :<\/span> new<\/span> Date<\/span>(<\/span>)<\/span>.toISOString<\/span>(<\/span>)<\/span>;<\/span>
\nconst<\/span> maxDate =<\/span> toQuery ?<\/span> new<\/span> Date<\/span>(<\/span>toQuery)<\/span>.toISOString<\/span>(<\/span>)<\/span> :<\/span> undefined<\/span>;<\/span><\/div><\/div>\nSending Edits Back to Google<\/h2>\n
The DataProcessor as the Router<\/h3>\n
\n entity:<\/span> "event"<\/span>,<\/span>
\n action:<\/span> SchedulerDataAction,<\/span>
\n data:<\/span> DhxEvent,<\/span>
\n id:<\/span> string |<\/span> number
\n)<\/span> =><\/span> {<\/span>
\n const<\/span> calendars =<\/span> scheduler.serverList<\/span>(<\/span>