We are excited to announce the migration from Microsoft Exchange Web Services (EWS) to Microsoft Graph API, which offers enhanced functionality, increased security, and real-time synchronization for your scheduling and management needs.
Benefits of Graph
Real-time event syncing - Graph API syncs in real-time whereas EWS syncs events every 5 minutes which can lead to conflicting events
Enhanced security - Graph uses OAuth instead of a password for EWS
Lower network usage - EWS is SOAP-based whereas Graph API is REST-based, providing faster serialization and lower network usage
Reduce sync errors and easy troubleshooting - Sync errors are less frequent with Graph API and error codes are more detailed
Recurring event sync - with the EWS integration recurring events created in outlook could become out of sync. The graph api will handle recurring events synced to Coconut.
Time zones - with EWS if the exchange timezone and coconut time zone were not aligned in observing daylight savings time, events would be off by 1 hr. This is resolved with the graph api.
Migration Steps
Note: It is strongly recommended that when setting up Graph, it is only set up in a Production instance and not a Demo instance, as this can cause double bookings.
Step 1: Enable Microsoft Graph
Navigate to Settings -> Microsoft Exchange -> Configuration.
Toggle on Use Microsoft Graph.
NOTE: Manual user sync can be on or off.
Step 2: Enter Microsoft Tenant ID
Enter your Microsoft tenant ID and click Continue.
Step 3: Grant Permissions
Log in to your Microsoft Admin account with Global Administrator permissions and grant permissions to Coconut Software.
Step 4: Wait for Migration
The migration process may take a few minutes to a few hours, depending on the number of accounts. The progress bar will display the percentage completed. You can close or navigate away from the page while the migration completes. Users will continue to enjoy Coconut and Exchange while the migration is in progress. When the user's account is synced they may notice a momentary duplication of events in Coconut while the Graph API and EWS API are both syncing. This will be resolved within a minute when the EWS integration is automatically removed.
The migration can stay at 99% for longer than the prior progress - this is expected as the migration finishes syncing all users.
Step 5: Confirm Migration Completion
Once the progress bar disappears, go to the Users tab in the Microsoft Exchange settings.
Verify that all users have synced. If any are incomplete, click to re-sync them.
Step 6: Test the Migration
For all testing ensure the user is assigned to a service and a location.
Note: Once migration to Graph API has finished, synchronization of all users may take additional time depending on Microsoft Exchange traffic. In practice, this may mean delayed visibility of Exchange events in Coconut, and vice versa. When testing, take this note into account.
Check the User tab in the Coconut Exchange settings and if there are errors, resync the users with errors by clicking the resync icon in the row of the user.
Choose a test user from the Coconut Exchange Users tab - it's easiest to choose your own user. Manually resync this user using the Resync button.
Create an appointment in Outlook and check that it syncs correctly to Coconut.
Create an appointment in Coconut and check that it syncs correctly to Outlook.
Create a recurring event in either Coconut or Outlook and verify that all events in the series sync properly to the other calendar.
For multi-staff appointments, ensure that appointments created in either Outlook or Coconut sync across all involved staff calendars.
If appointments do not immediately appear, wait 15 minutes and check for the appointments again.
Frequently Asked Questions
What should I do if the tests fail?
Contact Coconut Support at support@coconutsoftware.com or +1-888-257-1309 x 2
What happens if an appointment is edited during the migration? Will any data be lost?
No data will be lost. Graph API will capture all changes made during the migration.
Can I roll back the Graph migration?
Yes, migrations are supported. Please contact Coconut support before initiating a rollback to ensure its success. You can initiate the rollback directly from the Coconut settings within the Microsoft configurations page.
Is there a charge for the migration?
No, there is no charge for this migration.
After the migration is completed, can I remove the EWS “Legacy Exchange”?
Yes, in the Coconut configuration setting “Legacy exchange is connected” you can click “Remove” to delete the EWS connection. Please ensure the Graph sync is complete before doing this as it will remove the option to roll back to EWS.
Is the migration stalled at 99%?
The last 1% of the migration can take longer (up to 60 minutes) as the system finishes.
What can I do if a user has an error?
Resync the user by clicking the resync icon on the right.
A user has an error “Incorrect Permissions”, how do I resolve it?
Ensure the user has a service assigned - users with no service assignment will not be synced with exchange.
This message can occur when the mailbox is busy. Try resyncing by clicking on the refresh icon ⟳ next to the user.
If these steps do not resolve your issue and the error code is not listed on the Coconut Exchange help center page, it is likely a Microsoft error. Please search the Microsoft Exchange troubleshooting for further support.
I have encountered an “Incorrect PermissionsExtension Error”, how can I resolve?
The Principal name (UPN) in Azure and email in coconut must match.
What do I do if many users haven’t synced?
If there are any incomplete user syncs, click to re-sync the user from the Coconut Microsoft Exchange user dashboard.
Click the resync icon next to the user or check the “staff” check box and click the resync button in the top right to resync all users.
