Jump to content

Office 365 Calendar Sync - Administrative Setup: Difference between revisions

From Prime 16 Online User's Manual
← Older edit
No edit summary
 
(33 intermediate revisions by the same user not shown)
Line 1: Line 1:
Prime 16 utilizes technologies made available through Office 365 (O365) to provide users with the ability to synchronize their Prime and O365 calendars.  This new sync is very easy to use in Prime.  This is the updated version as of 05/19/2026. Prior version information is below in the "Archived/old material" section.
Prime 16 utilizes technologies made available through Office 365 (O365) to provide users with the ability to synchronize their Prime and O365 calendars.  This new sync is very easy to use in Prime.  This is the updated version as of 05/19/2026. Prior version information is below in the "Archived/old material" section.


= Prime Microsoft 365 Calendar Sync Instructions =
 
 
= Prime Microsoft 365 Calendar Sync Setup Instructions =


These instructions are for organizations setting up Prime calendar sync with Microsoft 365 / Outlook. Each organization should create its own Microsoft Entra application registration in its own Microsoft tenant.
These instructions are for organizations setting up Prime calendar sync with Microsoft 365 / Outlook. Each organization should create its own Microsoft Entra application registration in its own Microsoft tenant.
Line 67: Line 69:
User.Read
User.Read
Calendars.ReadWrite
Calendars.ReadWrite
Mail.ReadWrite
Mail.ReadWrite.Shared
Mail.Send
Mail.Send.Shared
offline_access
offline_access
</pre>
</pre>
Line 72: Line 78:
Prime uses delegated permissions because each Prime user signs in as themselves.
Prime uses delegated permissions because each Prime user signs in as themselves.


If the organization blocks user consent, an administrator may need to grant consent for the organization.
Review the list of delegated permissions. Once that list includes all those shown above, click the "Grant admin consent for <your domain>".


== 2. Prime Administrator Setup ==
== 2. Prime Administrator Setup ==
Line 83: Line 89:


<pre>Exchange Calendar Sync Settings</pre>
<pre>Exchange Calendar Sync Settings</pre>
In the "Exchange Calendar Sync Admin" form, choose "Open Org Settings".


Enter the following values:
Enter the following values:
Line 89: Line 97:
Tenant ID:        Directory (tenant) ID from Entra
Tenant ID:        Directory (tenant) ID from Entra
Client ID:        Application (client) ID from Entra
Client ID:        Application (client) ID from Entra
Redirect URI:    http://localhost:3017/
Redirect URI:    <<As instructed by Kemp's Case Works staff>>
Default Time Zone: Central Standard Time
Default Time Zone: <<Select the appropriate time zone>>
</pre>
</pre>
Enter the appropriate Time Zone for your Organization.


Then enable organization-level calendar sync:
Then enable organization-level calendar sync:
Line 108: Line 114:
Each organization can adjust those values later.
Each organization can adjust those values later.


= Testing =
In the "Exchange Calendar Sync Settings" page click "Save Settings" and close this form. This should put you back in the "Exchange Calendar Sync Admin" form. Click on "Refresh Status" to see the values you've entered.
 
Testing should be done first by an administrator or support user before rolling out to all staff.
 
== Test 1 — Confirm Microsoft Sign-In Works ==
 
In Prime, sign in to Microsoft 365 for the test user.
 
Expected result:
 
<pre>
Prime confirms that Microsoft Graph sign-in was saved.
The user's Microsoft display name, email, or user principal name is shown.
</pre>
 
If sign-in fails, check:
 
<pre>
Tenant ID
Client ID
Redirect URI
Public client flow setting
Graph permissions
User/admin consent
</pre>
 
== Test 2 — Confirm Saved Token Works ==
 
Run the saved connection test from Prime.
 
Expected result:
 
<pre>Saved Microsoft Graph connection works.</pre>
 
This proves Prime can refresh the Microsoft connection without requiring the browser sign-in every time.
 
== Test 3 — Create and Delete a Temporary Outlook Event ==
 
Run the Graph calendar create/delete test.
 
Expected result:
 
<pre>
Prime creates a temporary Outlook calendar event.
Prime then deletes it.
No event remains in Outlook.
</pre>
 
This confirms the Microsoft Graph Calendars.ReadWrite permission is working.
 
== Test 4 — Prime to Outlook ==
 
# Create a simple future calendar item in Prime.
# Run the sync.
# Open Outlook.
 
Expected result:
 
<pre>The Prime calendar item appears in Outlook.</pre>
 
Then change the Prime calendar item's reason or time and run sync again.
 
Expected result:
 
<pre>The Outlook event updates.</pre>
 
Then delete the Prime calendar item and run sync again.
 
Expected result:
 
<pre>The Outlook event is deleted.</pre>
 
== Test 5 — Outlook to Prime ==
 
# Create a simple future event in Outlook.
# Run the sync in Prime.
 
Expected result:
 
<pre>The Outlook event appears in Prime.</pre>
 
# Change the Outlook event subject or time.
# Run the sync in Prime again.
 
Expected result:
 
<pre>The Prime calendar item updates.</pre>
 
== Test 6 — Outlook Deletion Review ==
 
# Create or use an Outlook event that has already synced to Prime.
# Delete the event in Outlook.
# Run the sync in Prime.
 
Expected result:
 
<pre>
The Prime calendar item is not deleted automatically.
The item appears in the Outlook Deleted Calendar Review screen.
</pre>
 
From the review screen, the user can choose one of the available actions:
 
<pre>
Recreate in Outlook
Keep Prime Only
Accept Delete
</pre>
 
Recommended first test action:
 
<pre>Recreate in Outlook</pre>
 
Expected result:
 
<pre>
The event appears again in Outlook.
The review item is resolved.
</pre>
 
== Test 7 — Recurring Outlook Events ==
 
For the first production version, Prime treats Outlook recurring events as individual calendar entries inside the sync window.
 
Test with a short recurrence, such as:
 
<pre>
Daily event for 3 days
</pre>
 
Expected result:
 
<pre>
Each occurrence appears as a separate Prime calendar item.
Prime does not create or edit the Outlook recurrence pattern itself.
</pre>
 
= General Use =
 
== Normal User Sync ==
 
Users should normally run:
 
<pre>Sync Microsoft 365 Calendar</pre>
 
This should call the Prime user-facing sync routine:
 
<pre>RunExchangeCalendarSyncForUser</pre>
 
This performs the full sync:
 
<pre>
Outlook → Prime
Prime → Outlook
Deletion review handling
Missing Outlook event verification
</pre>
 
Users should not normally run developer/test commands.
 
== What Sync Does ==
 
When a user runs calendar sync, Prime will:
 
# Bring Outlook-created calendar events into Prime.
# Bring Outlook changes into Prime.
# Mark Outlook-deleted events for review instead of automatically deleting Prime calendar rows.
# Push Prime-created calendar items to Outlook.
# Push Prime changes to Outlook.
# Delete Outlook events when the Prime calendar item was deleted.
# Verify that tracked Outlook events still exist.
 
== What Users Should Do When Outlook Deletion Review Appears ==
 
If a user deleted an Outlook event that Prime still has, Prime will show it in the review list.
 
Choose:
 
<pre>Recreate in Outlook</pre>
 
when the event should still exist in Outlook.
 
Choose:
 
<pre>Keep Prime Only</pre>
 
when the event should remain in Prime but should no longer sync to Outlook.
 
Choose:
 
<pre>Accept Delete</pre>
 
only when the Prime calendar item should also be removed.
 
== Important User Notes ==
 
* Users should avoid editing the same calendar item in both Prime and Outlook at the same time.
* Sync should be run after making changes.
* If an event is private in Outlook, Prime may skip or limit what it imports.
* For recurring Outlook events, Prime currently handles individual dated occurrences, not the recurrence pattern itself.
* If sync fails, the user should contact support and provide:
** The date/time they ran sync.
** The calendar item involved.
** Whether the item was changed in Prime or Outlook.
** Any error message shown.
 
= Support Checklist =
 
When troubleshooting an organization, check these first:
 
# Entra app exists in the organization's tenant.
# Redirect URI is exactly:
#: <pre>http://localhost:3017/</pre>
# Public client flow is enabled.
# Graph delegated permissions include:
#: <pre>User.Read, Calendars.ReadWrite, offline_access</pre>
# Tenant ID and Client ID are entered correctly in Prime.
# Organization-level sync is enabled.
# Staff-level sync is enabled.
# User has successfully signed in from Prime.
# SQL tables, indexes, and triggers are installed.
# Outlook Deleted Calendar Review screen shows only the current user's review items.
 
= 3. Per-User Setup in Prime =
 
Each Prime user who wants Outlook calendar sync must complete a Microsoft sign-in.
 
# Log in to Prime as the user.
# Open the Microsoft 365 calendar sync setup/sign-in screen.
# Choose:
#: <pre>Sign in to Microsoft 365</pre>
# A browser window opens.
# The user signs in with their Microsoft 365 account.
# Microsoft may ask the user to consent to calendar access.
# After successful sign-in, Prime saves that user's Microsoft identity and refresh token.
 
The user should only sign in to the Microsoft account that corresponds to their own Outlook calendar.
 
 
 
<div class="toccolours mw-collapsible mw-collapsed" style="padding:0.5em; margin:1em 0;">
'''Archived / old material''' — This information is outdated and kept for reference only.
 
<div class="mw-collapsible-content">
 
 
Setup for individual staff members is very easy.  Within the staff member forms, go to the Calendar Setup tab.  Insert the appropriate path to the Office 365 website (shown as https://outlook.office365.com in the example below) and the O365 username (shown as test@kempscaseworks.onmicrosoft.com).  To test that the entries are valid, click the test button and, when prompted, enter the user’s O365 password.
 
[[File:Screen Shot 2019-08-21 at 11.17.37 AM.png|400px]]
 
The system will use the entries to attempt to contact the O365 system and test the username and passwords entered. If Prime believes the settings are correct, a message is shown indicating the test seemed to work.
 
[[File:CalSync2.png|400px]]
 
A failure results in a failure message:
 
[[File:CalSync3.png|400px]]
 
Set the time zone for the staff person using the dropdown list.  Determine the method of synchronization desired.  For example, if the staff person wants to sync from O365 to Prime, and from Prime to O365, check both boxes.  If the staff person only wants to sync from O365 to Prime, select that single box.  If the staff person only wants to sync from Prime to O365, select that single box.
 
Syncing only one way (i.e., choosing only one checkbox) will result in inconsistent entries in both calendars.  For example, when syncing only from Prime to O365, entries in Prime will be reflected in the O365 calendar.  Changes to those entries will also be reflected in the O365 calendar.  New entries or changes to the O365 calendar will not change any entries in Prime.
 
The first two times a user synchronizes their calendar will take longer than successive syncs.  The reason for that is the initial syncs require getting all entries from both calendars and making sure they are copied to the other calendar.  Because entries are not yet tied to one another, entries in the calendars may appear to duplicate. 
 
To illustrate, before synchronization, a staff member would enter a calendar item in Prime, and then enter that same item in O365.  Neither O365 nor Prime associate those entries as the same entry.  Rather, each entry is treated as unique.  When a sync is performed, the calendar item in Prime is added to the O365 calendar.  The O365 item is added to Prime.  Those entries may be for the same event, but O365 and Prime do not know that.
 
After the initial synchronization, new entries in either calendar should not appear to “duplicate” in the other calendar.  Each entry, when synched, has its own unique identifier that each calendar understands.  When a change is made in one location, the same change is made in the other using those unique identifiers.
 
After the first two syncs, synchronization should be much faster.  Since only changes on either side are transferred, there will be much less to copy.  The first couple of syncs should be made using the O365 Sync Start Page.  This page is accessed using the top-line menu bar and going to SearchCustom Search and clicking on the Exchange Sync button:
 
[[File:Screen Shot 2019-08-21 at 11.19.15 AM.png|400px]]


A user may press the “Open O365 Sync Details” button to get to the original setup page. Pressing the “Sync” button will start the synchronization process.  The user is prompted for his password.  [Note: The sync is only performed for the user who is currently logged into Prime.]  The system, depending on the settings made for the user, will then sync to and from O365/Prime.  
===Testing Settings===
====Test Chilkat/OAuth====
In the "Exchange Calendar Sync Admin" click the "Test Chilkat/OAuth" button. This will test to ensure the underlying/background systems are in place that are necessary for the system to run.  


As the synchronization progresses, updates are shown on this page, including the total number of items to synchronize, and how many are complete. Finally, the starting and ending times for the sync are displayed.
At the bottom you should see "Chilkat.OAuth2 object created and configured success". That means the system should be ready. Click OK to close this screen and return to the "Exchange Calendar Sync Admin" screen.


After the initial synchronization is performed by the user, and when exiting the system using the Exit menu option, a user will be asked whether he wants to perform a calendar sync.  Answering “Yes” will initiate the calendar sync before exiting the system.
====Test Sign-in / Me====
This button will test sign in with Microsoft using your Microsoft account. Be prepared to pass whatever credentials and two-factor authentication tests you may have set up with Microsoft.


[[File:CalSync5.png|400px]]
When you click this button, a web browser page should appear asking you to log in. You must use your account credentials in the agency. After successful logon, you should see "OAuth2 access is granted." This informs you the Microsoft system has authenticated you and returned information that Prime can use.


Answering “No” will avoid a calendar sync.  Finally, clicking “Cancel” will indicate the user never wants to be asked again and effectively disables calendar syncing.
Close the web browser.


[Some limitations exist on syncing.  Old entries are ignored.  Only entries within the last few days and into the future are synced.  Changes to old entries are also ignored.  This helps improve the speed of syncing and limits bandwidth use.  Additionally, because Prime is a standalone product, it is not a true “calendar client”.  Moving O365 calendars or resetting the sync settings in Prime will cause all items to be synced and (potentially) duplicated.  Synchronization only takes place when Prime is running and synchronization is triggered.]
You should see a "Microsoft Graph sign-in succeeded" notification together with information about your name and email account.


The start and stop time in Prime and O365 are copied between calendars. Additionally, the “Note” in Prime is used as the title in the O365 entry and vice versa.
====Test Calendar Create/Delete====
This tests Prime's ability to create and then delete an entry in the calendar. Once again, you will be required to log on using your Organization's account. Use the web browser to enter your credentials and then close it. (It should again show the "OAuth2 access is granted" message.


=Two Factor Authentication=
You should see a note saying a test calendar event was created, together with a question of whether you want to delete it, click "Yes" to test deletion capacity.
For O365 accounts that have two factor authentication (2FA) enabled on the account, you may have to set and use an application specific password to bypass the 2FA.


You should see "The Outlook test event was created and deleted successfully." This indicates your setup is complete.


</div>
You can click "Close" to close the "Exchange Calendar Sync Admin" form.
</div>

Latest revision as of 15:06, 27 May 2026

Prime 16 utilizes technologies made available through Office 365 (O365) to provide users with the ability to synchronize their Prime and O365 calendars. This new sync is very easy to use in Prime. This is the updated version as of 05/19/2026. Prior version information is below in the "Archived/old material" section.


Prime Microsoft 365 Calendar Sync Setup Instructions

These instructions are for organizations setting up Prime calendar sync with Microsoft 365 / Outlook. Each organization should create its own Microsoft Entra application registration in its own Microsoft tenant.

1. Setup

A. Microsoft 365 / Entra Administrator Setup

The organization's Microsoft 365 administrator must create an app registration in Microsoft Entra. This allows Prime to connect each Prime user to that user's Microsoft 365 Outlook calendar.

  1. Sign in to the Microsoft Entra admin center. https://entra.microsoft.com
  2. Go to: 
    Entra ID → App registrations
  3. Choose: 
    New registration
  4. Enter a name such as: 
    Prime Access Calendar Sync
  5. For supported account types, choose: 
    Single tenant only - <your domain name>
    This means the app is only for your organization's Microsoft tenant.
  6. Create the app registration by clicking "Register"
  7. After the app is created, copy these two values: 
    Application (client) ID and Directory (tenant) ID
  8. These will be entered into Prime.

B. Configure the Redirect URI

In the app registration, go to: 

Authentication

Click "Add Redirect URI" and choose: 

Mobile and desktop applications

In the blank box (that may show an example entry), add this custom redirect URI exactly: 

http://localhost:3017/

Important: The final slash matters!

Prime uses a desktop OAuth sign-in flow where Microsoft signs the user in through the browser and redirects back to a local listener on the user's workstation.

C. Enable Public Client Flow

Still under the app registration's Authentication page, in the Settings section, enable: 

Allow public client flows

Set it to: 

Enabled

Prime is a desktop Access front end, so it should be treated as a public client.

D. Add Microsoft Graph Permissions

In the app registration, go to: 

API permissions

Add Microsoft Graph delegated permissions: 

User.Read
Calendars.ReadWrite
Mail.ReadWrite
Mail.ReadWrite.Shared
Mail.Send
Mail.Send.Shared
offline_access

Prime uses delegated permissions because each Prime user signs in as themselves.

Review the list of delegated permissions. Once that list includes all those shown above, click the "Grant admin consent for <your domain>".

2. Prime Administrator Setup

After the Microsoft administrator creates the Entra app, open Prime and go to the calendar sync settings screen. 

Admin → Custom Admin

and choose 

Exchange Calendar Sync Settings

In the "Exchange Calendar Sync Admin" form, choose "Open Org Settings".

Enter the following values: 

Tenant ID:        Directory (tenant) ID from Entra
Client ID:        Application (client) ID from Entra
Redirect URI:     <<As instructed by Kemp's Case Works staff>>
Default Time Zone: <<Select the appropriate time zone>>

Then enable organization-level calendar sync: 

Calendar Sync Enabled = Yes

Recommended sync window: 

Sync Past Days:    30
Sync Future Days:  365

Each organization can adjust those values later.

In the "Exchange Calendar Sync Settings" page click "Save Settings" and close this form. This should put you back in the "Exchange Calendar Sync Admin" form. Click on "Refresh Status" to see the values you've entered.

Testing Settings

Test Chilkat/OAuth

In the "Exchange Calendar Sync Admin" click the "Test Chilkat/OAuth" button. This will test to ensure the underlying/background systems are in place that are necessary for the system to run.

At the bottom you should see "Chilkat.OAuth2 object created and configured success". That means the system should be ready. Click OK to close this screen and return to the "Exchange Calendar Sync Admin" screen.

Test Sign-in / Me

This button will test sign in with Microsoft using your Microsoft account. Be prepared to pass whatever credentials and two-factor authentication tests you may have set up with Microsoft.

When you click this button, a web browser page should appear asking you to log in. You must use your account credentials in the agency. After successful logon, you should see "OAuth2 access is granted." This informs you the Microsoft system has authenticated you and returned information that Prime can use.

Close the web browser.

You should see a "Microsoft Graph sign-in succeeded" notification together with information about your name and email account.

Test Calendar Create/Delete

This tests Prime's ability to create and then delete an entry in the calendar. Once again, you will be required to log on using your Organization's account. Use the web browser to enter your credentials and then close it. (It should again show the "OAuth2 access is granted" message.

You should see a note saying a test calendar event was created, together with a question of whether you want to delete it, click "Yes" to test deletion capacity.

You should see "The Outlook test event was created and deleted successfully." This indicates your setup is complete.

You can click "Close" to close the "Exchange Calendar Sync Admin" form.

Retrieved from "https://internalmanual.kempscaseworks.com/index.php?title=Office_365_Calendar_Sync_-_Administrative_Setup&oldid=3272"