This article outlines the two methods available for migrating accounts from V2 to V3, utilizing the object V2 to V3 translation tool. It also details the benefits and disadvantages of each method.
Note: Running accounts in both V2 and V3 on a single app will not result in double billing but may increase workload and the likelihood of encountering rate limiting.
Note II: For accounts that are not running we create placeholder accounts with the scopes.
Important: We recommend turning off the V2 account via the /revoke endpoint at the earliest opportunity, we have seen instances where IMAP providers do not appreciate two sync engines connected to the same mailbox.
Prerequisites
- Microsoft: A new Azure project to OAuth personal accounts on your V3 application to authenticate ALL Microsoft accounts.
- GMAIL: Ensure the API V3 Callback URI is added to the existing GCP project
Migration Methods
1. Gradual Migration
Steps:
- Change the Auth URL on your application to point to the V3 application.
- Over time, revoke tokens to force customers to authenticate on your new application.
Benefits:
- Migrate at your own pace.
- Migrate to different datacenter
- Same method for all accounts.
Disadvantages:
- All customers will need to re-authenticate.
- Can not migrate scheduler Slugs
- No relationship between V2 account_id and V3 grant_id
2. Nylas Account Migration Tool
Availability: The tool is available via the API, it will be added to the dashboard in due course.
Usage:
- Run a single migration on an account for each major provider like Office365, Gmail, Outlook, IMAP.
- Run the Batch migration tool
- Fetch the job logs to get the V2 account_id to V3 grant_id
- The v2 account is also returned on the /grants endpoint
- You can use V2 object ID's in V3 endpoints (live end July)
- Password microsoft (Microsoft Free or Family licenses including Outlook.com, Hotmail.com, and MSN.com email addresses) accounts can not be migrated, we can create placeholder accounts with their scopes if you pass clone_exchange = True
Benefits:
- Accounts with the provider GMAIL, IMAP, and Graph (using our v2 Graph Calendar Beta) should see no disruption or change as little is affected in the shift.
- Clones the accounts, allowing them to run in both V2 and V3.
- Required to migrate scheduler slugs
- Allows for V2 object ID's to be used in V3 endpoints.
Disadvantages:
- Only Microsoft accounts will need to re-authenticate.
- Personal Microsoft accounts such as Hotmail / Live / outlook can not be migrated, requires new account due to move from Basic to Oauth.
- Requires development to switch from V2 to V3 webhooks when the grant is online.
|
# |
v2 Provider Type |
v3 Equivalent |
Automatic migration support by migration tool |
Extra steps |
End user (owner of the email) has to reauth |
Notes |
|---|---|---|---|---|---|---|
|
|
Provider:Google Auth: OAuth (hosted/native) |
Provider: Google Auth: OAuth (hosted/custom) |
YES |
|
No |
|
|
|
Provider: Google Auth: Service Account |
Provider: Google Auth: Bulk Auth |
YES |
|
No |
|
|
|
Provider: Microsoft Graph Auth: OAuth |
Provider: Microsoft Graph Auth: OAuth (hosted/custom) |
YES |
|
No |
|
|
|
Provider: Outlook / Live Variation: Personal Auth: Basic (username/password) |
Provider: Microsoft Graph Auth: OAuth |
No |
Basic to Oauth, different object type. |
Yes |
eg domains: live.com, hotmail.com, … |
|
|
Provider: Microsoft O365 Variation: non-personal, not-on-prem Auth: OAuth Modern |
Provider: Microsoft Graph Auth: OAuth |
Grants get created with |
New Azure application. End user reauths again. |
Yes |
|
|
|
Provider: Exchange O365 Variation: non-personal, not-on-prem Auth: ServiceAccount (Basic) |
N/A |
N/A |
N/A |
N/A |
Deprecated by Microsoft in 2022. |
|
|
Provider: Exchange O365 Variation: non-personal, not-on-prem Auth: ServiceAccount (OAuth refresh_token) |
Provider: Microsoft Graph Auth: Bulk Auth |
No |
New Azure application. |
No |
domains:
|
|
9 |
Provider: Exchange On-Prem Variation: non-personal, on-prem Auth: Basic (username/password) |
Provider: Exchange (v3) Auth: Basic also |
Yes (WIP |
|
No |
We also support syncing with IMAP if the use case is email only but that requires extra configuration in the server. |
|
11 |
Provider: Exchange On-Prem Hybrid Variation: non-personal, on-prem, hybrid Auth: ServiceAccount (OAuth refresh_token) |
Provider: Microsoft Graph Auth: Bulk Auth |
No |
New Azure application. |
No |
Nylas cannot distinguish between on-prem and not on-prem, therefore it treats these accounts similar as #8 |
|
12 |
Provider: Exchange On-Prem Variation: non-personal, on-prem Auth: ServiceAccount (Basic) |
N/A |
N/A |
N/A |
N/A |
Microsoft has shutdown and deprecated most of the capability already. We will not support it. |
|
13 |
Provider: IMAP Auth: Basic (username/password) |
Provider: IMAP Auth: Basic (username/password) |
Yes |
|
No |
Password can be “App Password”. |
|
14 |
Provider: iCloud Auth: Basic (username/password) |
Provider: iCloud Auth: Basic (username/password) |
Yes |
|
No |
Password SHOULD be “App Password”. This connector syncs both Email (IMAP) and Calendar (CalDav protcol) under the same grant. |
|
15 |
Provider: Virtual Calendar Auth: N/A |
Provider: Virtual Calendar Auth: N/A |
Yes (WIP |
|
N/A |
Migration of data still WIP |
FAQ:
How do I handle the switchover from V2 to V3? The concern is lost synced objects between moving from V2 to V3.
- If using the Gradual method or the accounts are Microsoft you will need to record the time you hit /revoke on the V2 application and when the customer re-authenticates. For this time gap you will need to GET /object_endpoint for all the objects in question.
- If using the migration tool then the accounts can work in parallel and you programmatically switch between API's.
- V2 Object ID's can be used in V3 endpoints, replace the V3 grant_id with the v2 account_id, likewise with the object_id. Ony works of the migration tool was used.
Resources
Documentation on Migrating Microsoft accounts
How do I migrate my V2 organization, applications, accounts and objects to V3
Updated
Comments
0 comments
Please sign in to leave a comment.