Notes/ Updates based on newer versions:
- Starting August 4, 2022 release of the application, all space records can be synced with Outlook, as opposed to only Room records.
The Workplace Calendar Synchronization application lets users reserve room resources with ServiceNow® Workplace Reservation Management or their organization's calendar service providers such as Microsoft Exchange Online or Google calendar. Reservations made in either application synchronize with the other making reserving rooms for meetings easy, regardless of where the reservation is.
This article will explore setting up the Workplace Calendar Synchronization to sync room reservation information with Microsoft Exchange and discuss some tips related to this integration.
The Workplace Reservation product is constantly improving with enhancements and defect fixes through quarterly releases. Given the pace of these updates, this article is meant to be used as a reference, with the Product Documentation being the source of truth.
NOTE: This article covers version 2.0 and onwards of the Workplace Calendar Synchronization application. Version 2.0 is a redesigned iteration of the application which leverages the MS Exchange Online spoke. Previous application versions will have different configuration steps found in the product docs. Links in this article point to the San Diego release documentation to cover the most recent updates, however, screenshots below are captured in a Rome instance.
Table of Contents
Setting up the Integration in MS Exchange
Setting up the Integration in ServiceNow
Setting up Reservation Synch Configurations in ServiceNow
- Reservations made in SN Workplace Reservation Management
- Reservations made in MS Exchange
- Cancellations
- Repeating Reservations made in MS Exchange
- Can I further restrict SN’s access to MS Calendar?
- How do I work with resources that need approvals in MS Outlook?
- I just cloned my instance, and the integration is no longer working in my lower environments.
- My reservation is stuck in the 'Awaiting Confirmation' state.
- The subject for meetings created in Outlook shows the username as the subject instead of the Event t...
- How do we upgrade from version 1.x (non-Spoke) of the Workplace Calendar Synchronization application...
- How do I control the time zone for the invites sent out to my Outlook calendar?
- For reservations created in SN WSD, at what points are events triggered to MS Exchange?
Setting up the Integration in MS Exchange
Resource configuration in MS Exchange
This integration synchronizes 'Room' records in SN with ‘Resources’ created in MS Exchange.
NOTE: In the current app version (Workplace Calendar Synchronization version 2.0.4), this integration only supports MS Exchange resources that get auto accepted, if they are available. Resources requiring approvals in MS Exchange are not supported.
If your organization does not have resources configured, please follow the steps below to create Resources in MS Exchange. If you already have resources set up for rooms, you can skip this step and note down the email addresses for each of these resources.
Microsoft currently communicates the following: https://docs.microsoft.com/en-us/Exchange/recipients/room-mailboxes?redirectedfrom=MSDN&view=exchser...
1.) As an MS Admin, navigate to Resources > Rooms and equipment > Add resource
2.) Create a new resource and note down the email address for it.
Return to Table of Contents
Configuring OAuth Credentials
Perform the steps below to register ServiceNow as an OAuth client in MS Exchange. The credentials obtained here will be used in the Spoke configuration in ServiceNow. More details on these steps can be found at the link here.
- In the Microsoft Azure portal, search app registration and create a new app registration for ServiceNow.
- Note down the Application (client) ID and Directory (tenant) ID for this app.
- For the new app, in the Authentication section add a platform ‘Web’ and add the Redirect URIs in this format: https://<instance-name>.service-now.com/oauth_redirect.do
- For the new app, in the ‘Certificates and secrets’ section, create a new client secret and copy it to the clipboard.
- For the new app, in the ‘API permissions’ section, select Microsoft Graph and grant the below Application permissions:
| Calendars.Read | Read the room calendars |
| Calendars.ReadWrite | Read and write reservations users’ calendar |
| Calendars.Read.Shared | Only needed in case strict mode is used The user that will be used needs to be a delegate for the room resource, this is done in the Office portal not the Azure portal. Strict mode: The system is not able to make a reservation directly in the users’ calendar, but the user will be invited. |
| offline_access | For ServiceNow to request Refresh tokens, which are used to request new access tokens when the current one becomes invalidated |
6. Record the Client Secret, Client ID, and Directory ID for use in configurations made in ServiceNow.
Return to Table of Contents
Setting up the Integration in ServiceNow
Install Plugins in ServiceNow
Install the below plugin versions or newer in the following order:
1. Microsoft Exchange Online Spoke (version 3.2.1 or later)
2. IHUB Spoke Util Pack
3. Workplace Calendar Synchronization (version 2.0.4 or later)
If you install Exchange Online Spoke after the Workplace Calendar Synchronization application, please repair the Workplace Calendar Synchronization application before continuing. This step is needed as there are some scripts that the Workplace Calendar Synchronization installation runs only if it finds the MS Exchange Spoke installed.
NOTE: These plugins are in addition to the Workplace Reservation Management application being installed and Rooms configured for making a reservation. We will use demo data for setting up this integration.
Set up Microsoft Exchange Online Spoke in ServiceNow
Next, we will set up the Microsoft Exchange Online Spoke, which is a dependency for this integration. Product Documentation detailing this spoke can be found here.
Register Microsoft Exchange Online as OAuth Provider
- Navigate to All > System OAuth > Application Registry.
- Open the record: Microsoft Exchange Online.
- Change the scope to Microsoft Exchange Online Spoke and update values for fields: Client ID, Client Secret,
Authorization URL (https://login.microsoftonline.com/<Directory-ID>/oauth2/v2.0/authorize),
Token URL (https://login.microsoftonline.com/<Directory-ID>/oauth2/v2.0/token),
Redirect URL (https://<instance-name>.service-now.com/oauth_redirect.do), and Save.
These values should have been obtained from the MS Exchange admin, as noted in the previous step.
Return to Table of Contents
Configure Microsoft Exchange Online_clientCredentials
- All > System OAuth > Application Registry
- Open the record: Microsoft Exchange Online_clientCredentials.
- Change the scope to Microsoft Exchange Online Spoke and update values for fields: Client ID, Client Secret,
Authorization URL (https://login.microsoftonline.com/<Directory-ID>/oauth2/v2.0/authorize),
Token URL (https://login.microsoftonline.com/<Directory-ID>/oauth2/v2.0/token),
Redirect URL (https://<instance-name>.service-now.com/oauth_redirect.do), and Save.
These values should have been obtained from the MS Exchange admin, as noted in the previous step.
Return to Table of Contents
Configure Connection Credentials for MS Graph
- Change Scope to Workplace Calendar Synchronization
- Navigate to: Connections & Credentials > Credentials
- For each of the records MS Graph 1 and MS Graph 2 perform the below steps:
a. Set OAuth Entity Profile to Microsoft Exchange Online_clientCredentials default_profile and save.
b. Click Get OAuth Token Related Link to ensure the connection is successful.
Return to Table of Contents
Create Webhook Registry
Create a webhook registry connection to generate subscriptions for events coming from MS Exchange Resources. These event subscriptions are used to sync up the information being sent from MS Exchange with rooms in ServiceNow.
- Navigate to Microsoft Exchange Online Spoke > Webhook Registry
- Open the record WSDRS Event Subscription.
- Click on the Callback URL UI Action button.
This will refresh the callback URL and Client state values.
NOTE: This step will need to be performed after each clone down since this value needs to be specific to the instance.
Setting up Reservation Synch Configurations in ServiceNow
We will now configure the Workplace Calendar Synchronization application. In the following steps, we configure SN Workplace Calendar Sync application to use Microsoft Graph and the connections previously configured as the external Calendar provider for this integration.
NOTE: As of the current version (Workplace Calendar Synchronization version 2.0.4), only 'Rooms' are synced; workspace records currently do not get synced with MS Calendar or have MS exchange emails sent out.
Create a Calendar Provider
Product documentation can be found here.
- Navigate to Workplace Calendar Synchronization > Calendar Providers > New
- Enter the Name, Sync Start and End times, select Microsoft Graph as the Calendar Processor, and click submit.
If the synchronize past reservation flag is checked, it will bring in historical reservations for the Outlook resources defined in the next steps since the sync start date.
Reservable Sync Configuration
We will now link Rooms in ServiceNow to Resources in MS Exchange through their email addresses.
To achieve this, create a Reservation Sync Configuration record for each MS Exchange Resource and the corresponding room it needs to be synchronized within SN WSD.
As a part of this walkthrough, we will sync three rooms in SN WSD:
These rooms must be defined as resources in Exchange, and we need their resource email addresses.
1.) Open the Calendar Provider we just configured > Related List > Reservable Sync Configurations > New
Alternatively, we can navigate to Workplace Calendar Synchronization > Reservable Sync Configuration > New
2.) Create the reservation sync record by selecting the room, reservable module it should apply to, and the resource's email address.
This step needs to be performed for all rooms.
NOTE: Personalize the list view to include the 'Subscription' column.
Once a reservable sync configuration record is created, a flow will populate the value populate for the 'Subscription' column. This subscription acts as a listener for events on that resource.
To refresh the subscription for all Rooms, uncheck the Active Flag on the Calendar Provider record and save. This will trigger flows to clear out the 'Subscription' field value for all associated 'Reservable Sync Configuration' records.
Check the activate flag and save once all these subscriptions have been cleared out. This will trigger flows to recreate subscriptions for the 'Reservable Sync Configuration' records.
To recreate a subscription for an individual room, deactivate and activate the 'Reservable Sync Configuration' record.
Recreating subscriptions may be needed after repopulating Call back URL in the Webhook registry after a clone down. It may also be needed if SN is not receiving events back from MS Exchange.
The Outlook Calendar sync is now configured for these three rooms.
Any reservation made in SN WSD will flow out and block the resource out in MS Exchange and vice versa.
NOTE: As of the current version (Workplace Calendar Synchronization version 2.0.4), MS Exchange resources with approvals enabled are not supported by the SN WSD sync. The recommendation is to have MS Exchange auto-accept all resource requests if the resource is available.
Starting May 2022 WSD release, the recommendation is to move all approvals to SN WSD, and MS Exchange will continue to auto-accept all resource requests.
In that release, when a user will make a reservation for a resource in MS Exchange, it will be 'Accepted' in Exchange, and it will trigger an approval workflow in SN WSD (if the room is configured to need approval). If approved in WSD, the Exchange resource status stays 'Accepted.' If this reservation request is rejected in WSD, then SN will 'Cancel' the reservation for the MS Exchange.
Properties
The properties used to configure this integration are linked here.
sn_wsd_rsvsync.use_user_default_tz and sn_wsd_rsvsync.use_default_tz can be used to tweak the time zones for the reservation events sent out to MS Exchange.
If the value for the property sn_wsd_rsvsync.use_default_tz is not 'user' or 'building', users will see the events correctly in their outlook calendar, but these outlook events may show a different time zone when these events are opened in Outlook.
Testing: making sure it works
Reservations made in SN Workplace Reservation Management
Room reservations created in ServiceNow sync will create MS Exchange calendar events if there are resources associated with them. These events will show up on the Outlook Calendar of the user who made this reservation.
1.) Identify and impersonate a test user who has their sys_user record email set to an MS Exchange email account and has the Workplace user role.
2.) Make a reservation in one of the rooms configured above; in our case, let's use Dublin.
This will trigger an event to MS Exchange, and the status will be 'Awaiting confirmation.
Once SN gets an event from MS exchange (within minutes), this status is changed to 'Confirmed.'
The user receives an 'Accepted' email for the resource requested (not the times are different since the Outlook time is different from the Building time in WSD).
NOTE: If the status remains 'Awaiting confirmation' long after the user receives an 'Accepted' email from the MS exchange, it points to SN not hearing back from the MS exchange, which may be because of issues with the subscription the calendar sync configuration. We will need to recreate subscriptions as detailed previously.
Return to Table of Contents
Reservations made in MS Exchange
When a resource is booked in Outlook and there is a room associated with it in ServiceNow Workplace Sync configuration, in that case, the booking event will flow over to SN and create a Reservation record.
1.) Using the same test user as above, create a reservation for an Outlook resource synced in SN.
This reservation will flow into SN as a confirmed reservation.
Return to Table of Contents
Cancellations
When an event in MS Exchange that created a reservation in SN gets canceled in Outlook, the associated reservation in ServiceNow also gets canceled.
1.) Cancel the booking event created previously in the Outlook calendar.
2.) The Cancellation event flows over to SN.
Similarly, when a room reservation that was created in SN is canceled in SN, the associated calendar event that was created in MS Exchange is deleted.
NOTE: As of the current app version (Workplace Calendar Synchronization version 2.0.4), SN WSD cannot be used to cancel or edit a resource booking event that was created in Outlook. It will need to be canceled within Outlook, and the Cancellation will flow over to SN and be reflected on the associated reservation as noted above.
Return to Table of Contents
Repeating Reservations made in MS Exchange
Repeating resource bookings created in MS Exchange flow into SN as occurrences for recurring reservations.
1.) Using the same test user as above, create a repeating reservation in the Outlook calendar for one of the resources synced with SN WSD.
2.) Ensure that it creates a series of reservations in SN WSD.
Return to Table of Contents
FAQs
Can I further restrict SN’s access to MS Calendar?
We can configure ‘Strict mode’ on the Calendar Provider record so that all reservations created in WSD that sync with Outlook will be created on behalf of a 'dedicated' reservation account and the employee is invited to that reservation instead of making the reservations directly as the user.
If the option is enabled, employees cannot update or cancel this reservation using the calendar service. They can only make changes using the Workplace Reservation Management application.
This is a more secure setup, as we only have access to that dedicated reservation account, besides the rooms. This mode only affects the reservations created in WSD and reservations created in Outlook will still be created on behalf of the employees themselves.
Setting up Restricted Mode requires certain additional delegate API permissions and additional config on the provider.
Additional fields to be configured on Calendar Provider:
Strict mode: Option to restrict emails so that employees do not directly receive emails. Instead, notifications are sent to a single email address at the organization. The system is not able to make a reservation directly in the users’ calendar, but the user will be invited.
Strict mode email: The email address that is used to create reservations and to receive reservation-related notifications if the Strict mode is enabled. Employees are considered invitees to the reservation.
Additional configuration needed at Room level in MS Office:
As MS Office admin, booking delegates need to be defined for all resources. The delegated user for all resources synched with SN WSD must be the account with the Strict mode email address configured previously.
Additional configuration needed in MS Azure:
Please refer to the app permissions section of Azure configuration steps noted previously.
How do I work with resources that need approvals in MS Outlook?
See details linked in the notes here.
If MS Outlook Booking delegates are required by your organization, then they will need to be turned on for all resources and we can explore using the strict mode as detailed above.
I just cloned my instance, and the integration is no longer working in my lower environments.
See details linked in notes here.
My reservation is stuck in an ‘Awaiting Confirmation’ state.
See details in notes here.
The subject for meetings created in Outlook shows the username as the subject instead of the Event title.
In some instances, the meeting's subject name always changes the organizer's name, after it has been accepted in Exchange and then synced with ServiceNow. Also, private flags are not accepted by Exchange by default. This is a default configuration in Exchange, but this can be changed by the MS Exchange administrator using Windows PowerShell. They would need to change the DeleteSubject, RemovePrivateProperty , and AddOrganizerToSubject Fields to False for all resource mailboxes.
Microsoft currently communicates the following: https://docs.microsoft.com/en-US/exchange/troubleshoot/client-connectivity/calendar-shows-organizer-...
How do we upgrade from version 1.x (non-Spoke) of the Workplace Calendar Synchronization application to version 2.x (using Spoke)?
Please execute the installation in the following order.
1. Install the Exchange Online Spoke
2. Upgrade the Workplace Calendar Synchronization application.
3. Configure the MS Exchange Online Spoke as detailed above.
If you install Exchange Online Spoke after the Workplace Calendar Synchronization application, please repair the Workplace Calendar Synchronization application before continuing. This step is needed as there are some scripts that the Workplace Calendar Synchronization installation runs only if it finds the MS Exchange Spoke installed.
Version 2.0 contains a fix script to migrate the existing provider and sync configuration records. In case the script was not executed correctly, the admin can de-activate (active=false) and activate (active=true) the configuration for the calendar provider to refresh subscriptions as detailed here previously.
How do I control the time zone for the invites sent out to my Outlook calendar?
This can be controlled by properties defined in the Workplace Calendar Synchronization application as detailed previously here.
For reservations created in SN WSD, at what points are events triggered to MS Exchange?
Assuming a valid reservable sync configuration has been set up for these rooms:
- If the room requires approval in SN, an event is sent to MS Exchange when the reservation is ‘approved’. No activity in Outlook when SN reservation is in a status of ‘awaiting approval’ or ‘rejected’.
- For WSD rooms that do not need approval, the event is sent to MS Exchange immediately when the reservation is made.
- An event is sent for Cancellations of room reservations.
@Matt Forder Thank you for the feedback, I have sent over your notes to the docs team for reviewing any gaps that may exist.
Apologies for the broken link - all internal page anchors were broken when Community was re-platformed a couple of months back and it won't let me create internal links anymore.
This is where the link was supposed to take you (it's within the same article):
