Office 365 Calendar Integration: Technical FAQ

The benefits of the SmartRecruiters O365 Calendar integration

SmartRecruiters O365 calendar integration allows recruiting teams to drastically improve the efficiency of one of the most time-consuming and complex workflows in recruiting: interview scheduling. Our calendar integration is used by almost 400 enterprises around the world to save dozens of hours a week for recruiting coordinators, recruiters, and interviewers.

Our integration has two key features that help achieve this efficiency:

looking up availability of colleagues (interviewers) for a particular time slot,
booking rooms/video projectors and other equipment necessary for interviews straight from SmartRecruiters.

Those two tasks, when done without an integration, require coordinators to switch between multiple tabs and make scheduling panel interviews, and especially rescheduling/updating them a very time-consuming task.

Screen Shot 2019-10-23 at 3.58.47 PM.png In addition to the above scope, SmartRecruiters uses our central messaging system to pass and display interviewer responses to interview invites in our system. This is a huge time saver for coordinators/recruiters, as they can have a holistic view of all responses for a certain interview rather than collecting responses one by one in their emails. Below is an example of a full-day interview panel displaying interviewer responses in SmartRecruiters.

Screen Shot 2019-10-23 at 3.59.25 PM.png

What permissions does SmartRecruiters need in order for O365 calendar integration to work?

Office 365 can be integrated in two ways:

Application Permissions - SmartRecruiters will make calls to Graph API as a user that is signed in into the SR system
Delegated Permissions - SmartRecruiters will make calls to Graph API as a user that is authenticated on the Admin page, regardless of the user that is logged in into the SR system.

Permissions Key	Permission Description	Reason
Calendars.ReadWrite	Read and write calendars in all mailboxes	To access Calendar API (create, update, delete, list events). We need "write" type permission to create, update and cancel events in users' calendars.
Directory.Read.All	Read directory data	To access Directory API (list calendar resources, i.e. rooms, projectors, etc.). Resources are returned in Graph API as users, so we need to list users to find resources.

Which APIs does SmartRecruiters call and what data do you receive as a result of those calls?

SmartRecruiters uses Microsoft Graph API to integrate with O365 calendars. Particularly, application use the following three APIs. SmartRecruiters uses minimum data to operate. List below shows all data types that our application may receive but use only minimum data required for certain actions:

Calendar API:

Business Operation	API we call:	Data we use:
Get Event	https://developer.microsoft.com/en-u.../api/event_get	attendees (status, emailAddress)
Get Schedule	https://docs.microsoft.com/en-us/graph/api/calendar-getschedule?view=graph-rest-1.0&tabs=http	start, end, showAs
Create Event	https://developer.microsoft.com/en-u...er_post_events	id, iCalUId
Update Event	https://developer.microsoft.com/en-u...i/event_update	id, iCalUId
Cancel Event	https://developer.microsoft.com/en-u...i/event_delete	-
Accept Event	https://developer.microsoft.com/en-u...i/event_accept	-
Decline Event	https://developer.microsoft.com/en-u.../event_decline	-
Tentatively Accept Event	https://developer.microsoft.com/en-u...tativelyaccept	-
List User's Calendar	https://developer.microsoft.com/en-u...list_calendars	id, name
Get Calendar	https://developer.microsoft.com/en-u...i/calendar_get	id, name

Change notifications (aka Subscriptions, aka webhooks):

Business Operation	API we call:	Data we use:
Create Subscription	https://developer.microsoft.com/en-u..._subscriptions	id, changeTypes, notificationUrl, expirationDateTime
Delete Subscription	https://developer.microsoft.com/en-u...ription_delete	id
Get Subscription	https://developer.microsoft.com/en-u...bscription_get	id
Cancel Event	https://developer.microsoft.com/en-u...ription_update	id, expirationDateTime

Users:

Business Operation	API we call:	Data we use:
List Users (to fetch resources like rooms, projectors, etc.)	https://developer.microsoft.com/en-u.../api/user_list	givenname, surname, displayname, mail

NOTE: SmartRecruiters do not use or store any other Calendar API data.

Which data transfer methods/protocols does SmartRecruiters use?

SmartRecruiters call Microsoft Graph API using Java Client library provided by Microsoft. They wrap all calls into HTTP requests using standard methods (GET, PUT, POST, DELETE) and REST approach.

Do you store any calendar data you receive via API?

We do not store any data related to events or busy periods in the calendars of the users that we receive by calling Microsoft Graph API.

The data we store is:

IDs of calendar events that we create
List of calendar resources, containing:
- Resource ID
- Resource name
ID and name of the calendar user want to create events in
ID of subscription (webhook) we create

What information is displayed on the scheduler when you call the Graph API?

SmartRecruiters calls the Microsoft Graph API to retrieve the only availability of users on the scheduler and this availability, is the 'free' or 'busy' status of each user based on time slots that are available on each users' calendar.

SmartRecruiters does not retrieve any type of event details during this call. And therefore, event details such as the title and the content of the event are not displayed on the scheduler. To learn more details about the actual API call, you can read more on the Microsoft API documentation of get free/busy schedule which is the call we use to retrieve the availability.

Which users' calendar is SmartRecruiters accessing via the API?

We only access calendar of users that are users of SmartRecruiters. If there are other users in your Microsoft O365 calendar that are not SmartRecruiters, we will not retrieve those users' availability as SmartRecruiters will not know these users exist.

How can we control SR access to our calendars (how can we disable integration)?

Our access to Microsoft Graph API can be immediately disabled at any time by using the following methods:

For application permissions:
- By revoking permissions in the Azure portal
- By invalidating credentials for SR application in the Azure portal
For delegated permissions:
- By revoking permissions in the Azure portal
- By invalidating credentials for SR application in the Azure portal
- By invalidating tokens (logging off, changing password) for the account that was used logged in on SR Admin page

NOTE: by doing this, scheduling interviews will stop working and SR assistance will be necessary.

How can I monitor what the SmartRecruiters app does once it is enabled?

Monitoring can be achieved using “Overview” or “Audit logs” tabs in the Azure portal for SR integration application:

What does SmartRecruiters do to ensure system-wide information security?

SmartRecruiters takes information security and privacy very seriously. As a vendor of some of the world’s largest, high growth enterprise organizations, it is critical that we maintain a standard far above that of other competitors.

As a 100% cloud-based system, SmartRecruiters is entirely hosted by Amazon Web Services (AWS) and we rely on AWS KMS encryption. We selected AWS for its proven reliability and security capabilities, that are designed to meet the most rigorous and robust privacy and security needs of some of the world’s most security-sensitive organizations. On behalf of SmartRecruiters, Amazon holds ISO 27001, SOC-2 and NIST certifications.

Independent of Amazon, SmartRecruiters is Privacy Shield self-certified and has passed both third party and customer penetration tests. Separately, we are ISO27001 certified and successfully recertified. We are in the process of obtaining SOC-2 compliance.

Internally, we've created stringent logs, separation of duties so that only specific employees can access certain areas of our product’s data and software, extensive monitoring that tracks all traffic in our product, among other best practices to protect our customer's data.

SmartRecruiters follows internal SDLC guidelines that incorporate mandatory code reviews, automated testing, and verification on pre-prod environments as a part of the code deployment process. We also have a strict production environment access control. Getting access to both code and infrastructure is limited, fully audited and requires formal approval.

Additionally, SmartRecruiters has a security team dedicated to protecting our systems against cyber-attacks and security threats. We believe we offer one of the most comprehensive data security and privacy policies in this space so our customers have the assurances they need to know their data is secure.

Is a ready-only or limited access integration possible?

Read-only or limited access integration is not possible. A ready-only integration prevents SmartRecruiters and the integrated calendar from generating and syncing the interview event (effectively mitigating the value of the integration). Schedule viewing and interview generation works when users are associated with the company account authenticated for integration.

Is calendar integration required?

Customers are not required to use a calendar integration - the feature is provided as a convenience to Hiring Teams.

Customers who wish to use the calendar integration benefits should complete the integration process as outlined.
Customers who do not wish to use the calendar integration feature can still manually create interviews within SmartRecruiters. However, for the interview event to be present in both SmartRecruiters and Microsoft O365, users must create the event in each system separately, with no synchronization between the two.