Version:
Only show these results:

Upgrade and migrate v2 Virtual Calendars to v3

This page explains how to upgrade your v2 Virtual Calendars to v3, and migrate your v2 virtual account data to v3 grants.

If you're using virtual calendars by themselves, you can start the data migration process before you start upgrading your code to use v3 APIs. However, if you're using virtual calendars along with a provider auth system, you should upgrade the rest of your app before working on virtual calendar migration.

Either way, you'll want to migrate your v2 application to a v3 application, and upgrade your webhooks to v3 so you can get notifications while you test. Then you can migrate your virtual calendar data.

✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!

Changes to virtual calendar schemas in v3

Virtual calendars have very few changes in v3, and a few improvements.

The schema for the underlying virtual account has changed. The client ID is now passed in the API request, the scopes and name fields have been removed, the provider is now virtual-calendar, and the email string is now inside the settings.

{
  "client_id": "3",
  "provider": "nylas",
  "scopes": "calendar",
  "email": "virtual_account_unique_id",
  "name": "Virtual Calendar",
  "settings": {}
}   
{
  "provider": "virtual-calendar",
  "settings": {
  "email": "virtual_account_unique_id" //a human-readable ID
  }
}

When you make new virtual accounts in the future, make sure the email string provides a clear description for the virtual account.

Import app settings and upgrade webhooks

When you're ready to start, you can either use the Migrate button in the v3 Dashboard, or use the individual Migration APIs to link your v2 apps with their v3 equivalents, and import your v2 app settings to the linked v3 app.

If webhook notifications are a big part of your project, you should upgrade your webhook systems so you can monitor for notifications.

Migrate virtual calendar data to v3

You can start by migrating your virtual calendar data to v3 to help you upgrade the rest of your project code. Start with a dev or test application so you don't disturb your production users.

After you link your v2 and v3 applications you can batch migrate accounts to copy your Virtual Calendar data to the v3 application.

Migrated virtual calendar event and calendar object IDs don't change. You can use the same IDs to reference the same events and calendars in your v3 app.

Migrated virtual accounts keep the email from the v2 version, but are converted to grants. Use the grant ID for the virtual account's grant to locate its calendar and event data.

When you're ready for your users to start switching to the v3 version, you can re-run the migration tool to catch up on any new or changed data since the initial sync.

Changes to virtual calendar data during migration

The migration tool looks at your v2 virtual calendar data, transforms it into the v3 format, and copies it to the v3 systems. You can expect the following changes:

  • When you migrate virtual calendar data using the Nylas Migration API, Nylas saves the content of the name and organizer fields to the grant's metadata. If you need access to this metadata, contact Nylas Support.
  • Other metadata from v2 is not migrated to v3.
  • The v2 virtual account name and v2 event organizer are not supported in v3 Virtual Calendars. The v3 equivalent for the organizer field is the email string that you set when you create the virtual calendar.
  • The created_at and updated_at timestamps are be updated for all events and calendars during migration.
  • In v2, Nylas marked a virtual calendar event as status=cancelled when it was deleted ("soft-delete"). In v3 events are permanently deleted immediately.
  • The v2 recurrence timezone is now part of the when property of v3 events. Timezones are not available for all-day events in v3, so Nylas drops the timezone when converting v2 all-day events to v3 format.
  • The read_only field in v3 virtual calendars is always null.
  • Reminders are not supported for v3 virtual calendars, and are not migrated.

Upgrade virtual calendar auth to use v3

For most projects migrating from v2.x to v3, the first step is to upgrade authentication. However, since Virtual Calendars use Custom Authentication (previously called "Native Authentication"), you get to skip worrying about scopes and provider auth apps. You just need to update how you authorize your API calls to the v3 method, and update the Custom Auth API calls themselves.

In fact, you don't actually need to upgrade to use Custom authentication until you want to make new virtual accounts.

Upgrade your Calendar and Events calls to use v3

Virtual calendars use the new v3 Nylas Calendar and Events APIs, and all Calendar-related endpoint changes in v3 API also apply to virtual calendars. To upgrade these APIs, use the Upgrading Calendar APIs instructions.

General changes to virtual calendars

  • Virtual calendars are no longer limited to one calendar per account (now called a grant). You can now have up to 10 calendars per grant, and you can still create as many grants as you need. You are still billed per grant.
  • You create new grants using Custom auth and the virtual-calendar provider.
  • In v3 new virtual accounts are created without any calendars so you can specify the email identifier and control which is set as primary. Create new virtual calendars for each grant using the POST /v3/calendars endpoint.
  • You must provide an identifier when you create a grant for a virtual calendar. Previously, this was optional. This can be any arbitrary string, and no longer needs to be in email address format.
  • In v3 Nylas can set one calendar per account as the "primary" calendar, and you can use the word primary instead of a calendar_id in Calendar API calls. In virtual calendars, the primary calendar is the first calendar created for a grant. Once created, that first calendar cannot be deleted.