MS Graph provides a more secure way to interact with the Office 365 Exchange server to sync Penelope events to your Outlook calendar.
Important Information
MS Graph Exchange Synchronization is only available when using Penelope 4.21.1.0 and above. If you have any questions please contact the Penelope Support Team.
In this article:
What can MS Graph Exchange Synchronization do?
Everything that the previous version (using EWS – Exchange Web Services) could do. Namely it will automatically sync events from Penelope into the Outlook calendars of your staff, allowing them to integrate their Penelope calendar with their normal Outlook calendar.
What can’t MS Graph Exchange Synchronization do?
Anything that the previous version did not do.
Namely synchronize Penelope Individuals as Outlook Contacts or Penelope messages as Outlook Emails. Also, MS Graph Exchange remains a one-way sync from Penelope out to Outlook, so no Outlook meetings will be synced back into Penelope.
Why Switch to MS Graph Exchange Synchronization?
On October 13, 2020 Microsoft sunsetted their EWS (Exchange Web Service) libraries for use with Outlook in Office 365, so previous Exchange Synchronization no longer works.
If you are using an on-premises Microsoft Exchange server for Outlook, then you cannot upgrade to MS Graph Exchange synchronization at this time. There is nothing you need to do and your EWS libraries will continue to function as they always have.
How Do I Switch to MS Graph Exchange Synchronization?
STEP ONE: Register your Penelope application with MS Azure to provide secure authentication.
STEP TWO: Set up your MS Graph Exchange Synchronization using the information received when registering Penelope with MS Azure.
STEP THREE: Test the connection to make sure it is working.
Each of these steps is described in detail below. At any time during this activity you can switch back to EWS to make sure that your Exchange Synchronization is functioning while you resolve any issues or errors.
STEP FOUR: Enable Worker Events to sync
Step One: Register Penelope with MS Azure
Login to https://portal.azure.com/ using an Admin level account.
Go to the App registration page. In the Header Search type App registrations and select App registrations (under Services) from the search drop-down.
Create an App. On the App registrations page select the + New registration option to create an App. Fill in the Register an Application form. Name: Penelope Account Type: Single Tenant Redirect URI (Web): https://YourAgencyPenelopeURL/azure Select Register to create the App. You are redirected to the App’s main page.
Setting API Permissions Click on API Permissions in the left-hand sidebar. Select the + Add a permission option. Under Microsoft APIs (default) select the Microsoft Graph box. When it asks, What type of permissions does your applications require?, select Application Permissions. Where it asks for Select Permissions, search for User.Read.All permission. Check box associated with the User.Read.All permission. Return to Select Permissions and search for Calendars.ReadWrite permission. Check box associated with the Calendars.ReadWrite permission. Return to All APIs screen.
Grant Permissions Click the ‘Grant admin consent for (account name)’ button A pop-up will appear asking for confirmation Answer ‘Yes’ Confirm that both permissions have a green status checkmark and are marked ‘Granted’
Add Client Secret Click on Certificates & secrets in left-hand sidebar. Under Client Secrets select + New client secret. Fill out form with: Name: any name (e.g.: penelope_secret) Expires: We suggest the longest possible timeframe to avoid the secret expiring and causing sync issues. Click Add. A new row will appear with the secret information. Click on the Copy to Clipboard icon to the left of the trash icon. Open any text editor and paste the value for the secret in. You will need this later.
Copy Azure values Click on Overview in the left-hand sidebar. Copy the application (client) ID via copy icon (after the text). Paste application ID into the same text editor you pasted the secret into. Copy the directory (tenant) ID in the same way. Paste the directory (tenant) ID into the same text editor.
You are now ready to begin set-up in Penelope.
If you need to make changes, you can return to the Application page in MS Azure by selecting it from the list of Owned Applications on the App registrations page.
Step Two: Set-up MS Graph in Penelope System Admin Application
Login to Penelope with a System Administrator account.
If you are not currently using MS Exchange Synchronization, then enable MS Exchange. In the System Setup section click Agency, Settings. Click Edit. Check the Use MS Exchange checkbox. Click Save.
Under System Setup, click MS Exchange. On read-only MS Exchange set-up page, click Edit. Check MS Exchange Sync if not already checked. Select Microsoft Graph radio button (defaults to EWS).Page will reset to show MS Graph set-up information. Enter the following: Application ID – enter the Application (client) ID from Azure. Tenant ID – enter the Directory (tenant) ID from Azure. Application Secret – enter the Client Secret from Azure. Chose a Worker Category to receive alerts about syncing issues.
Click Save.
You will be redirected to the read-only MS Exchange page.
Step Three: Test the Connection
Note that the MS Exchange page is showing the following information: Integration is set to MS Graph. Application ID is the one just entered during Set-up. Last Test Result and Exchange Detected are both blank. Send Alert To is set to the Worker Category selected during Set-up.
On the Exchange set-up page, click the Test Connection link.
You will be prompted for an email address.
Enter an email address for a user in the Azure active directory. Must be an account in the same Azure directory as the App made in step 1 above with an active inbox (can be same admin email used to login to Azure). Click Save.
When test completes you will be prompted with a message indicating success or an error box indicating an error.
If test was successful, the Last Test Result is set to current date and time and the Exchange Detected field is set to Yes. No email is sent to the email provided (this is different than EWS which will send an email to indicate success).
If test failed the Last Test Result is set to current date and time and the Exchange Detected is set to No. If you have questions about the error received, please contact the Penelope Support Team.
Step Four: Enable Worker Events to Sync
Navigate to a Worker Profile either as a System Administrator or another user with the ability to make changes to the Worker Profiles of other users.
Select Edit to the top right of the Worker Profile while on the Profile tab.
Check the "Use for MS Graph" checkbox.
Save
Repeat for any Workers who need to have their Events sync. Alternately, users with the ability to edit their own Worker Profiles can complete these steps themselves.
NOTE: The email address in the Email field above the checkbox must be the Microsoft email address that is compatible to be used with calendar sync.
How do I Revert to EWS Exchange Synchronization?
If you have an issue with MS Graph and cannot establish a connection, you can revert to EWS to ensure that your MS Synchronization continues without interruption while you diagnose the error.
Login to Penelope with a System Administrator account.
Under System Setup, click MS Exchange. Click Edit. Select EWS radio button. Page will reset to show EWS set-up information. All your previous EWS set-up information should still be shown. Click Save. You will be redirected to the read-only MS Exchange page with Integration set to EWS. Last Test Result and Exchange Detected Fields are set to blank.
Click on Test Connection to ensure your EWS connection still works. You will be prompted for an email address (will default to your admin email). Click Save. If test is successful, the email address will receive an email confirmation The Last Test Result and Last Successful Sync fields are updated to the current date and time. The Exchange Detected Field is set to Yes. If the test fails, an error will be received. The Last Test Result field is updated to current date and time.The Exchange Detected Field is set to No.
Are there any differences between MS Graph and EWS Synchronization?
There are no differences in the synchronization functionality between MS Graph and EWS. Either integration method will add, update or remove Penelope events in your staff’s Outlook calendars.
There is a small difference in how status is reported in the MS Exchange Administration Application. In MS Graph, the Last Successful Sync field will only be updated and shown when data has successfully been synchronized between Penelope and MS Exchange. If there is no data to be updated, or if all data fails to sync successfully, then the field will not update. In EWS this field is updated whenever a successful connection occurs, whether any data is synchronized or not.
Also, when testing a connection, EWS will send an email to report a successful test. MS Graph simply provides a pop-up to indicate success.